wiki:ndg_security/Installation/RelyingPartyAuthenticationServices

Relying Party Authentication Services

This denotes authentication services used to secure a given application. A paster template, ndgsecurity_relyingparty_authn_services is used to create the configuration for them. They are used in conjunction with the Secured Application template, ndgsecurity_securedapp. This creates an INI file configuration for an application fronted by security filters. One of these, the authentication enforcement filter, intercepts requests and triggers the authentication process. Since authentication may be carried out over SSL, a separate application is needed to handle these listening with HTTPS. This is where this application comes into play. authentication enforcement filter sets a HTTP redirect to redirect the client to the Relying Party Authentication Services are hosted in this application. They support SSL client based authentication and OpenID based sign in. Once the authentication process is complete, a HTTP redirect is set to return the client back to the secured application.

Steps assume root privileges.

Create virtualenv

  1. Install virtualenv:
    $ pip install virtualenv
    
  2. Create a virtualenv for the relying party:
    $ virtualenv /usr/local/ndg-security-relying-party
    
  3. Add virtualenv bin directory to path to pick up respective python executable and related scripts:
    $ . /usr/local/ndg-security-relying-party/bin/activate
    
    The shell prompt should change to display (ndg-security-relying-party) prefix.

Set-up Security Packages

  1. Install the required packages:
    $ pip install -f http://ndg.nerc.ac.uk/dist/ ndg_security_server ndg_security_test Genshi
    
    Nb. the --proxy setting may be needed if a site-wdie http proxy is in place.

Set-up Configuration Files

  1. Create configuration using the special paster template:
    $ cd /usr/local/ndg-security-relying-party
    $ paster create -t ndgsecurity_relyingparty_authn_services
    
    Enter the required information when prompted accepting defaults if acceptable. For the project name, entering 'etc' will set-up the configuration files in a etc sub-directory under /usr/local/ndg-security. Note the value for authkitCookieSecret.
    Enter authkitCookieSecret (Cookie secret for AuthKit authentication middleware.  
    This value *MUST* agree with the one used for the ini file of the application 
    to be secured - see ndgsecurity_securedapp template) ['Lsh9EIvPQuYPR7aREkaC4oiQQ9']:
    
    Other applications are secured with the Relying Party Authentication Services created here. To do so, they're configured with Secured Application template. This also has a prompt for authkitCookieSecret. The value chosen MUST agree with the value used here otherwise authentication will fail.
  2. Set PKI trust settings for SSL client authentication filter. Edit the ini file generated authenticationservices.ini, and find the section, [filter:SSLClientAuthenticationFilter]. Comment out the ssl.caCertFilePathList and ssl.clientCertDNMatchList parameters. The first setting is applied in the Apache configuration using the equivalent SSLCACertificatePath directive. the latter is applied by the authorisation filter. If desired, the Apache SSLRequire directive can be used to specify a given certificate subject name or subject name pattern.
    # Apply verification against a list of trusted CAs.  To skip this step, comment
    # out or remove this item.  e.g. set CA verification in the Apache config file.
    #ssl.caCertFilePathList = %(testConfigDir)s/pki/ca/d573507a.0
    
# Apply whitelisting of client certificate DNs.  This should never be needed in
# this context.  The only reason to use it might be as a means to set a crude
# access control list of DNs
#ssl.clientCertDNMatchList = /O=NDG/OU=BADC/CN=mytest /O=gabriel/OU=BADC/CN=test /O=NDG/OU=BADC/CN=test

Configure WSGI script

  1. Create script in Apache scripts area (/var/www is assumed here but it may vary between Linux distributions) to load and run the application:
    $ cat > /var/www/wsgi_scripts/ndg_security_relyingparty_authn_services.wsgi
    #
    # NDG Security Relying Party Authentication Services WSGI Script
    #
    # This application provides SSL client and OpenID based authentication for 
    # secured applications running on this host.
    #
    # P J Kershaw 27/05/11
    import site
    site.addsitedir('/usr/local/ndg-security-relying-party/lib/python2.6/site-packages')
    
    from paste.deploy import loadapp
    from paste.script.util.logging_config import fileConfig
    
    configfile="/usr/local/ndg-security-relying-party/etc/relyingparty_authn_services/authenticationservices.ini"
    fileConfig(configfile)
    application = loadapp("config:" + configfile)
    
  2. If not already done, create a new system account and group to run the Apache mod_wsgi processes
    $ groupadd ndgsecurity
    $ useradd -r -g ndgsecurity -c "NDG Security system account" ndgsecurity
    
    Nb. this step is not essential, it may be preferable to run the WSGI script under the default Apache user/group.
  3. Create Python egg cache directory:
    $ mkdir /var/www/wsgi_scripts/.ndg-security-python-eggs
    $ chown ndgsecurity:ndgsecurity /var/www/wsgi_scripts/.ndg-security-python-eggs
    
  4. Edit SSL config file /usr/local/apache2/conf/extra/httpd-ssl.conf and make settings (Ref: wiki:ndg_security/Installation/Apache2#SSLConfiguration)
  5. Make an entry to set up daemons and mount the script:
    	# NDG Security WSGI Set up
            WSGIDaemonProcess ndg-security processes=2 threads=15 display-name=%{GROUP} python-eggs=/usr/local/apache2/wsgi-scripts/.ndg-security-python-eggs user=ndgsecurity group=ndgsecurity
            WSGIProcessGroup ndg-security
            WSGIScriptAlias / /usr/local/apache2/wsgi-scripts/ndg_security_relyingparty_authn_services.wsgi
    
    Nb. user and group settings to WSGIDaemonProcess can be omitted if preferred in which case the process will run as the default Apache user/group (apache:apache for RedHat?).
  6. Restart Apache2:
    $ apachectl restart
    
    Nb. invocation may vary with distributions e.g. service httpd restart
  7. Test the sign in endpoint:  https://<fqdn>/verify and troubleshoot by examining the SSL error log.

Troubleshooting

  1. M2Crypto may not build on RedHat systems. It's possible to install a yum package for this. In this case, the virtualenv should be created with the --system-site-packages option so that the M2Crypto package can be picked up from the global system Python installation area. Alternatively, to install local to the virtualenv, download the M2Crypto tarball from PyPI ( http://pypi.python.org/pypi/M2Crypto/) and unpack it. Then use the special build script from within the package directory:
    $ ./fedora_setup.sh build
    $ ./fedora_setup.sh install
    $ ./fedora_setup.sh test
    
    The script may need execute permissions adding to it (chmod +x ./fedora_setup.sh).
  2. Again, on RedHat systems and perhaps some others too, there can be problems with writing out the WSGI socket file because of restrictive permissions. A client request will return a HTTP 503 error message and the Apache log will show something like:
    Permission denied: mod_wsgi (pid=2730): Unable to connect to WSGI daemon process 'ndg-security' on '/etc/httpd/logs/wsgi.2687.0.1.sock' after multiple attempts.
    
    Add this directive to the Apache configuration outside of any VirtualHost directive:
    WSGISocketPrefix /var/run/wsgi
    
    Ref:  http://code.google.com/p/modwsgi/wiki/ConfigurationIssues#Location_Of_UNIX_Sockets