SimpleSSO Installation Guide

This document outlines how to configure a Java application server with the SimpleSSO components, configure a SSO provider and secure a web application.

Solution overview

Single sign on is a mechanism whereby a user authenticates against a central directory and is provided with an access token which is subsequently used as credentials in one or more applications. Many organizations have existing single sign on solutions based around non-Java technology. The SimpleSSO solution is a light, flexible Spring-based architecture to enable Java applications to participate in an existing SSO infrastructure.

Outline

There are three steps to setting up a SimpleSSO solution.

Installing SimpleSSO in your application server

Deploying SimpleSSO to Tomcat 5.5

The standard SimpleSSO build operates against catalina.jar from Tomcat 5.5 and is incompatible with Tomcat 5.0 and below.

Installing SimpleSSO and its dependencies

The following files need to be placed in {CATALINA_HOME}/server/lib:

The following files need to be placed in {CATALINA_HOME}/common/lib:

Enabling SimpleSSO in the web application context

The web application context file is used to configure Tomcat components for a specific web application. In Tomcat 5.5 the name of the context xml file is the path to your web application. The file should be created in {CATALINA_HOME}/conf/Catalina/localhost/myapp.xml by default. Here is an example configured to use Lotus Domino SSO cookies:

Installing the sssoContext.xml

The sssoContext.xml file is a Spring context file that is used by SimpleSSO to configure the environment. It should be placed in {CATALINA_HOME}/server/classes.

Now choose an SSOProvider below and configure the required SSOProvider component (Spring bean) in the sssoContext.xml file.

Logging and debugging

A successful or unsuccessful authentication will be logged to logs/catalina.*.log. Further debugging can be enabled by adding the following line to {CATALINA_HOME}/conf/logging.properties.

Deploying SimpleSSO to Tomcat 5.0

An early version compatible with Tomcat 5.0 is in the source repository. The build script is not configured to build this version yet. This version has not been tested recently but should work. Configuration is the same as for Tomcat 5.5 above.

TODO. Make a binary version of ssso-tomcat50-x.x.x.jar available.
TODO. Configure the ant build.xml to produce this jar as part of the build.

Configuring an SSO provider

Configuring a SimpleSSO provider for testing purposes

The SimpleSSO solution comes with a basic, low security token that can be used for testing purposes. The only parameter that needs to be set is the password parameter. Any user will be able to authenticate with this password.

Configuring a SimpleSSO provider for Lotus Domino

Lotus Domino provides an SSO solution called the LtpaToken. The parameters are as follows:

The URL of the Domino server to POST a username and password to
The Domino shared secret used for encryption. Ask your Domino administrator to provide this.
The character set the Domino server uses to encode usernames inside the LtpaToken.

Configuring an application for SSO

Now that the server is configured and the SSO provider is configured you can configure each application for SSO.

Securing a generic Java web application

Add a login config to the web.xml.

Create the login form and login error pages.

Make sure the login.html and login-error.html pages are available. As a minimum your login form will contain something like the following.

Secure all or part of the application with a constraint in the web.xml

Deploy and test the application

Build and deploy your war file and deploy to the Tomcat webapps folder. You should be presented with a username and password dialog box.

Securing an Atlassian Confluence application

You may want to make the following changes in the edit-webapp directory in Confluence and build an sso enabled confluence war.

Confluence is an enterprise wiki tool available from Atlassian.

Securing the web application

Secure the confluence web container with a standard \<security-contraint/> as described in the previous section. This will ensure that a SimpleSSO principal is available to the confluence application.

Deploy the atlassian jar

The following files need to be placed in /WEB-INF/lib:

ssso-atlassian-x.x.x.jar

Configuring a Seraph login filter for SimpleSSO

Confluence (and Jira) use the Seraph library to provide authentication. The confluence SimpleSSO plugin consists of a Seraph filter and a Seraph authenticator. Add the following lines to web.xml in the appropriate places.

Configuring a Confluence Seraph authenticator for SimpleSSO

When a Seraph login filter attempts to log a user in it will call the Seraph authenticator. Our Seraph authenticator checks for a valid ISimpleSSOPrincipal on the container. If this user does not have permission to access Confluence they are automatically added to the "confluence-users" group. The /WEB-INF/classes/seraph-config.xml is used to set the authenticator.

Testing

You can enable logging with settings in the /WEB-INF/classes/log4j.properties file.