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

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-6.0.14

For Win32 systems you can use :

set CATALINA_HOME=c:\apache-tomcat-6.0.14

Introduction

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

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 tomcat6 plugin files in the ./build/josso-1.7/plugins directory :

• josso-tomcat6-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-tomcat60

For Win32 systems you should execute :

build.bat install-tomcat60

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 Single Sign-On Gateway configuration file :

<?xml version="1.0" encoding="ISO-8859-1" ?>
<domain>
  <name>SampleDomain</name>
  <type>web</type>
  <authenticator>
<class>org.josso.auth.AuthenticatorImpl</class>
<authentication-schemes>
    <!-- Basic Authentication Scheme -->
    <authentication-scheme>
      <name>basic-authentication</name>
      <class>org.josso.auth.scheme.UsernamePasswordAuthScheme</class>

      <!-- ========================================================= -->
      <!-- JDBC Credential Store                                     -->
      <!-- ========================================================= -->
      <credential-store>
       <class>
       org.josso.gateway.identity.service.store.db.JDBCIdentityStore
       </class>
       <credentialsQueryString>
       SELECT login AS username , password AS password FROM josso_user
       WHERE login = ?
       </credentialsQueryString>
       <connectionName>SCOTT</connectionName>
       <connectionPassword>TIGER</connectionPassword>
       <connectionURL>jdbc:oracle:thin:@mydbhost:1521:mydb</connectionURL>
       <driverName>oracle.jdbc.driver.OracleDriver</driverName>
      </credential-store>

      <credential-store-key-adapter>
    <class>
    org.josso.gateway.identity.service.store.SimpleIdentityStoreKeyAdapter
    </class>
      </credential-store-key-adapter>

    </authentication-scheme>

</authentication-schemes>
  </authenticator>

  <sso-identity-manager>
<class>org.josso.gateway.identity.service.SSOIdentityManagerImpl</class>
<!-- ========================================================= -->
<!-- JDBC Identity Store                                       -->
<!-- ========================================================= -->
<sso-identity-store>
  <class>
  org.josso.gateway.identity.service.store.db.JDBCIdentityStore
  </class>
  <userQueryString>
   SELECT login FROM josso_user WHERE login = ?
  </userQueryString>
  <rolesQueryString>
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
   </rolesQueryString>
   <connectionName>SCOTT</connectionName>
   <connectionPassword>TIGER</connectionPassword>
   <connectionURL>jdbc:oracle:thin:@mydbhost:1521:mydb</connectionURL>
   <driverName>oracle.jdbc.driver.OracleDriver</driverName>
</sso-identity-store>

<sso-identity-store-key-adapter>
  <class>
  org.josso.gateway.identity.service.store.SimpleIdentityStoreKeyAdapter
  </class>
</sso-identity-store-key-adapter>
  </sso-identity-manager>

  <sso-session-manager>
<class>org.josso.gateway.session.service.SSOSessionManagerImpl</class>

<!--
Set the maximum time interval, in minutes, between client requests
before the SSO Service will invalidate the session. A negative time
indicates that the session should never time out.
-->
<maxInactiveInterval>1</maxInactiveInterval>

<sso-session-store>
  <class>
  org.josso.gateway.session.service.store.MemorySessionStore
  </class>
</sso-session-store>

<sso-session-id-generator>
  <class>
   org.josso.gateway.session.service.SessionIdGeneratorImpl
  </class>
  <!--
  The message digest algorithm to be used when generating session
  identifiers.  This must be an algorithm supported by the
  java.security.MessageDigest class on your platform.

  In J2SE 1.4.2 you can check :
  Java Cryptography Architecture API Specification & Reference -
  Apendix A : Standard Names
  Values are : MD2, MD5, SHA-1, SHA-256, SHA-384, SHA-512
  -->
  <algorithm>MD5</algorithm>
</sso-session-id-generator>
</sso-session-manager>

<sso-audit-manager>
  <class>org.josso.gateway.audit.service.SSOAuditManagerImpl</class>
  <handlers>

    <!-- This handler logs all audit trails using Log4J, under the given category -->
    <handler>
      <class>org.josso.gateway.audit.service.handler.LoggerAuditTrailHandler</class>
        <name>LoggerAuditTrailHandler</name>
        <category>org.josso.gateway.audit.SSO_AUDIT</category>
    </handler>
  </handlers>
</sso-audit-manager>

    <!-- SSO Event Manager component -->
<sso-event-manager>
  <class>org.josso.gateway.event.security.JMXSSOEventManagerImpl</class>
  <!--
  JMX Name of the EventManager MBean that will send SSO Events as JMX Notifications
  The MBean will be registered by the MBeanComponentKeeper.
  -->
  <oname>josso:type=SSOEventManager</oname>
</sso-event-manager>


</domain>

josso-config.xml

The josso-config.xml file represents the master configuration file which is used to declare the concrete configuration files that will be used by JOSSO to customize its behaviour.

This file must reside in the $CATALINA_HOME/bin directory in order to be located by the Single Sign-On Gateway.

Let's take a look at an example josso-config.xml file that will configure a JOSSO Single Sign-On Gateway :

<?xml version="1.0" encoding="ISO-8859-1" ?>
<configuration>
    <!-- Comment if no agent runs in this server -->
    <hierarchicalXml fileName="josso-agent-config.xml"/>
    <!-- Comment if no gateway runs in this server -->
    <hierarchicalXml fileName="josso-gateway-config.xml"/>
</configuration>

Using this configuration JOSSO is told to import the josso-gateway-config.xml XML configuration file. Any configuration file referenced in the josso-config.xml file must reside in the same directory as the josso-config.xml which is $CATALINA_HOME/bin.

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 $CATALINA_HOME/bin directory and import it from the josso-config.xml file as described below.

Configuring the Authenticator

The Authenticator is the component responsible of realizing a concrete authentication scheme.

The authentication scheme to be implemented must be set in the class element, child of the authentication-schemes element. For username/password authentication scheme set it to org.josso.auth.scheme.UsernamePasswordAuthScheme.

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 setting the class element child of the credential-store element. For database persistence mechanism set it to org.josso.gateway.identity.service.store.db.JDBCIdentityStore.

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 identity manager to be implemented must be set in the class element, child of the identity-manager element. To use the default Identity Manager set this element value to org.josso.gateway.identity.service.SSOIdentityManagerImpl.

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 setting the class element child of the sso-identity-store element. For database persistence mechanism set it to org.josso.gateway.identity.service.store.db.JDBCIdentityStore.

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 lifecycle of an SSO User Session. On succesfull user authentication the Single Sign-On Gateway creates a new SSO Session using the Session Manager.

The concrete session manager to be instantiated, its store for persisting SSO sessions among other things can be configured but for most common uses the default configuration will do just fine.

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 configured and used, but for most cases the default configuration will do just fine.

Configuring the Event Manager

The Single Sign-On Event Manager is the component responsible for propagating generic SSO events, such as information session lifecycle 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 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.

josso-config.xml

The josso-config.xml file represents the master configuration file which is used to declare the concrete configuration files that will be used by JOSSO to customize its behaviour.

This file must reside in the $CATALINA_HOME/bin directory in order to be located by the Single Sign-On Agent Valve.

Let's take a look at an example josso-config.xml file that will configure a JOSSO Single Sign-On Agent :

<?xml version="1.0" encoding="ISO-8859-1" ?>
<configuration>
    <!-- Comment if no agent runs in this server -->
    <hierarchicalXml fileName="josso-agent-config.xml"/>
    <!-- Comment if no gateway runs in this server -->
    <hierarchicalXml fileName="josso-gateway-config.xml"/>

</configuration>

Using this configuration JOSSO is told to import the josso-agent-config.xml XML configuration file. Any configuration file referenced in the josso-config.xml file must reside in the same directory as the josso-config.xml which is $CATALINA_HOME/bin as described above.

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

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.tc60.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 /partnerapp 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.tc60.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.tc60.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.

Configure the Agent

The Single Sign-On Agent Configuration must reside in the $CATALINA_HOME/bin directory and should be referenced by the josso-config.xml file as stated before.

Let's take a look at an example Single Sign-On Agent configuration file :

<?xml version="1.0" encoding="ISO-8859-1" ?>
<agent>
  <class>org.josso.tc60.agent.CatalinaSSOAgent</class>
  <gatewayLoginUrl>http://localhost:8080/josso/signon/login.do</gatewayLoginUrl>
  <gatewayLogoutUrl>http://localhost:8080/josso/signon/logout.do</gatewayLogoutUrl>
  <sessionAccessMinInterval>1000</sessionAccessMinInterval>
  <service-locator>
    <class>org.josso.gateway.WebserviceGatewayServiceLocator</class>
    <endpoint>localhost:8080</endpoint>
  </service-locator>

  <partner-apps>
      <partner-app>
          <context>/partnerapp</context>
      </partner-app>
  </partner-apps>
</agent>

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-tomcat60

For Win32 systems you should execute :

build.bat deploy-tomcat60

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 don't want to include JOSSO configuration files in the generated war, compile JOSSO using the exclude.config system property set to true :

For Unix systems you should execute :

$ ./build.sh -Dexclude.config=true deploy-tomcat60

For Win32 systems you should execute :

build.bat -Dexclude.config=true deploy-tomcat60

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.

Using Memory Stores When using memory stores you have to copy credential and user files josso-credentials.xml and josso-users.xml to $CATALINA_HOME/lib/

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-tomcat60

For Win32 systems you should execute :

build.bat deploy-samples-tomcat60

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