Added by Sebastian Gonzalez Oyuela, last edited by Gianluca Brigandi on Mar 20, 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_13

For Win32 systems you can use :

set JAVA_HOME=c:\jdk1.5.0_13

JOSSO can be deployed in the Weblogic 9.2 application server, providing the authenticated user's identity to the partner web application, EJBs and other components using Weblogic Security Infrastructure. Integration is achieved using Weblogic Security Framework.

In order to integrate JOSSO with Weblogic to implement a Single Sign-on Infrastructure, you should use Weblogic 9.2. Other versions may work but have not been tested yet.

BEA environment variables must be set pointing to the installation directory of Weblogic server.

For Unix systems you can use :

$ export WL_HOME="/opt/bea/weblogic92"
$ export DOMAIN_HOME="$WL_HOME/samples/domains/wl_server"

For Win32 systems you can use :

set WL_HOME=c:\bea\weblogic92
set DOMAIN_HOME=%WL_HOME%\samples\domains\wl_server

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 -Dinclude.plugin.wls92=true build-wls92

For Win32 systems you should execute :

build.bat -Dinclude.plugin.wls92=true build-wls92

It is important to include the -Dinclude.plugin.wls92=true part because Weblogic plugin is disabled by default and will not be built. You can also modify this property in the build.properties configuration file located in the projcect root.

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

  • wl-josso-
    1.8.2
    .jar
  • wl-josso-web-
    1.8.2
    .jar
  • wl-josso-wsl92-plugin-mbeans-
    1.8.2
    .jar

Installing

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

For Unix systems you should execute :

$ ./build.sh -Dinclude.plugin.wls92=true deploy-wls92

For Win32 systems you should execute :

build.bat -Dinclude.plugin.wls92=true deploy-wls92

This procedure must be done only once. The installation will copy the following files, you can remove unused files when deploying only a gateway or an agent:

In $DOMAIN_HOME/lib

  • wl-josso-
    1.8.2.jar needed by gateway and agent
  • josso-common-
    1.8.2.jar needed by gateway and agent

In $DOMAIN_HOME/lib/mbeantypes

  • wl-josso-wsl92-plugin-mbeans-
    1.8.2.jar needed by agent

In $DOMAIN_HOME/autodeploy

  • josso.ear needed by gateway
    josso.ear deployment

    If Weblogic is not running in development mode, the josso.ear file must be deployed using then Administration Console.

    This will install JOSSO on the Weblogic DOMAIN referenced by the DOMAIN_HOME environment variable. If you want to use a different domain, set the DOMAIN_HOME environment variable to the proper domain name. You can use any domain name, for example build.sh -DDOMAIN_HOME=$WL_HOME/myServer/domains/myDomain

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 $DOMAIN_HOME 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 $DOMAIN_HOME

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 $DOMAIN_HOME 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 $DOMAIN_HOME 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>

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 $DOMAIN_HOME 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 $DOMAIN_HOME 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 $DOMAIN_HOME directory and import it from the josso-config.xml file.

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.

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.wls92.agent.WLSSSOAgent</class>

  <!-- Modify this URLs and replace localhost with the proper host name -->
  <gatewayLoginUrl>http://localhost:7001/josso/signon/login.do</gatewayLoginUrl>
  <gatewayLogoutUrl>http://localhost:7001/josso/signon/logout.do</gatewayLogoutUrl>

  <sessionAccessMinInterval>1000</sessionAccessMinInterval>

  <service-locator>
    <class>org.josso.gateway.WebserviceGatewayServiceLocator</class>
    <endpoint>localhost:7001</endpoint>
  </service-locator>
  <partner-apps>
      <partner-app>
          <context>/partnerapp</context>
      </partner-app>
  </partner-apps>
</agent>
Gateway host name

You have to modify the gatewayLoginUrl and gatewayLogoutUrl replacing localhost with the proper host name. If the gateway is not running on the same server you also have to modify the endpoint, for example 192.168.1.99:8080

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.

Configuring a new Authenticator

Now that the SSO Gateway and Agent are installed and configured, we need to configure a new Authentication Provider using Weblogic Administration Console. The first thing to do is to start weblogic, so change to the $DOMAIN_HOME/bin directory and start weblogic :

For Unix systems you can use :

$ ./startWeblogic.sh

1 - Access the administration console and click the "Security Realms" option from Your Application's Security Settings section :

2 - Select the Realm where you're adding the new Authentication Provider, we'll use myrealm in this how-to :

3 - Select the Providers section, you will see a list with configured Authenticators

4 - Now, click the New button to add JOSSO Authenticator

You need to click the Lock&Edit button to be able to add a new Authenticator

Name the Authenticator JOSSO Authenticator and select the JOSSOAuthenticator type from the list.

5 - Click the Reorder button and place JOSSO Authenticator first.

6 - Configure the Authenticators and set the Control Flag to SUFFICIENT

Setting Authenticator's Control Flag to SUFFICIENT will allow weblogic to authenticate users if any of them succeeds.

7 - Save and confirm changes, now JOSSO will authenticate configured applications

Try to access the partner application, if you are using the Memory Identity Store and Credential Store,
you can login as user1 and user1pwd

You many need to restart Weblogic after configuring the Authenticator

Integrating your Java Application with JOSSO

For details on how to integrate your Java Web applications with JOSSO, take a look at the Java Developer Documentation