Summary

This document will guide you through the steps to enable multi-factor authentication and Single-Sign On for web based applications with header enrichment using Shibboleth SP.

System Requirements

• PhenixID Authentication Server 2.0 or higher
• Apache HTTP server installed.
• The Apache HTTP server must be reached from clients and IDP over HTTPS (443).

Instruction

Overview

This document will guide you through the steps to enable multi-factor authentication and Single-Sign on for header aware web applications.

If the application to secure is not implemented on the same HTTP server as Shibboleth, the Apache HTTP Server must be configured as a Reverse Proxy to redirect the user to the application web server.

If the Apache HTTP Server is implemented on a DMZ the Reverse Proxy function can enable external access to internal web applications with strong authentication.

PhenixID Authentication Server acting as SAML IdP

1. Setup PhenixID Authentication Services as a SAML IdP using one of the Federation scenarios described here. (If the desired authentication method is not provided by a scenario, use the documentation for the SAML authenticator here)
2. Use sAMAccountName as Name ID attribute. (If not using AD, please consult PhenixID for configuration assistance).
3. Verify your SAML IdP metadata by going to the URL:
   https://<YourServerDomainName>/saml/authenticate/<authenticator_alias>?getIDPMeta
   If needed, download the metadata to a xml file.

Configure Shibboleth SP

Install Shibboleth SP

Download and install Shibboleth SP from http://shibboleth.net/downloads/service-provider/

Configure Apache HTTP

The changes needed in the apache httpd.config are:

1. Loading the shib sp module
   Linux: LoadModule mod_shib /usr/lib64/shibboleth/mod_shib_24.so
   Windows: LoadModule C:/opt/shibboleth-sp/lib64/shibboleth/mod_shib_24.so
2. Adding location directive (path that should be protected by shibboleth)
   <Location /[path to application]/>
   AuthType shibboleth
   ShibRequestSetting requireSession 1
   require valid-user
   ShibUseHeaders On
   </Location>
   # Enable Shibboleth to handle all links that starts with /Shibboleth.sso
   # Must be added if Apache also is configured as a reverseProxy
   <Location /Shibboleth.sso>
                   SetHandler shib
   </Location>In a ReverseProxy environment, the [path to application] must be the same as the ProxyPass and ProxyPassReverse [path]
3. Save the configuration and restart Apache

Configure Shibboleth SP

Change EntityID of the SP and allow the IDP

1. Open shibboleth2.xml
   Linux: /etc/shibboleth/shibboleth2.xml
   Windows: C:\opt\shibboleth-sp\etc\shibboleth\shibboleth2.xml
2. Change entityID.
   <ApplicationDefaults entityID=”<any_string_of_your_choice>” REMOTE_USER=”eppn”>Best practice for setting the entityID value is to use ”https://<domain>/shibboleth”
3. Find the <SSO part in the file and add your IDP to allowed IDP
   <SSO entityID=”<EntityID of your IDP>”>
     SAML2
   </SSO>

Attribute mapping

The file attribute-map.xml in the same folder as shibboleth2.xml controls which SAML assertion attributes should be added as http headers.

1. To add an attribute mapping, simply add this to the file.
   <Attribute name=”<attribute_name_in_attribute_statement_of_saml_assertion” id=”target_http_header_name”>
           <AttributeDecoder xsi:type=”StringAttributeDecoder” caseSensitive=”false”/>
   </Attribute>Example:<Attribute name=”sAMAccountName” id=”userid”>
           <AttributeDecoder xsi:type=”StringAttributeDecoder” caseSensitive=”false”/>
   </Attribute>
2. Save the file.
3. Restart shibboleth sp.

Metadata exchange

Import metadata to Shibboleth SP

1. Add the IDP metadata to shibboleth2.xml
   Linux: /etc/shibboleth/shibboleth2.xml
   Windows: C:\opt\shibboleth-sp\etc\shibboleth\shibboleth2.xml
2. Add a new metadata provider. Place under current metadata providers defined.
   <MetadataProvider type=”XML” uri=”https://<YourServerDomainName>/saml/authenticate/<authenticator_alias>?getIDPMeta” reloadInterval=”7200″>
   </MetadataProvider>
   
3. Save file
4. Restart Shibboleth SP

Import metadata to IdP

1. Open PhenixID Configuration Manager and login
2. Go to Scenarios->Federation
3. Click the plus next to SAML Metadata upload
4. Enter a display name = “Shibboleth SP”
5. Use this URL to retrieve the Shibboleth SP SAML 2 metadata xml:
   https://<shibboleth_server>/Shibboleth.sso/Metadata

Test

1. Browse to https://<shibboleth_server>/[path to application]/
2. This should result in a redirect to PhenixID Authentication server
3. Authenticate
4. If authentication was successful, a redirect to application should occur (with SAML assertion converted to header attributes)
5. The user should now be logged in.

Verify

Check which headers are forwarded to the Federation application
https://<shibboleth_server>/Shibboleth.sso/Session

If you want to see the content of the attributes, change the parameter showAttributeValues in shibboleth2.xml to true.

Addenum

The instruction shows how to implement Shibboleth on a Apache HTTP server.
It is possible to do the same configuration using a Microsoft IIS Web Server.