Configuring JOSSO Gateway

Prerequisites

You should first setup JOSSO for one of the supported platforms such as Tomcat and JBoss, Geronimo or Weblogic.
Check the specific Setup HOW-TO corresponding to the platform where JOSSO is going to be installed.

Once you're done with the initial setup make sure that the JOSSO web application is accessible.

Introduction

This How-To will explain how to integrate your own user and roles database with JOSSO, it provides a specific example but you could use other persistence mechanism and data structure..

It will implement a Credential Store, configured for providing authentication information, like the user password, using JDBC database access.

It will implement an Identity Store, configured for providing identity information, like user roles, using JDBC database access.

Reference

For detailed information on all components, including Directory Server stores and available configuration properties check out the Reference guide.

Create the user and roles database schema

Optional

If you already have your own database schema, this step is not required. You should instead modify the SQL queries in the josso-gateway-config.xml file so that user and roles can be obtained. First of all, you must have a database server available that provides a JDBC driver.

Lets assume that you don't have a user and role tables. We must then create 3 tables :

JOSSO_USER : contains all the users that will be able to sign-on.
JOSSO_ROLE : contains all the roles to which users can be associated.
JOSSO_USER_ROLE : contains the roles associated with each user.
JOSSO_USER_PROPERTY : contains additional properties of the user, like personal data, etc. .

Lets have a look at the ER Diagram :

The DDL SQL scripts should look like the following :

CREATE TABLE JOSSO_ROLE (
       NAME                 VARCHAR2(16) NOT NULL,
       DESCRIPTION          VARCHAR2(64) NULL
);

ALTER TABLE JOSSO_ROLE
       ADD  ( PRIMARY KEY (NAME) ) ;

CREATE TABLE JOSSO_USER (
       LOGIN                VARCHAR2(16) NOT NULL,
       PASSWORD             VARCHAR2(20) NOT NULL,
       NAME                 VARCHAR2(64) NULL,
       DESCRIPTION          VARCHAR2(64) NULL
);

ALTER TABLE JOSSO_USER
       ADD  ( PRIMARY KEY (LOGIN) ) ;


CREATE TABLE JOSSO_USER_PROPERTY (
       LOGIN                VARCHAR2(16) NOT NULL,
       NAME                 VARCHAR2(255) NOT NULL,
       VALUE                VARCHAR2(255) NOT NULL
);

ALTER TABLE JOSSO_USER_PROPERTY
       ADD  ( PRIMARY KEY (LOGIN, NAME) ) ;

CREATE TABLE JOSSO_USER_ROLE (
       LOGIN                VARCHAR2(16) NOT NULL,
       NAME                 VARCHAR2(255) NOT NULL
);

ALTER TABLE JOSSO_USER_ROLE
       ADD  ( PRIMARY KEY (LOGIN, NAME) ) ;

ALTER TABLE JOSSO_USER_PROPERTY
       ADD  ( FOREIGN KEY (LOGIN)
                             REFERENCES JOSSO_USER ) ;

ALTER TABLE JOSSO_USER_ROLE
       ADD  ( FOREIGN KEY (NAME)
                             REFERENCES JOSSO_ROLE ) ;

ALTER TABLE JOSSO_USER_ROLE
       ADD  ( FOREIGN KEY (LOGIN)
                             REFERENCES JOSSO_USER ) ;

            Execute this DDL in your database.

Create sample Users and Roles

After you finished creating the database schema, add sample user and role records. These users should be able to sign-on to JOSSO.

We'll create three roles :

role1
role2
role3

We'll create two users and associate them to the created roles :

user1: which will be part of the 'role1' and 'role2' roles.
user2: which will be part of the 'role3' role.

We'll associate three properties to the two just created users :

user.name: which will hold the first name of the user.
user.lastName: which will hold the lastname of the user.
user.registrationDate: which will hold when the user registred.

Lets look ad the DML script to do this :

INSERT INTO JOSSO_ROLE (NAME,DESCRIPTION) VALUES('role1','The Role1');

INSERT INTO JOSSO_ROLE (NAME,DESCRIPTION) VALUES('role2','The Role2');

INSERT INTO JOSSO_ROLE (NAME,DESCRIPTION) VALUES('role3','The Role3');

INSERT INTO JOSSO_USER (LOGIN,PASSWORD,DESCRIPTION)
        VALUES('user1', 'user1pwd', 'The User1');

INSERT INTO JOSSO_USER_ROLE (LOGIN,NAME) VALUES('user1', 'role1');

INSERT INTO JOSSO_USER_ROLE (LOGIN,NAME) VALUES('user1', 'role2');

INSERT INTO JOSSO_USER (LOGIN,PASSWORD,DESCRIPTION)
        VALUES('user2', 'user2pwd', 'The User2');

INSERT INTO JOSSO_USER_ROLE (LOGIN,NAME) VALUES('user2', 'role3');

INSERT INTO JOSSO_USER_PROPERTY(LOGIN,NAME,VALUE)
        VALUES('user1', 'user.name', 'User1 Name');

INSERT INTO JOSSO_USER_PROPERTY(LOGIN,NAME,VALUE)
        VALUES('user1', 'user.lastName', 'User1 Last Name');

INSERT INTO JOSSO_USER_PROPERTY(LOGIN,NAME,VALUE)
        VALUES('user1', 'user.registrationDate', 'User1 Registration Date');

INSERT INTO JOSSO_USER_PROPERTY(LOGIN,NAME,VALUE)
        VALUES('user2', 'user.name', 'User2 Name');

INSERT INTO JOSSO_USER_PROPERTY(LOGIN,NAME,VALUE)
        VALUES('user2', 'user.lastName', 'User2 Last Name');

INSERT INTO JOSSO_USER_PROPERTY(LOGIN,NAME,VALUE)
        VALUES('user2', 'user.registrationDate', 'User2 Registration Date');

Configure the SSO Gateway

Now we need to tell the Single Sign-On Gateway how to obtain user and role information in order to authenticate users.

We'll also tell the Single Sign-On Gateway how to load the properties of the user.

Modify the josso-gateway-config.xml configuration file located in the /WEB-INF/classes folder of the JOSSO web application.

Lets look at the josso-gateway.xml configuration file content :

<?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>
  <userPropertiesQueryString>
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 = ?
  </userPropertiesQueryString>

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

Make sure you set your specific values for the for the connectionName, connectionPassword, connectionURL and driverName elements according to your database settings.

Do this for both the Credential Store and Identity Manager settings.

Include the database driver in the JOSSO Gateway

Since the SSO Gateway will use the configured driver, in this case the Oracle JDBC Thin Driver, to execute the configured SQL queries, you will need to make this available in the JOSSO Gateway classpath

Go to the JOSSO installation directory and create the /src/webapp/josso/WEB-INF/lib directory.

Copy the Jar file containing the JDBC driver to the JOSSO installation directory, into the /src/webapp/josso/WEB-INF/lib

Rebuild JOSSO to produce a new josso.war file which will include the JDBC driver and deploy it. Follow your platform specific setup guide to perform this operation.

About

Project

Setup

Developer Documentation

Advanced Documentation

Page Operations