Added by Sebastian Gonzalez Oyuela, last edited by Sebastian Gonzalez Oyuela on Mar 14, 2008  (view change)

Labels:

Enter labels to add to this page:
Wait Image 
Looking for a label? Just start typing.

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

Introduction

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.

Building

JBoss 4.2.1,4.2.0

To install JOSSO In JBoss 4.2.1 and previous 4.2.x version, you will have replace the $JBOSS_HOME/server/<instance>/deploy/jboss-web.deployer path with $JBOSS_HOME/server/<instance>/deploy/jboss-web.deployer. Remember to also move all files copied during JOSSO Install and deployment procedures to the proper directory.

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.8.2 directory :

  • josso.ear
  • josso-1.8.2.jar
  • josso-common-1.8.2.jar

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

  • josso-tomcat55-plugin-1.8.2.jar
  • josso-jboss42-plugin-1.8.2.jar

The josso.war file contains the server part of the Single Sign-On, while the josso-1.8.2.jar file contains the stubs needed to integrate the web infrastructure to the SSO authentication schemes. The josso-common-1.8.2.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.

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

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

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. If your JBoss instance is not default, copy your instance conf directory.

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>

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 $JBOSS_HOME/server/default/conf 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 $JBOSS_HOME/server/default/conf 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-gateway-config.xml to $JBOSS_HOME/server/default/conf directory and import it from the josso-config.xml file.

The Single Sign-On Gateway has its own josso-config.xml configuration file, which is completely independent of the $JBOSS_HOME/server/default/conf/josso-config.xml. The JOSSO configuration files located in the $JBOSS_HOME/server/default/conf directory (josso-) are only used by the Single Sign-on Agent and Reverse Proxy components. If you want to place all JOSSO configuration files together, including the gateway configuration, you can : move alljosso-* files to *$JBOSS_HOME/server/default/conf directory, set the following build property to true : exclude.config=true when building and deploying, and modify the josso-config.xml file to include all necessary files : josso-agent-config.xml, josso-gateway-config.xml, etc. Add this property to your local.build.properties file, located in the $JOSSO_HOME directory.

Protect a Web Application

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/jboss-web.deployer/server.xml file in the following way :

<Server>
          ...
          <Service>
            ...
            <Engine>
              ...
              <Host name="localhost" ...>
                ...
                <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.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/jboss-web.deployer/server.xml file that must have the following content :

<Server>
      ...
      <Service name="jboss.web">
        ...
        <Engine name="jboss.web" defaultHost="localhost">
          ...
          <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>

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-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.jb42.agent.JBossCatalinaSSOAgent</class>
  <gatewayLoginUrl>http://localhost:8080/josso/signon/login.do</gatewayLoginUrl>
  <gatewayLogoutUrl>http://localhost:8080/josso/signon/logout.do</gatewayLogoutUrl>
  <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.
  • The Single Sign-On partner application web contexts

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 agent and the gateway 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.

This configuration file defines only one partner application associated with the /partnerapp web context. This means that the web application associated with the /partnerapp web context will be put behind the Single Sign-On. You can define one or more partner applications.

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.8.2.jar, josso-common-1.8.2.jar, josso-tomcat55-plugin-1.8.2.jar , josso-jboss42-plugin-1.8.2.jar files to the $JBOSS_HOME/server/default/deploy/jboss-web.deployer 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.

JBoss 4.2.2.GA+ Support patch

This are instructions to apply the Josso 1.6-1830606 patch

This patch provides support for JBoss 4.2.2.GA

Applying the patch :

1. First, the JOSSO_HOME environment variable must be set to the JOSSO distribution directory.

For Unix systems you can use :

$ export JOSSO_HOME=/usr/local/josso-1.6

For Win32 systems you can use :

set JOSSO_HOME=c:\josso-1.6

2. Once you have set JOSSO_HOME environment variable you can apply the patch to your JOSSO 1.6 distribution.

For Unix systems you should execute :

$ ./apply-patch-1830606.sh

For Win32 systems you could use CYGWIN and execute :

$ ./apply-patch-1830606.sh
CYGWIN patch utility

For Win32 systems using CYGWIN, make sure you have the patch utility installed.

Now that the patch has been applied, you should build and deploy JOSSO as described above.

Comments

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