NAME

SecurityModule.pm - Web Security Module


SYNOPSIS

Note: This applies specifically to the MySQL implementation. There is also a SecurityModule::SQLite implementation.

  use SecurityModule::MySQL;
  $sec = new SecurityModule::MySQL({CALLER_URL => $myurl,
                                    CONFIG => "/etc/sec/SecMod.conf";
                                    LOGLEVEL => 5,
                                    KEYVALIDTIME => 7200,
                                    PWDFORM_HANDLER => \&myPasswordForm
                                   });
  $ret = $sec->init(); # returns 0 in case of failure
  $errmsg = $sec->getErrMsg(); # returns error message
  # if getCookie() returns a defined value, your page needs to make
  # sure that this cookie will be set using CGI.pm's
  # header(-cookie => $cookie ) command
  if( ($cookie=$sec->getCookie) ) {
    print header(-cookie => $cookie );
  } else {
    print header();
  }
  # Access to authentication / authorization information
  $state = $sec->getAuthnState(); # returns (failed | cert | passwd)
  $user_dn = $sec->getDN(); # returns user's distinguished name
  $roles = $sec->getRoles(); # returns a hash of roles, each role mapping to a
                             # list of scopes
  # Protecting functions: reqAuthnCert() and reqAuthnPasswd()
  sub my_certificate_protected_function {
    $sec->reqAuthnCert();
    ...
  }
  sub my_password_protected_function {
    $sec->reqAuthnPasswd();
    ...
  }


DESCRIPTION

The SecurityModule handles authentication and authorization to a web site. Users are identified by a certificate loaded in their browser or by a previously set cookie that was issued upon a successful password authentication.

Certificate based authentication is the strongest authentication type, so functions protected by the reqAuthnPasswd() method will allow access to certificate authenticated users, but reqAuthnCert() will deny access to password authenticated users.

The SecurityModule was written for a setup where a remote Proxy mediates access to a number of backend servers. The remote proxy handles the SSL authentication and is required to set the following request headers to the values of the respective environment variables for this request:

SSL_CLIENT_VERIFY, SSL_CLIENT_S_DN, HTTPS.

On the backend servers these must be available as environment variables of identical names except for the prefix HTTP_, e.g. HTTP_SSL_CLIENT_S_DN.

Since all backend servers are hidden behind the reverse proxy, an authentication cookie is set restrictively to only be sent back to the issueing server. The necessary translation for the proxy is handled transparently by apache's mod_proxy module (needs >= apache-2.2).

The SecurityModule can also be run without a reverse proxy in pure SSL mode if the REVPROXY directive is left out or set to 0.

Initialization

Arguments which can be passed to the constructor:

Convenience Functions for condition tests

these functions can be used to formulate conditions easily

Functions to retrieve user information

These functions can be used to retrieve additional information about a user

Calling the password form via a web page 'Login' link:

You can pass SecModPwd=1 as a GET variable to any page using the SecurityModule. This will call the handler for / redirect to the password form and insure that the user can return to the same page (the original page will be encoded in the caller_url parameter)


AUTHOR

Derek Feichtinger <derek.feichtinger@psi.ch>

CMS web interfaces group <hn-cms-webInterfaces@cern.ch>


ISSUES / TODO

List of issues to resolve: