Enabling SAML2 for end services

This is a short guide to provide service operators and developers with information about how to enable support for federated authentication and SSO using SAML.

The guide assumes that the reader is familiar with the terminology and concepts of federated AAIs. It targets at Service providers, i.e. operators of services exposed via web that consumes decisions that Identity providers issue with information about the user. To get more information on the principles you can refer to AARC's Training material on main technical and policy concepts of federated access and Training material targeted to Resource and Service Providers.

In order to provide support for SAML2 on your servers you need to

1. Enable the SAML2 technology on the service,
2. Register the service with an IdP and/or federation(s) of IdPs.

The guide is tailored to utilization of the West-Life SAML Idp-SP-Proxy service.

Enabling SAML2 technology

There are basically two possibilities to enable support of SAML2, it can be configured on level of either application or web server/container. The former requires changes to the application code base, the latter requires reconfiguration of the web server.

Major current web frameworks and/or languages are well supported to enable SAML2. SimpleSAMLphp is a widely used application covering SAML2. Details on SP installations and integration with an application are available from the documentation. PySAML provides a similar support for Python. In most cases, however, it is easier to configure SAML support on the level of Apache so that the application does not need to deal with SSO details.

Enabling SAML2 in Apache

There are two modules widely in use, mod_shib and mod_mellon. The mod_mellon is simpler but covers sufficiently what is needed for West-Life services so we use it as a reference installation.

Instructions on how to configure end service with Apache's Mellon module

These instructions will provide a basic configuration of Apache's Mellon module to work with the West-Life SAML Proxy and process users' attributes.

Before you start, make sure you have correctly installed and configured Apache server on your machine.

Install and configure mod_auth_mellon

Proceed to install mod_auth_mellon for Apache. Major Linux distributions provide proper packages so please follow the standard procedures, e.g.

apt-get install libapache2-mod-auth-mellon

After the module is installed, you have to add proper configuration to Apache configuration files. For full documentation of the setup you can refer to the module documentation, the minimal configuration for West-Life is described below. The configuration should look like following:

You need to create a specification for the directory you want to protect.

<Location "/" >
        MellonSPPrivateKeyFile /etc/apache2/mellon/sp_key.pem
        MellonSPCertFile /etc/apache2/mellon/sp_cert.pem
        MellonSPMetadataFile /etc/apache2/mellon/sp-metadata.xml
        MellonIdPMetadataFile /etc/apache2/mellon/idp-metadata.xml
        # Mapping of attribute names to something readable
        MellonSetEnv "name" "urn:oid:2.16.840.1.113730.3.1.241"
        MellonSetEnv "mail" "urn:oid:0.9.2342.19200300.100.1.3"
        MellonSetEnv "eppn" "urn:oid:1.3.6.1.4.1.5923.1.1.1.6"
        MellonSetEnv "entitlement" "urn:oid:1.3.6.1.4.1.5923.1.1.1.7"
        MellonSetEnv "eduPersonUniqueId" "urn:oid:1.3.6.1.4.1.5923.1.1.1.13"
</Location>
<Directory "/var/www/something/protected">
        AuthType Mellon
        MellonEnable "auth"
        Require valid-user
</Directory>

In the configuration snippet above there are credentials and metadata files that have to also be prepared during the configuration phase. The files are placed in the /etc/apache2/mellon/ directory that needs to be created first. You need to provide the following:

• SP private key and certificate (MellonSPPrivateKeyFile and MellonSPCertFile)
  • These credentials are only used to communicate between the Proxy and SP using SAML and XML. It's not exposed to user and not related to the HTTPS credentials used by Apache to protect the web communication. The private key file should be only readable for root.
• SP metadata XML (MellonSPMetadataFile)
  • The file contains a information necessary to locate the SP endpoints and communicate with them. The metadata will have to be communicated to the Proxy operator later.
• IdP metadata XML (MellonIdPMetadataFile)
  • The file contains the description of the Proxy, it is available directly from the Proxy service.

There is a helper script that can be used to generate the SP key, certificate and SP metadata.

mellon_create_metadata.sh <entity ID> <endpoint>

• entity ID is a unique identifier of the service, it is usually derived from the URL, e.g. https://sp.example.org/west-life
• endpoint is the entry point for SAML protocol, e.g. urn:https://sp.example.org/mellon (if you followed the configuration above)

It is advisable to check the generated metadata and provide more details about the service. The outcomes should place on proper places referred to by the Mellon configuration, make sure the private key is cannot be read by anyone but root.

The IdP metadata file can be obtained from https://auth.west-life.eu/proxy/saml2/idp/metadata.php and place in a file pointed to by MellonIdPMetadataFile (TODO: renewal).

Send your metadata to West-Life Proxy

You can find metadata of your SP on https://example.com/mellon/metadata. Check if the link is correct, and send it to westlife-aai@ics.muni.cz. N.B. For the pilot environment we do not require any paper work.

Test your setup

Once the SP metadata has been enabled on the Proxy, you can check how it works. When you go to https://example.com/endpoint, you are redirected to IdP. After entering your credentials and being authorized on IdP's side, you are redirected back to https://example.com/endpoint and now can see the hidden content.

Integrate application

With the configuration above, the application doesn't need to deal with any authentication, it could also have the Proxy performed authorization based on group membership.

The applications will receive a list of following attributes

• eduPersonUniqueId
  • a unique id for the user (i.e. all users have different values)
• eduPersonPrincipalName
  • set to be the same as eduPersonUniqueId
• eduPersonEntitlement
  • a list of groups that the user is member of (i.e. might be multi-valued)
• displayName
  • A human-readable form of the user's name
• mail
  • User's mail address

An application may just consume the attributes like this:

<h2 align="center"><p>You have been successfully logged in.</p></h2>
<p align="center">Your name: <?php echo $_SERVER['MELLON_name'];?></p>
<p align="center">Your email: <?php echo $_SERVER['MELLON_mail'];?></p>
<p align="center">Your id: <?php echo $_SERVER['MELLON_eppn'];?></p>
<p align="center">Your groups:
<?php
for ($i = 0; ; $i++) {
    $var = 'MELLON_entitlement_' . $i;
    if (array_key_exists($var, $_SERVER) == false)
        break;
    if ($i > 0)
        print (", ");
    print($_SERVER[$var]);
}
?>

West-Life AAI login button

Using West-Life proxy as IdP, you can place one of these buttons on your website to log in into your service.

• Small .png buttons 130x58px:

• Medium .png buttons 300x123px:

• SVG files:

Contact

Any comments or questions can be sent to westlife-aai@ics.muni.cz.