1. Introduction

We will integrate JOSSO with your identity ecosystem and leverage the features you need. In order to setup JOSSO we have to install and configure the SSO Gateway (IdP) and at least a SSO Agent (SP). The need for more agents depends on your planned SSO deployment. Take a look at the JOSSO Architecture Overview to help you build a plan that suites your needs.

2. Install JOSSO Gateway (IdP)

The firs thing to do when setting up JOSSO is to install the SSO Gateway (IdP), this section will describe this procedure.

2.1 Prerequisites

• The JEE Container that will host the SSO Gateway.
• JDK 5 or 6 : You can download it at http://java.sun.com/javase/downloads/index.jsp
• JOSSO distribution.

2.2 Using the Deployment Console

JOSSO deployment console has been implemented using Apache Geronimo GShell. GShell is an extensible, command-line processing environment for creating platform independent command-line applications. To start the console, simply unpack JOSSO distribution and run the josso-gsh launcher script located in the bin folder.

A log file will be created in the distribution's _log_folder recording all the activity performed by the console.

c:> cd josso-1.8.0\bin
c:> josso-gsh
    __ _____ _____ _____ _____ 
 __|  |     |   __|   __|     |
|  |  |  |  |__   |__   |  |  |
|_____|_____|_____|_____|_____|

 JOSSO (1.8.0)

Type 'help' for more information.
-------------------------------------------------------
josso> 

The gateway install is used to deploy the Gateway and all required resources like configuration files. Using the command's source option you can deploy your branded Gatweway. Refer to JOSSO Deployment Console documentation for information about available commands and their options.

2.2.2 Gateway Install Matrix

Instructions bellow will show you how to install the Gateway onto different containers using JOSSO Deployment Console.

Platform	Supported	Deployment Console	Install Instructions
JBoss 5.x			install
JBoss 4.2.x			install
JBoss 4.0.x			install
JBoss 3.2.6+			install
Tomcat 6.0			install
Tomcat 5.5			install
Tomcat 5.0			install
Weblogic 10.0			install
Weblogic 9.2			install
Geronimo 2.1			install
Websphere CE			install
Generic J2EE / JEE			install

Partial support, the console will only copy the josso.war file to the specified target directory.

2.3 Using your container deployment facilites

JOSSO Gateway is bundled in a WAR file. Therefore, you can use your container deployment facilities to deploy it. It is recommended to use a Branded Gateway when deploying using this option.

2.3.1 Non-Branded Gateway

If you want to deploy a non-branded Gateway (the one provided with JOSSO distribution) using your container deployment facilities, you have to perform some additional steps:

Install Configuration Files

Make sure that the configuration files are accessible by JOSSO. Install them in where they can be reached by web applications. For example, in JBoss, you can copy them to $JBOSS_HOME/server/<instance>/conf/ folder. Gateway configuration files can be found in JOSSO distribution at josso-1.8.0/dist/gateway/config.

The next thing you have to do is to create a josso-auth.properties and install it with the configuration

This file contains an Base 64 encoded AES key that will be used by the automatic login infrastructure('remember me'). Here's a sample of this file:

#JOSSO 'Remember Me' authentication schemem properties.
#Mon Nov 17 17:43:49 GMT-03:00 2008
josso.rememberme.authscheme.key=udbpOogx0j6Tw1k3JX7q1Q\=\=

3. Configure JOSSO Gateway (IdP)

After installing the gateway, the next thing to do is to leverage JOSSO for your needs. Following there is a list of steps that should cover most common scenarios. Keep in mind that advanced deployments, with more complex requirements like multiple security domains, clustering, fail over, auditing, etc, require additional configuration steps.

3.1 Identity/Credential Stores

This tells JOSSO how to obtain user's identity information like username, roles, credentials, etc. It defines the specific persistence mechanism used to retrieve data. JOSSO provides out of the box identity stores that support the following mechanisms: RDBMS, LDAP (Including Active Directory) and XML.

Stores configuration can be found in josso-gateway-stores.xml file.

Include the correct Stores configuration Make sure to include the configuration file you modified from the gateway main config: josso-gateway-config.xml

    ...
    <!-- Identity, Session and Assertion Stores configuration -->

    <s:import resource="josso-gateway-stores.xml" />

    <!--
    <s:import resource="josso-gateway-memory-stores.xml" />
    <s:import resource="josso-gateway-db-stores.xml" />
    <s:import resource="josso-gateway-ldap-stores.xml" />
    -->
    ...

3.2 Authentication Schemes

This components define the authentication mechanism that will validate user's identity using a set of provided credentials. JOSSO is distributed with several authentication schemes like basic authentication (username/password), strong authentication (digital certificates), Windows Authentication (NTLM), LDAP-Bind Authentication and Automatic Login (Remember Me) among others.

Authenticatio schemes configuration can be found in josso-gateway-auth.xml file.

3.3 Branding

You may want to modify JOSSO UI appearance, add specific resources like JDBC drivers or even include custom components. Branding JOSSO will help you achieve this goals by creating your own JOSSO Gateway (IdP) distribution. Refer to the Branding JOSSO guide for details.

4. Some Sample Setups

Database Setup