This How-To will explain how to install, configure and deploy JOSSO Single Sign-On in the Apache Tomcat 5.5 Container.

Introduction

The default mechanism in JOSSO for registering, configuring and assembling its components is through a built-in and product-specific IoC container. Considering that such concerns are realized in a domain-specific way, thus hiding unnecessary technical details from the configuration metadata, the setup experience is more user-friendly than using a non-domain specific approach. On the other hand, more complex setup use-cases are not easily supported and call for a higher level configuration metadata format and product-agnostic IoC container.

In order for these scenarios to be handled properly, JOSSO can be run on top of the Spring IoC container instead of the built-in container, bringing support for more complex configuration and extensibility use-cases through the leveraging of the popular Spring configuration format and its platform components.

Furthermore, existing Spring applications can interoperate with the JOSSO layer and its components (e.g. beans), since a common microkernel and component model is used.

The JOSSO Gateway Spring configuration is spanned over several context files. Each Spring context file contains beans definitions responding to a specific concern. For instance, identity store beans are defined within the josso-identitystores-config.xml Spring context file.
Lets have a look at the available Spring context files for the JOSSO Gateway:

• josso-gateway-config.xml : entry point SSO Gateway Spring context file, containing top level bean definitions.
• josso-credential-stores-config.xml: contains credential store bean definitions referenced by the top level SSO Gateway beans
• josso-identitystores-config.xml: contains identity store bean definitions referenced by the top level SSO Gateway beans
• josso-sessionstores-config.xml: contains session store bean definitions referenced by the top level SSO Gateway beans
• josso-gateway-jmx-config.xml: contains required definitions for enabling Spring JMX support for the registered SSO Gateway beans

Lets have a look at the available Spring context files for the JOSSO Agent:

• josso-agent-config.xml: entry point SSO Agent Spring context file, containing top level bean definitions.
• josso-agent-jmx-config.xml: contains required definitions for enabling Spring JMX support for the SSO Agent

Finally, the Spring context file for the Reverse Proxy component is josso-reverse-proxy-config.xml.
This Spring context hierarchy, given the Spring container context aggregation facilities, can of course vary depending on the specific user needs.

Be Careful Inclusion of the JMX context file is mandatory for the gateway to function properly

By default JOSSO uses its built-in IoC container. In order to use JOSSO with the Spring IoC container you must enable it on execution.

Prerequisites

Before configuring JOSSO make sure you have installed the JDK 1.5 that can be downloaded from here . The JAVA_HOME environment variable must be set to the JDK installation directory.

For Unix systems you can use :

$ export JAVA_HOME=/usr/local/jdk1.5.0_12

For Win32 systems you can use :

set JAVA_HOME=c:\jdk1.5.0_12

JOSSO requires the Catalina Container in order to run.

Catalina is bundled with the Apache Tomcat Web server which can be downloaded from here .

In order to integrate JOSSO with Tomcat 5.5 to implement a Single Sign-on Infrastructure, you should use Apache Tomcat v5.5.9 or later.

The CATALINA_HOME environment variable must be set pointing to the installation directory of Apache Tomcat.

For Unix systems you can use :

$ export CATALINA_HOME=/usr/product/apache-tomcat-5.5.20

For Win32 systems you can use :

set CATALINA_HOME=c:\apache-tomcat-5.5.20

Building

Once the prerequisites are satisfied you can start building JOSSO by invoking the build script for your OS. from the project root.

For Unix systems you should execute :

$ ./build.sh war

For Win32 systems you should execute :

build.bat war

If this procedure is succesfully executed you will find the following files in the ./build/josso-1.7 directory :

• josso.war
• josso-1.7.jar
• josso-common-1.7.jar

You will also find the tomcat55 plugin files in the ./build/josso-1.7/plugins directory :

• josso-tomcat55-plugin-1.7.jar

The josso.war file contains the server part of the Single Sign-On, while the josso-1.7.jar file contains the stubs needed to integrate the web infrastructure to the SSO authentication schemes. The josso-common-1.7.jar file contains the classes that are shared beteween the JOSSO infrastructure and the partner applications.

Installing

After succesfully compiling JOSSO you must install the core Jars for JOSSO to run in Catalina.

For Unix systems you should execute :

$ ./build.sh install-tomcat55

For Win32 systems you should execute :

build.bat install-tomcat55

This procedure must be done only once.

Setup

The Single Sign-On Gateway Configuration

The Single Sign-On Gateway is responsible of the centralized authentication of web users using the configured authentication scheme and credential store.

An authentication scheme is a security mechanisms used to verify user identity based on his credentials. Sample authentication schemes are username/password authentication or Certificate based authentication.

A credential is a piece of information bound to an individual that is presented to the verifier in an authentication transaction. Sample credentials are username/password pair and X.509 Certificates.

User credentials must be stored using some sort of persistence mechanism, so that credentials provided by the user in an authentication transaction can be checked. A Credential Store is where user credentials are located. Sample credential stores are database and LDAP.

One core feature of JOSSO is to allow to combine authentication schemes and credential stores using the Single Sign-On Gateway configuration file. This file must reside in the $CATALINA_HOME/bin directory in order to be located by the Single Sign-On Gateway.

Lets have a look at an example Spring Single Sign-On Gateway configuration file:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd">

    <import resource="josso-credentialstores-config.xml"/>
    <import resource="josso-identitystores-config.xml"/>
    <import resource="josso-sessionstores-config.xml"/>
    <import resource="josso-gateway-jmx-config.xml"/>
    <bean name="ssoWebConfiguration" class="org.josso.gateway.SSOWebConfigurationImpl">
    </bean>
    <bean id="securityDomain" class="org.josso.SecurityDomainImpl">
        <property name="eventManager" ref="ssoEventManager" />
        <property name="authenticator" ref="authenticator"/>
        <property name="identityManager" ref="ssoIdentityManager"/>
        <property name="sessionManager" ref="ssoSessionManager"/>
        <property name="auditManager" ref="ssoAuditManager"/>
    </bean>
    <bean id="ssoEventManager" class="org.josso.spring.SpringJMXSSOEventManagerImpl">
    </bean>
    <bean id="authenticator" class="org.josso.auth.AuthenticatorImpl">
        <property name="authenticationSchemes">
            <list>
                <ref bean="userPassAuthScheme" />
                <ref bean="x509CertificateAuthScheme" />
            </list>
        </property>
    </bean>
    <bean id="ssoIdentityManager" class="org.josso.gateway.identity.service.SSOIdentityManagerImpl">
        <!-- Memory -->
        <property name="identityStore" ref="memoryIdentityStore" />
        <property name="identityStoreKeyAdapter" ref="simpleIdentityStoreKeyAdapter" />
    </bean>
    <bean id="ssoSessionManager" class="org.josso.gateway.session.service.SSOSessionManagerImpl">
        <property name="maxInactiveInterval" value="30" />
        <property name="maxSessionsPerUser" value="-1" />
        <property name="invalidateExceedingSessions" value="false" />
        <property name="sessionMonitorInterval" value="10000" />
        <property name="sessionStore" ref="memorySessionStore" />
        <property name="sessionIdGenerator" ref="sessionIdGenerator" />
    </bean>
    <bean id="ssoAuditManager" class="org.josso.spring.SpringSSOAuditManagerImpl">
        <property name="handlers">
            <list>
                <ref bean="loggerAuditTrailHandler" />
            </list>
        </property>
    </bean>
    <bean name="loggerAuditTrailHandler" class="org.josso.gateway.audit.service.handler.LoggerAuditTrailHandler">
        <property name="name" value="LoggerAuditTrailHandler" />
        <property name="category" value="org.josso.gateway.audit.SSO_AUDIT" />
    </bean>
    <bean name="userPassAuthScheme" class="org.josso.auth.scheme.UsernamePasswordAuthScheme">
        <property name="name" value="basic-authentication"/>
        <property name="hashAlgorithm" value="MD5"/>
        <property name="hashEncoding" value="HEX"/>
        <property name="ignorePasswordCase" value="false"/>
        <property name="ignoreUserCase" value="false"/>
        <property name="credentialStore" ref="memoryUserPasswordCredentialStore" />
        <property name="credentialStoreKeyAdapter" ref="simpleIdentityStoreKeyAdapter" />
    </bean>
    <bean name="x509CertificateAuthScheme" class="org.josso.auth.scheme.X509CertificateAuthScheme">
        <property name="name" value="strong-authentication" />
        <property name="credentialStore" ref="memory509CertificateCredentialStore" />
        <property name="credentialStoreKeyAdapter" ref="simpleIdentityStoreKeyAdapter" />
    </bean>
</beans>

Every JOSSO configuration file must reside in the same directory which is $CATALINA_HOME/bin directory.

The Single Sign-On Agent has its own configuration file, if you plan to run both Agent and Gateway in the same server, you must also copy josso-agent-config.xml to the $CATALINA_HOME/bin directory.

Configuring the Authenticator

The Authenticator is the component responsible of realizing a concrete authentication scheme.
The concrete authentication scheme bean to be implemented must be added to the collection of authentication schemes that the authenticator bean holds. For username/password authentication define a bean identified as "userPassAuthScheme" and realized by the org.josso.auth.scheme.UsernamePasswordAuthScheme class. Then reference it from an authenticator bean
Lets have a look at an example :

<bean id="authenticator" class="org.josso.auth.AuthenticatorImpl">
    <property name="authenticationSchemes">
        <list>
            <ref bean="userPassAuthScheme" />
        </list>
    </property>
</bean>
<bean name="userPassAuthScheme" class="org.josso.auth.scheme.UsernamePasswordAuthScheme">
    <property name="name" value="basic-authen7tication"/>
    <property name="hashAlgorithm" value="MD5"/>
    <property name="hashEncoding" value="HEX"/>
    <property name="ignorePasswordCase" value="false"/>
    <property name="ignoreUserCase" value="false"/>
    <property name="credentialStore" ref="memoryUserPasswordCredentialStore" />
    <property name="credentialStoreKeyAdapter" ref="simpleIdentityStoreKeyAdapter" />
</bean>

Now you will need to tell the authenticator the persistence mechanism to be used for obtaining the user credentials when asserting his identity. You can configure this by defining a bean of type org.josso.gateway.identity.service.store.CredentialStore and reference it from the 'credentialStore' attribute of the consuming authentication scheme bean. For database persistence mechanism use a credential store implementation of type org.josso.gateway.identity.service.store.db.JDBCIdentityStore.
Lets have a look at an example:

<bean name="jdbcIdentityStore" class="org.josso.gateway.identity.service.store.db.JDBCIdentityStore" >
    <property name="userQueryString">
        <value>
            SELECT login FROM josso_user WHERE login = ?
        </value>
    </property>
    <property name="userPropertiesQueryString">
        <value>
            SELECT 'user.description' AS name , description AS value FROM josso_user WHERE login = ?
            UNION
            SELECT name AS name ,  value AS value FROM josso_user_property WHERE login = ?
        </value>
    </property>
    <property name="rolesQueryString">
        <value>
            SELECT josso_role.name FROM josso_role , josso_user_role , josso_user WHERE josso_user.login = ? AND josso_user.login = josso_user_role.login AND josso_role.name = josso_user_role.name
        </value>
    </property>
    <property name="connectionName" value="josso" />
    <property name="connectionPassword" value="josso" />
    <property name="connectionURL" value="jdbc:oracle:thin:@localhost:1521:josso_db" />
    <property name="driverName" value="oracle.jdbc.driver.OracleDriver" />
</bean>

Once you chose persistence mechanism to be used by the authenticator, you will need to tell the store how to obtain the username and password information from your specific store. In case of a JDBC credential store you must set the credentialsQueryString element value with the SQL SELECT query that will retrieve the username and password for a user.
In case of using the database persistence mechanism you will also need to set the specific values for the connectionName, connectionPassword, connectionURL and driverName elements.

Configuring the Identity Manager

The Identity Manager is the component responsible of authenticating the user using the configured authenticator and managing the authenticated user sessions.
The selected identity manager bean to be implemented must be of type org.josso.gateway.identity.service.SSOIdentityManager. In order to use the default Identity Manager set the class attribute value to org.josso.gateway.identity.service.SSOIdentityManagerImpl.
For example:

<bean id="ssoIdentityManager" class="org.josso.gateway.identity.service.SSOIdentityManagerImpl">
    <property name="identityStore" ref="memoryIdentityStore" />
    <property name="identityStoreKeyAdapter" ref="simpleIdentityStoreKeyAdapter" />
</bean>

Now you will need to tell the identity manager the persistence mechanism to be used for obtaining user and role information. You can configure this by defining a bean of type org.josso.gateway.identity.service.store.IdentityStore , and reference it from the 'identityStore' attribute of the consuming ssoIdentityManager bean. For database persistence mechanism use the org.josso.gateway.identity.service.store.db.JDBCIdentityStore bean.

Once you set the persistence mechanism to be used by the identity manager, you will need to tell the identity store how to obtain the user and role information from your specific store. In case of a JDBC identity store you must set the userQueryString element value with the SQL SELECT query that will retrieve the username for a user given user. This username will then be used to retrieve the user's roles by executing the SQL SELECT query declared in the rolesQueryString.
In case of using the database persistence mechanism you will also need to set the specific values for the connectionName, connectionPassword, connectionURL and driverName elements.

Configuring the Session Manager

The Single Sign-On Session Manager is the component responsible of managing the life cycle of an SSO User Session. On successful user authentication the Single Sign-On Gateway creates a new SSO Session using the Session Manager.
The selected session manager bean to be implemented must be of type org.josso.gateway.session.service.SSOSessionManager. In order to use the default Session Manager set the class attribute value to org.josso.gateway.session.service.SSOSessionManagerImpl.
For example :

<bean id="ssoSessionManager" class="org.josso.gateway.session.service.SSOSessionManagerImpl">
    <property name="maxInactiveInterval" value="30" />
    <property name="maxSessionsPerUser" value="-1" />
    <property name="invalidateExceedingSessions" value="false" />
    <property name="sessionMonitorInterval" value="10000" />
    <property name="sessionStore" ref="memorySessionStore" />
    <property name="sessionIdGenerator" ref="sessionIdGenerator" />
</bean>
<bean name="memorySessionStore" class="org.josso.gateway.session.service.store.MemorySessionStore" />
<!-- Session Id Generator-->
<bean name="sessionIdGenerator" class="org.josso.gateway.session.service.SessionIdGeneratorImpl">
    <property name="algorithm" value="MD5" />
</bean>

Configuring the Audit Manager

The Single Sign-On Audit Manager is the component responsible for propagating auditing SSO events to the listening Audit Handlers. Audit Handlers can trap such events and act accordingly, such as disabling an account after several failed authentication attempts (In this example its probably best to extend the default Authenticator to verify the user account status on authentication request).

JOSSO provides a default handler which traces all SSO audit trails using the configured logger.
Custom audit managers and their handlers can be used, but for most cases the following default configuration will do just fine.

<bean id="ssoAuditManager" class="org.josso.spring.SpringSSOAuditManagerImpl">
    <property name="handlers">
        <list>
            <ref bean="loggerAuditTrailHandler" />
        </list>
    </property>
</bean>
<bean name="loggerAuditTrailHandler" class="org.josso.gateway.audit.service.handler.LoggerAuditTrailHandler">
    <property name="name" value="LoggerAuditTrailHandler" />
    <property name="category" value="org.josso.gateway.audit.SSO_AUDIT" />
</bean>

Configuring the Event Manager

The Single Sign-On Event Manager is the component responsible for propagating generic SSO events, such as information session life cycle and authentication requests.

You can add your own event listeners to act on behalf of any SSO event, such as an authentication failure. Even thought events are propagated through the JMX bus, your listeners do not have to deal with the JMX api since the underlying JOSSO event infrastructure will take care of this.

Custom event managers and their handlers can be configured and used, but for most cases the default configuration will do just fine.

Single Sign-On Agent Configuration

The main responsibility of the Single Sign-On Agent is to check that a previously user logged through the Single Sign-On Gateway is authorized to access a web context.
The Agent verifies this information by querying via SOAP the Single Sign-On Webservice infrastructure using a special cookie set by the Single Sign-On Gateway on authentication.

Protect the Web Applications

So, first we will have protect a specific Tomcat Web Context using the Single Sign-On Agent Valve. which is done by modifying the $CATALINA_HOME/conf/server.xml file in the following way :

<Server>
      ...
      <Service>
        ...
        <Engine>
          ...
          <Host>
            ...
            <Valve className="org.josso.tc55.agent.SSOAgentValve" debug="1"/>
            ...
          </Host>
          ...
        </Engine>
        ...
      </Service>
      ...
</Server>

This file tells that the /partner Web Context can only be accessed by authenticated users with an established session against the Single Sign-On Gateway. On each request sent by the user to the /partner Web Context, the Single Sign-On Agent will intercept it, assert the Single Sign-On session and obtain the user data from the Single Sign-On Gateway.
In case the session is valid, the Single Sign-On Agent will set the security context to the request and pass it on to the web application listening for the Web Context.

Configure a JAAS Realm

A Tomcat Realm is a "database" of usernames and passwords that identify valid users of a web application (or set of web applications), plus an enumeration of the list of roles associated with each valid user.

In order to integrate the Single Sign-On Agent with the Single Sign-On Gateway a JAAS Tomcat Realm entry must be added to the server.xml file that must have the following content :

<Server>
  ...
  <Service>
    ...
    <Engine name="Catalina" defaultHost="localhost" debug="0">
      ...
        <Realm className="org.josso.tc55.agent.jaas.CatalinaJAASRealm"
             appName="josso"
             userClassNames="org.josso.gateway.identity.service.BaseUserImpl"
             roleClassNames="org.josso.gateway.identity.service.BaseRoleImpl"
             debug="1" />      ...
    </Engine>
  </Service>
</Server>

You must remove the default realm configured in the server.xml file.

Configure a JAAS Login Module

The Single Sign-On Agent uses JAAS (Java Authentication and Authorization Service). For each request the Single Sign-On Agent intercepts it delegates the SSO session authentication to the Single Sign-On Gateway Login Module configured for the Tomcat JAAS Realm. The Login Module validates the session and obtains the corresponding user and role information by invoking the gateway identity management webservices.

The Tomcat JAAS Realm must be able to run the Single Sign-On Gateway Login module. To do this create a jaas.conf file in the $CATALINA_HOME/conf directory with the following content :

josso {
  org.josso.tc55.agent.jaas.SSOGatewayLoginModule required debug=true;
};

The jaas.conf will need to be fetched by Tomcat when starting up. For this reason before starting Tomcat set the JAVA_OPTS variable to -Djava.security.auth.login.config=../conf/jaas.conf

For Unix systems you can use :

$ export JAVA_OPTS=-Djava.security.auth.login.config=../conf/jaas.conf

For Win32 systems you can use :

set JAVA_OPTS=-Djava.security.auth.login.config=..\conf\jaas.conf

For the jaas.conf file to be found by the Tomcat JAAS Realm remember to start Tomcat from the $CATALINA_HOME/bin directory.

In Unix systemes you can also add/edit the setenv.sh file located in CATALINA_HOME/bin as follows :

export JAVA_OPTS="-Djava.security.auth.login.config=$CATALINA_HOME/conf/jaas.conf"

In WIndows systemes you can also add/edit the setenv.bat file located in CATALINA_HOME/bin as follows :

set JAVA_OPTS=-Djava.security.auth.login.config=%CATALINA_HOME%\conf\jaas.conf

Tomcat will automatically call the setenv during startup, if present.

Enabling Spring Ioc Container

To enable the Spring IoC container add the following definition to the JAVA_OPTS environment variable:
-Dorg.josso.ComponentKeeperFactory=org.josso.spring.SpringComponentKeeperFactoryImpl

Configure the Agent

The Single Sign-On Agent Configuration must reside in the $CATALINA_HOME/bin directory and should be referenced by the josso-agent-config.xml file.
Let's take a look at an example Single Sign-On Agent Spring configuration file :

<?xml version="1.0" encoding="ISO-8859-1" ?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd">
    <import resource="josso-agent-jmx-config.xml"/>
    <bean name="ssoAgent" class="org.josso.tc55.agent.CatalinaSSOAgent">
        <property name="gatewayLoginUrl" value="http://localhost:8080/josso/signon/login.do" />
        <property name="gatewayLogoutUrl" value="http://localhost:8080/josso/signon/logout.do" />
        <property name="sessionAccessMinInterval" value="1000" />
        <property name="gatewayServiceLocator" ref="gatewayServiceLocator" />
        <property name="configuration" ref="ssoAgentConfiguration" />
    </bean>
    <bean name="ssoAgentConfiguration" class="org.josso.agent.SSOAgentConfigurationImpl">
        <property name="SSOPartnerApps">
            <list>
                <ref bean="partnerApplication" />
            </list>
        </property>
    </bean>
    <bean name="partnerApplication" class="org.josso.agent.SSOPartnerAppConfig">
        <constructor-arg index="0" value="/partnerapp" />
        <constructor-arg index="1">
            <list>
                <value>public-resources</value>
            </list>
        </constructor-arg>
    </bean>
    <bean name="gatewayServiceLocator" class="org.josso.gateway.WebserviceGatewayServiceLocator">
        <property name="endpoint" value="localhost:8080" />
     </bean>
</beans>

Using this configuration you can set :

• The Gateway Login URL, where the Single Sign-On Agent will redirect the user on protected resource access request so that he can authenticate.
• The Gateway Logout URL, where the Single Sign-On Agent will redirect the user on logout request.
• Concrete Single Sign-On Agent to be instantiated
• The concrete Service Locator to be used to invoke the services of the Single Sign-On Gateway.

In this specific case, which is the default, is using SOAP over HTTP to invoke The Single Sign-On Gateway WebServices.

Its important to specify the *endpoint configuration parameter which should contain the host and port information where the Single Sign-On WebServices are listening.

If the gateway and the agent are running in the same server this will be localhost and the port should be the port where Tomcat is listening for incoming HTTP requests.

Deploying

The josso.war file must be deployed in Tomcat as a Web application by invoking the following command:

For Unix systems you should execute :

$ ./build.sh deploy-tomcat55

For Win32 systems you should execute :

build.bat deploy-tomcat55

This command will copy the josso-1.7.jar file to the $CATALINA_HOME/server/lib directory and the josso-common-1.7.jar file to the $CATALINA_HOME/common/lib directory, so that the Single Sign-On Agent and Reverse Proxy Tomcat Valves can be deployed.

If you want to include JOSSO configuration files in the generated war, compile JOSSO using the include.config system property set to true :

For Unix systems you should execute :

$ ./build.sh -Dinclude.config=true deploy-tomcat55

For Win32 systems you should execute :

build.bat -Dinclude.config=true deploy-tomcat55

Then you have to copy josso-config.xml, josso-agent-config.xml and josso-gateway-config.xml to $CATALINA_HOME/bin, remember to reference both agent and gateway files from josso-config.xml.

If you exclude JOSSO config files from bundle and want to use the memroy credential/user store copy josso-credentials.xml and josso-users.xml to $CATALINA_HOME/shared/classes/

Running

Set environent variables

The jaas.conf will need to be fetched by Tomcat when starting up. For this reason before starting Tomcat set the JAVA_ENV variable to -Djava.security.auth.login.config=../conf/jaas.conf

For Unix systems you can use :

$ export JAVA_OPTS=-Djava.security.auth.login.config=../conf/jaas.conf

For Win32 systems you can use :

set JAVA_OPTS=-Djava.security.auth.login.config=..\conf\jaas.conf

For the jaas.conf file to be found by the Tomcat JAAS Realm remember to start Tomcat from the $CATALINA_HOME/bin directory.

Run Tomcat

Change to the $CATALINA/bin directory and run the startup script provided for your Operating System.

For Unix systems you can use :

./startup.sh

For Win32 systems you can use :

startup

Deploy and run the Samples

From the JOSSO distribution, execute the following command :

For Unix systems you should execute :

build.sh deploy-samples-tomcat55

For Win32 systems you should execute :

build.bat deploy-samples-tomcat55

On succesfull deploy, call the sample partner application using the http://localhost:8080/partnerapp/protected URL, and logon using the configured users. If you followed the Developer HOWTO you should use the user1/user1pwd account.

On succesfull logon, the user identity should be displayed.

Comments

Care to comment on this How-To? Help keep this document relevant by passing along any constructive feedback to the josso-docs