ESOE to OpenID Authentication Delegator Installation Guide

Authors
Bradley Beddoes

Applicable versions
Beta 2

Overview

The OpenID authentication delegator allows the ESOE to accept openID credentials as authoritative sources of authentication for access to the ESOE and its associated applications. Enabling OpenID 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.

OpenID is largely an untrusted technology, anyone can create an OpenID for themselves, you should carefully consider where it makes sense to trust this technology. Some examples to date have been applications which would otherwise allow anonymous sign up and/or access anyway such as shopping carts and collaborative tools such as wiki's where everyone is allowed to participate but you need some kind of identifier to track comments and edits.

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://openid.esoe.company.com or https://esoe.company.com but not a server accessed by http://openid.company.com
  2. Where you intend to run the setup program from. The OpenID 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 openid and extract openiddelegator.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, OpenID 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 OpenID component (eg: https://esoe.company.com/openiddelegator - must end in openiddelegator):
Are you deploying the delegator in a https offloaded, load balanced environment (n): n
Please enter the amount of time in years the openID delegator should have a valid key for ESOE communication (eg: 2): 2
Please enter the directory where you have extracted the openid delegator files to (eg: /home/username/openiddelegator): 
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
OpenID URL: https://esoe-tst.qut.edu.au/openiddelegator
Key validity period in years: 2
Location of extracted files: /home/beddoes/0.3.99/openid
Output Directory: /home/beddoes/0.3.99/openid
Yes (Y) / No (N) [N] :    
When you're happy enter Y, a N value will allow you to correct mistakes. A Y value will lead to:
*** Configuring your openID delegator please wait....
*** Created keystores...
*** Rendered config...
Completed, files written to /dir. Copy openiddeleg.war to your tomcat instance, copy created files to ${openiddeleg.data}/config and after backing up your current esoeKeystore.ks replace with the newly generated version.

Configuration

The OpenID delegator relies on a Java property called openiddeleg.data. If your running on the same host as ESOE we reccomend 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/openid
Set openiddeleg.data to /opt/data/openid

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

Once openiddeleg.data is setup you should create a sub directory called config. Copy the files openidKeystore.ks and openiddelegator.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

Obviously to login using OpenID your users need somewhere to enter their domain details. We recommend this be accessible from your default login environment. You'll notice the default supplied web war has a space for this on the front page. Other implementors have chosen to have a link from the main page to a dedicated openID page. Regardless of the choice the requirements are the same. a Simple HTML form which looks like the following:
<form method="post" name="openidAuthenticator" action="/openiddelegator/login" id="esoe_login_form" autocomplete="off">

<input type="text"    name="openid_identifier" value="http://" id="openid_identifier">

<input type="submit" value="Login">

You may need to change the action target if the openID delegator does not run on the same host as your web application. Of course your also free to add any kind of fancy styling identifiers you wish. However the names of the form and elements are important and must be maintained as is.

Acceptance of attribute release

Users of the openID system must accept to release attributes about themselves before they are able to continue with a successful openID authentication. The content which is displayed at this stage is stored in your openiddelegator.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 openiddelegator.war file at this time to save any loss o 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 using your openID form created above you should be able to login to your systems using your openID successfully.

Logging

If you require assistance in debugging a problem the openID 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.openid">
        <level value="DEBUG" />
        <appender-ref ref="esoe-openid-logger" />
    </logger>

    <appender name="esoe-openid-logger" 
        class="org.apache.log4j.FileAppender">
        <param name="File" value="${openiddelegator.data}/logging/openid.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 openID integration. We welcome any comments or additions you may have on the ESOE users mailing list at any time.

Also available in: HTML TXT