This How-To will explain how to install, configure and deploy JOSSO Single Sign-On in JBoss 4.2.GA / Tomcat 5.5. application server.

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 can be deployed in the JBoss 4.2 application server, providing the authenticated user's identity to the partner web application and EJBs.

The JBoss application server can be downloaded from here .

In order to integrate JOSSO with JBoss to implement a Single Sign-on Infrastructure, you should use JBoss 4.0.2 or later.

The JBOSS_HOME environment variable must be set pointing to the installation directory of JBoss.

For Unix systems you can use :

$ export JBOSS_HOME=/usr/product/jboss-4.2.GA

For Win32 systems you can use :

set JBOSS_HOME=c:\jboss-4.2.GA

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 ear

For Win32 systems you should execute :

build.bat ear

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

• josso.ear
• josso-1.7.jar
• josso-common-1.7.jar

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

• josso-tomcat55-plugin-1.7.jar
• josso-jboss42-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 JBoss.

For Unix systems you should execute :

$ ./build.sh install-jboss42

For Win32 systems you should execute :

build.bat install-jboss42

This procedure must be done only once.

This will install JOSSO on the default JBOSS instance. If you want to use a different instance set the JBOSS_INSTANCE environment variable to the propper JBOSS instance name. You can use any instance name, for example build.bat -DJBOSS_INSTANCE=myInstance

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 $JBOSS_HOME/server/default/conf 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.

This file must reside in the $JBOSS_HOME/server/default/conf directory in order to be located by the Single Sign-On Gateway.

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

In order to be able protect a partner application an SSO Agent will have to be configured.

The main responsability of the Single Sign-On Agent is to check that a previosly 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.

So first we will have protect a specific JBoss host using the Single Sign-On Agent Valve. which is done by modifying the $JBOSS_HOME/server/default/deploy/jbossweb-tomcat55.sar/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 tells that HTTP requests for the localhost host, before being delivered to the target web application, will be processed by JOSSO.

If the target web context matches one of the partner application web contexts defined in the josso-agent-config.xml file, the SSO Agent will assert the Single Sign-On session, 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 target web context.

Add 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 Realm entry must be added to the $JBOSS_HOME/server/default/deploy/jbossweb-tomcat55.sar/server.xml file that must have the following content :

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

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 Realm. The Login Module validates the session and obtains the corresponding user and role information by invoking the gateway identity management web services.

Add an entry to the login-config.xml file located in the $JBOSS_HOME/server/default/conf directory with the following content :

<application-policy name = "josso">
  <authentication>
    <login-module code = "org.josso.jb42.agent.JBossSSOGatewayLoginModule"
       flag = "required">
       <module-option name="debug">true</module-option>
    </login-module>
  </authentication>
</application-policy>

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 $JBOSS_HOME/server/default/conf 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.jb42.agent.JBossCatalinaSSOAgent">
        <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 JBoss output artifact of the build procedure is an EAR file called josso.ear which contains the josso.war, partnerapp.war and partnercomponent.jar files. The josso.ear file must be deployed in JBoss by invoking the following command :

For Unix systems you should execute :

$ ./build.sh deploy-jboss42

For Win32 systems you should execute :

build.bat deploy-jboss42

This command will also copy the josso-1.7.jar, josso-common-1.7.jar, josso-tomcat55-plugin-1.7.jar , josso-jboss42-plugin-1.7.jar files to the $JBOSS_HOME/server/default/deploy/jbossweb-tomcat55.sar directory, so that the Single Sign-On Agent and Reverse Proxy Tomcat Valves can be deployed.

If you want to exclude JOSSO web/ejb samples from your distribution, you can use the following build property : exclude.samples=true JOSSO web/ejb samples will be excluded from the deploy. Add this property to the local.build.properties file in your JOSSO_HOME directory.

Running

Run JBoss

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

For Unix systems you can use :

./run.sh

For Win32 systems you can use :

run.bat

Running the Samples

Samples are bundled in josso.ear file unless specified otherwise.

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