VI-SEEM AAI mod auth mellon Integration

From VI-SEEM Wiki
Jump to: navigation, search

Introduction

This page describes how to integrate VI-SEEM AAI login support (as SAML Identity Provider - IdP) into generic web application running under Apache web server using mod_auth_mellon module acting as the Service Provider (SP).

For the demonstration needs, we are using somesite.vi-seem.eu as the site name and web application is located at /var/www/project.

Apache Settings

Before any changes, one should visit VI-SEEM Login integration guide for Service Providers to get the the basic picture. Also useful reading is mod_auth_mellon Generic Setup.

After the SP has successfully exchanged the metadata with VI-SEEM AAI as described here (SP metada will be accessible at https://somesite.vi-seem.eu/saml2/metadata) there are some changes needed to configuration:

First, we need to get the metadata XML file:

/usr/bin/wget https://aai.vi-seem.eu/proxy/saml2/idp/metadata.php -O /etc/apache2/mellon/idp.xml

Then we nedd to adapt our HTTPS site configuration (for example, other sites / configuration files can alsobe used):

/etc/apache2/sites-enabled/default-ssl.conf
<VirtualHost _default_:443>
# ... generic setup for virtual host ...

	SSLCertificateFile      /etc/ssl/somesite.vi-seem.eu.crt
	SSLCertificateKeyFile /etc/ssl/somesite.vi-seem.eu.pem
	# ^ these are the private key and the ceritificate of the server

	<Location />
		MellonEnable "info" 
		# ^ We want to provide our application with user information if it exists, if not - still run normally

		MellonEndpointPath "/saml2"
		MellonDefaultLoginPath "/"
		MellonSessionLength 8640000
		MellonSPentityId "https://somesite.vi-seem.eu/saml2/metadata"
		MellonOrganizationName "en" "VI-SEEM"
		MellonOrganizationDisplayName "en" "VI-SEEM Consortium"
		MellonOrganizationURL "https://vi-seem.eu/"

		MellonSPPrivateKeyFile /etc/ssl/somesite.vi-seem.eu.pem
		MellonSPCertFile /etc/ssl/somesite.vi-seem.eu.crt

		MellonIdPMetadataFile /etc/apache2/mellon/idp.xml 
		MellonIdPPublicKeyFile /etc/ssl/aai.vi-seem.eu.crt
		# ^ these are the private key and the ceritificate of the server, same as before

		MellonUser "urn:oid:1.3.6.1.4.1.5923.1.1.1.13"

		MellonSetEnv "eduPersonUniqueId" "urn:oid:1.3.6.1.4.1.5923.1.1.1.13"
		MellonSetEnv "eduPersonPrincipalName" "urn:oid:1.3.6.1.4.1.5923.1.1.1.6"
		MellonSetEnv "eduPersonTargetedID" "urn:oid:1.3.6.1.4.1.5923.1.1.1.10"
		MellonSetEnv "displayName" "urn:oid:2.16.840.1.113730.3.1.241"
		MellonSetEnv "givenName" "urn:oid:2.5.4.42"
		MellonSetEnv "sn" "urn:oid:2.5.4.4"
		MellonSetEnv "mail" "urn:oid:0.9.2342.19200300.100.1.3"
		MellonSetEnv "eduPersonScopedAffiliation" "urn:oid:1.3.6.1.4.1.5923.1.1.1.9"
		MellonSetEnv "eduPersonAssurance" "urn:oid:1.3.6.1.4.1.5923.1.1.1.11"

		MellonSamlResponseDump Off
		MellonSessionDump Off
	</Location>

	<Location /login>
			AuthType "Mellon"
			MellonEnable "auth"
			# ^ We want to require the user to log in before giving access to this directory
	</Location>

	<Location /guest>
			AuthType "Mellon"
			MellonEnable "off"
			# ^ We don't want auth for this directory
	</Location>

# ... rest of generic setup ...
</VirtualHost>

This setup configures VI-SEEM AAI as IdP and requires user to be logged in in order to access /login, will provide user data if it exists when the user accesses / (site root) and will ignore auth for /guest access.

Settings for osTicket Integration

We want to preserve the possibility to log in via local username/password pairs as well as via VI-SEEM AAI login for agents handling the tickets.

One possible way to achieve this is by installing and enabling auth-passthru plugin from osTicket plugin repository.

This plugin expects the web server to authenticate the user and set REMOTE_USER variable to username. Due to support for various other external methods, osTicket will strip off anything after the @ character in username, so for user with email someone@somesite.edu osTicket will see just someone as username.

Also important is to set Authentication Backend to Any Available Backend when creating user.

Changes to original apache configuration are:

        MellonDefaultLoginPath "https://osticket.domain.tld/scp"
        MellonUser "urn:oid:0.9.2342.19200300.100.1.3"
        MellonSetEnvNoPrefix "REMOTE_USER" "urn:oid:0.9.2342.19200300.100.1.3"

        <Location /login-agent>
                        AuthType "Mellon"
                        MellonEnable "auth"
        </Location>

In /login-agent directory we can put a redirect to /scp (either via apache, HTML or PHP).

In order to have a link that takes the user to VI-SEEM Login we put link to /login-agent in desired place in page template (client pages are in include/client and agent pages are in include/staff).

In order to enable for logging-out we need to log out twice - from AAI and from local level. This is done by inserting following PHP code in desired page (for example include/staff/header.inc.php):

<a href="https://osticket.domain.tld/saml2/logout?ReturnTo=https://osticket.domain.tld/scp/logout.php?auth=<?php 
echo $ost->getLinkToken(); ?>" class="no-pjax"><?php echo __('VI-SEEM Log Out'); ?></a>

This has an effect of logging the user out from AAI and returning the user to local logout URL which will then redirect to login page.

Troubleshooting

Lasso version

This module uses Lasso library which has to be at least version 2.5 to handle SHA256. Ubuntu 14.04 uses 2.4 branch in default repositories so one should either upgrade to Ubuntu 16.04 or newer or install version 2.5 from other source.

System Time

The thing that can cause many problems is the discrepancy between the clock at IdP and SP. One should configure NTP on the server if it's not already configured.

Python WSGI Application shows other users logged in

If the configuration file conatins

<IfModule mod_ssl.c>
  <VirtualHost _default_:443>

# ... generic settings

    WSGIDaemonProcess application user=webuser group=webuser threads=5 python-path=/var/www/project/
    WSGIScriptAlias / /var/www/project/application.wsgi
    <Directory /var/www/project>
           WSGIProcessGroup application
           WSGIApplicationGroup %{GLOBAL}
           Order deny,allow
           Allow from all
    </Directory>

# ... other settings 

  </VirtualHost>
</IfModule>

One possible solution is to change it to

<IfModule mod_ssl.c>
  <VirtualHost _default_:443>
# ... generic settings

    WSGIScriptAlias / /var/www/project/application.wsgi
    <Directory /var/www/project>
           Order deny,allow
           Allow from all
    </Directory>

# ... other settings 

  </VirtualHost>
  WSGIPythonPath /var/www/project/
</IfModule>