ESOE to Shibboleth Authentication Delegator Installation Guide

Authors
Bradley Beddoes

Applicable versions
Beta 2

Applicable Shibboleth Versions
Shibboleth 1.3f

Overview

The shibboleth authentication delegator allows the ESOE to accept shibboleth credentials as authoritative sources of authentication for access to the ESOE and its associated applications. Enabling shibboleth however does not mean that all your applications are able to be accessed by clients using this technology to authenticate. By carefully setting authorization policies for your services you can ensure that external clients are only able to access a small subset of services and content within services that you explicitly wish to make available to them.

Shibboleth is a technology used largely within education arenas for federation of identities and to provide access to resources. By combining ESOE with shibboleth your Education partners can access your local content without requiring local accounts. Furthermore you can get trusted attribute data about that client from their institution for use in local provisioning activities.

Preparing Shibboleth Installation

Going through shibboleth deployment is out of scope for this document. We instead point you towards the shibboleth configuration guide at https://spaces.internet2.edu/display/SHIB

For the purposes of ESOE integration you must setup an SP which is protecting the resource https://<yourhostname>/shibdelegator which in turn must be exported to Tomcat using the Mod Jk tomcat connector for Apache. The configuration to do this for Mod Jk is:
# Integrate into ESOE Shibboleth delegator
<Location /shibdelegator>
  AuthType shibboleth
  ShibRequireSession On
  require valid-user
</Location>

JkMount /shibdelegator/* ajp13

Preparing Installation

You need to make a few decisions about your environment before continuing with the delegator installation.

  1. Where will the delegator live host wise? It must be deployed either in the same container as the ESOE itself or on a host that is part of your ESOE subdomain hierachy.
    For example if your ESOE instance is available at https://esoe.company.com you may deploy the delegator on a server accessed by https://shibboleth.esoe.company.com or https://esoe.company.com but not a server accessed by https://shibboleth.company.com. For the shibboleth delegator we recommend that a separate server be used due to added requirements of deploying apache and the shibboleth SP.
  2. Where you intend to run the setup program from. The Shibboleth delegator has an interactive console based process to setup your new delegator instance. It needs read access to both esoe.config and esoeKeystore.ks - Some users may choose to do this on the live ESOE host, we reccomend copying both these files to a work space somewhere and basing access to these copies.

To install create a directory called shibboleth and extract shibdelegator.tar.gz to it.

Run the following command:
java -jar installer.jar Startup
You will then be presented with "Welcome to the Enterprise Sign On Engine, Shibboleth installation process". A series of questions will follow as shown below:
Please enter the ESOE keystore location (eg: ${esoe.data}/config/esoeKeystore.ks):
Please enter the ESOE configuration file location (eg: ${esoe.data}/config/esoe.config): 
Please enter the URL where users will interact with the ESOE shibboleth component (eg: https://esoe.company.com/shibdelegator - must end in shibdelegator):
Please enter the amount of time in years the shibboleth delegator should have a valid key for ESOE communication (eg: 2):
Please enter the directory where you have extracted the shibboleth delegator files to (eg: /home/username/shibdelegator):
Please enter a directory this application can write to (eg: /tmp/openiddelegator):
This will lead to a prompt to ensure everything is correct as below:
Is the following information correct?:
ESOE keystore location: /usr/local/site/esoe/data/core/config/esoeKeystore.ks
ESOE configuration file: /usr/local/site/esoe/data/core/config/esoe.config
Shibboleth URL: https://esoe-tst.qut.edu.au/shibdelegator
Key validity period in years: 2
Location of extracted files: /home/beddoes/0.3.99/shibboleth
Output Directory: /home/beddoes/0.3.99/shibboleth
Yes (Y) / No (N) [N] :Y  
When you're happy enter Y, a N value will allow you to correct mistakes. A Y value will lead to:
*** Configuring your shibboleth delegator please wait....
*** Created keystores...
*** Rendered config...
Completed, files written to /home/beddoes/0.3.99/shibboleth. Copy shibdelegator.war to your tomcat instance, copy created files to ${shibdeleg.data}/config and after backing up your current esoeKeystore.ks replace with the newly generated version.

Configuration

The Shibboleth delegator relies on a Java property called shibdeleg.data. If your running on the same host as ESOE we recommend you point this to a new directory in the same structure as your ESOE files e.g.
You already have /opt/data/core
Create a directory called /opt/data/shibboleth
Set shibdeleg.data to /opt/data/shibboleth

If your running on a different host we recommend you try and mirror the location you store config at as best as possible.

Once shibdeleg.data is setup you should create a sub directory called config. Copy the files shibKeystore.ks and shibdelegator.config which were created in the previous stage to this location.

The next task is replacing esoeKeystore.ks. BEFORE DOING THIS TAKE A BACKUP OF YOUR CURRENT KEYSTORE, infact take 2 and feel extra safe. Copy the new esoeKeystore.ks to esoe.data/config/esoeKeystore.ks over writing the current Keystore.

User interaction

Login

To login to Shibboleth users need a link somewhere to access your Federation WAYF. This redirection is configured as part of your shibboleth SP. All thats required is a basic HTML link that points at your shibdelegator installation such as
<a href="https://shibboleth.esoe.mycompany.com/shibdelegator/login">Login using Shibboleth for Australian Higher Education</a>

The normal shibboleth SP interaction then takes over from that point doing WAYF access and remote IDP communication. Note it must point at /shibdelegator/login not just vanilla /shibdelegator

If in fact you wanted to participate in multiple federations you could deploy multiple Shibboleth SP's which have membership in each and simply provide multiple links.

Acceptance of attribute release

Users of the shibboleth system must accept to release attributes about themselves before they are able to continue with a successful shibboleth authentication. The content which is displayed at this stage is stored in your shibdelegator.war file. To customize it simply edit the page border-template.htm

You may place any HTML content to match your environment you wish to. however the following sections must be retained:

<head>
$imports
#if ($headInclude)
#parse($headInclude)
#end

<!-- add your head content if needed -->

</head>

and with the body you must keep the code:
 #parse($path)

where you wish the main content to appear.

We recommend you keep a copy of this customization as it will need to be re-applied after performing updates. We also recommend you rebuild the shibdelegator.war file at this time to save any loss of data on container restart.

Deployment

You should now be able to successfully copy your openiddelegator.war to your containers webapps directory and restart your container. You will also need to restart the ESOE container if its hosted elsewhere to pickup the change in keydata.

By attempting to access protected SPEP resources, being redirected to the ESOE login portal and then clicking on the Shibboleth federation link created above you should be able to login to your systems using remote shibboleth credentials successfully.

Logging

If you require assistance in debugging a problem the shibboleth delegator uses log4j to provide output. You can access it by adding to your logging environment configuration similar to the following:
    <logger name="com.qut.middleware.delegator.shib">
        <level value="DEBUG" />
        <appender-ref ref="esoe-shib-logger" />
    </logger>

    <appender name="esoe-shib-logger" 
        class="org.apache.log4j.FileAppender">
        <param name="File" value="${shibdelegator.data}/logging/shib.log" />
        <layout class="org.apache.log4j.PatternLayout">
            <param name="ConversionPattern" value="%d %-5p %c - %m%n" />
        </layout>
    </appender>

Feedback

We aim to continually improve this documentation set to make it as easy as possible for new users and seasoned users alike to setup Shibboleth integration. We welcome any comments or additions you may have on the ESOE users mailing list at any time.