Dashboard > JOSSO 1 > ... > Advanced Documentation > Configure using a GUI
JOSSO 1
Configure using a GUI
Added by Sebastian Gonzalez Oyuela, last edited by Sebastian Gonzalez Oyuela on Jul 30, 2008  (view change)
Labels: 
(None)

The application used for configuring JOSSO in a user-friendly fashion through a graphical user interface is actually a JMX Management Console capable of altering manageable applications state and properties.

The JMX Management console that will be considered in this technical guide is the MC4J which can be downloaded from mc4j

Once installed, an additional environment variable called MC4J_HOME must be set pointing to the location where the MC4J JMX Console resides.

For Unix systems you can use : 

$ export MC4J_HOME="/usr/local/MC4J Console 1.2b9"
$ export JOSSO_HOME=/usr/local/josso-1.5

For Win32 systems you can use : 

set MC4J_HOME="C:\MC4J Console 1.2b9"
set JOSSO_HOME=C:\josso-1.5

Introduction

In order for allowing GUI-based JOSSO configuration, as mentioned before, the JMX support available in the product is the main enabler for this feature.

Every update made to a property-s value through the JMX Console can, in addition to affecting the behaviour of JOSSO on the fly, make such change explicitly persistent . This means that property updates are persisted in the standard Xml JOSSO configuration files as if a manual update would have taken place, making JOSSO capable of restoring and working using its latest state, even after a restart.

This How-To will explain how to configure JOSSO Single Sign-On using a GUI, in this case MC4J. We're assuming that basic :

  • Basic Authentication is used
  • Users, roles and credentials are stored in the database
  • Password are stored as plain text
  • Single Sign-On Sessions are volatible which means that they are kept in memory

Installing JOSSO

If you're using one of JOSSO bundles like the ones available for JBoss or Tomcat you can skip this section.

In order to be able to configure JOSSO using a GUI, follow the Building, Installing and Deploying section of the technical guide corresponding to your platform such as the HOW-TO, for example JBoss 4.x Setup HOW-TO.

Next modify server specific files, such as server.xml, leaving JOSSO configuration files as they are. We'll get back later on them.

Remember to build and deploy JOSSO using the exclude.config set to true. Details on how to do this can be found in the Deployment section of the Setup HOW-TOs

Once JOSSO has been built, installed and deployed copy the JOSSO configuration files to your container-specific configuration directory :

Tomcat

For Unix systems you can use : 

$ cp $JOSSO_HOME/src/resources/josso-*.xml $CATALINA_HOME/bin

For Win32 systems you can use : 

copy %JOSSO_HOME%\src\resources\josso-*.xml %CATALINA_HOME%\bin

If using Tomcat 5.5 with JDK 1.5 you must install Apache Xalan-J. Some APIs used by the management infrastructure are not compatible with the Xalan part of the JDK 1.5 . Simply copy all jars found in Xalan-J distribution root directory to $CATALINA_HOME/common/endorsed.
Xalan-J is already included in the JOSSO bundle for the Tomcat Container.

JBoss

For Unix systems you can use : 

$ cp $JOSSO_HOME/src/resources/josso-*.xml $JBOSS_HOME/server/default/conf

For Win32 systems you can use : 

copy %JOSSO_HOME%\src\resources\josso-*.xml %JBOSS_HOME%\server\default\conf

If your JBoss instance name is not 'default', modify the destination path when copying JOSSO configuration files using the corresponding instance name, for example %JBOSS_HOME%\server\my-instance\conf

There is no need to modify JOSSO configuration files yet. We'll setup JOSSO later as described in the next sections.

Select JOSSO components

So far we have installed and deployed JOSSO keeping the default setup : basic authentication using memory identity and session stores. Now we'll configure JOSSO by choosing the set of components that will satisfy our specific requirements.

JOSSO components must be selected by editing the JOSSO gateway configuration file. The file comes with commented configuration blocks with default settings for all components. The only thing that mus be done is to comment/uncomment component configuration blocks until reaching the desired configuration. In this particular case we will uncomment the Memory Identity stores and DB identity stores configuration blocks . Component properties will be later updated using the MC4J Console.

Let's take a look at our modified file, unused components were removed for clarity :

<?xml version="1.0" encoding="ISO-8859-1" ?>
<domain>
    <name>JOSSO</name>
    <type>web</type>
    <authenticator>
        <class>org.josso.auth.AuthenticatorImpl</class>
        <authentication-schemes>

            <authentication-scheme>
                <name>basic-authentication</name>
                <class>org.josso.auth.scheme.UsernamePasswordAuthScheme</class>
                <hashAlgorithm>MD5</hashAlgorithm>
                <hashEncoding>HEX</hashEncoding>
                <ignorePasswordCase>false</ignorePasswordCase>
                <ignoreUserCase>false</ignoreUserCase>

                <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>josso</connectionName>
                    <connectionPassword>josso</connectionPassword>
                    <connectionURL>jdbc:oracle:thin:@localhost:1521:josso_db</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>
        <sso-identity-store>
            <class>org.josso.gateway.identity.service.store.db.JDBCIdentityStore</class>
            <userQueryString>
                SELECT login FROM josso_user WHERE login = ?
            </userQueryString>
            <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>
            <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>josso</connectionName>
            <connectionPassword>josso</connectionPassword>
            <connectionURL>jdbc:oracle:thin:@localhost:1521:josso_db</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>
        <maxInactiveInterval>30</maxInactiveInterval>
        <maxSessionsPerUser>-1</maxSessionsPerUser>
        <invalidateExceedingSessions>false</invalidateExceedingSessions>
        <sessionMonitorInterval>10000</sessionMonitorInterval>
        <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>
            <algorithm>MD5</algorithm>

        </sso-session-id-generator>

    </sso-session-manager>

    <sso-audit-manager>
        <class>org.josso.gateway.audit.service.SSOAuditManagerImpl</class>
        <handlers>
            <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>
        <class>org.josso.gateway.event.security.JMXSSOEventManagerImpl</class>
        <oname>josso:type=SSOEventManager</oname>

    </sso-event-manager>

</domain>

Note that no component settings were modified, only some file sections were uncommented to obtain our new SSO base configuration.

In case you modify the josso-config.xml file, remember to reference both, agent and gateway configurations. Let's see the following sample : 

<?xml version="1.0" encoding="ISO-8859-1" ?>
<configuration>
  <hierarchicalXml fileName="josso-gateway-config.xml"/>
  <hierarchicalXml fileName="josso-agent-config.xml"/>
</configuration>

MC4J Setup

JMX support is not included in Tomcat as explained in the Monitoring and Managing Tomcat guide.

For a quick start follow these steps :

Modify your Tomcat startup script (catalina.sh for Unix systems and catalina.bat for Windows) :

For Unix systems, modify $CATALINA_HOME/bin/catalina.sh

export CATALINA_OPTS="-Dcom.sun.management.jmxremote \
    -Dcom.sun.management.jmxremote.port=8999 \
    -Dcom.sun.management.jmxremote.ssl=false \
    -Dcom.sun.management.jmxremote.authenticate=false"

For Windows systems, modify %CATALINA_HOME%\bin\catalina.bat

set CATALINA_OPTS="-Dcom.sun.management.jmxremote \
    -Dcom.sun.management.jmxremote.port=8999 \
    -Dcom.sun.management.jmxremote.ssl=false \
    -Dcom.sun.management.jmxremote.authenticate=false"

Next start JOSSO, launch the MC4J console and create a new server connection. Once the server is up, go to Management menu and select Create Server Connection. A Wizard will guide through the required configuration steps. Make sure to modify the server Url in case the console and JOSSO are not running in the same host.

GUI Based configuration

Now that JOSSO is up and running, we can use MC4J to configure every aspect of the SSO. In our example we will configure the basic authentication scheme, both the identity and credential stores and the session manager settings.

List of JOSSO Mbeans :

Configure the Identity Store

Let's take a look at the Identity Store MBean. To display a MBean basic view, right-click on the MBean node and select Available Dashboards and then select Basic MBean View :


If you want to view attribute properties, right-click on the desired attribute node and select Properties. You will see the attribute name, a description with information about the attribute function, a flag indicating whether this attribute can be modified or not and the attribute current value:

We can now configure our Identity Store properties. In this case we'll modify the connectionURL, connectionName and connectionPassword properties leaving the default values for SQL queries. Note that by looking at the className property value of this theMBean we know that an JDBC Identity Store is being used

These are the values being updated :

  • connectionURL: jdbc:oracle:thin:@my-db-host:1521:JOSSO
  • connectionName: JOSSO_USER
  • connectionPassword: JOSSO_PWD

Remember that these changes will appear in the josso-gateway-config.xml configuration file and will take effect immediately.

One way to modify MBean properties is to double-click on the MBean node and edit property values :

Configure the Credential Store

Now we'll configure the Credential Store. In our example credentials are stored using the same persistence mechanism. Let's modify the following properties :

  • connectionURL: jdbc:oracle:thin:@my-db-host:1521:JOSSO
  • connectionName: JOSSO_USER
  • connectionPassword: JOSSO_PWD

Configure the Authentication Scheme

Now we'll configure the basic-authentication scheme. Since we're storing passwords as plain text we will need to clear the hashAlgorithm and hashEncoding attribute values.

Modified properties :

Configure the Session Manager

Finally we'll configure the Session Manager by increasing the maximum session inactive interval from 30 minutes to one hour and decreasing the session monitor interval from 10 seconds to 2 seconds.

Modified properties :

Let's take a look at the josso-gateway-config.xml file after we completed the above configuration steps. The file was automatically updated with the new JOSSO component settings. 

<?xml version="1.0" encoding="UTF-8"?><domain>
    <name>JOSSO</name>
    <type>web</type>
    <authenticator>
        <class>org.josso.auth.AuthenticatorImpl</class>
        <authentication-schemes>

            <authentication-scheme>
                <name>basic-authentication</name>
                <class>org.josso.auth.scheme.UsernamePasswordAuthScheme</class>
                <hashAlgorithm/>
                <hashEncoding/>
                <ignorePasswordCase>false</ignorePasswordCase>
                <ignoreUserCase>false</ignoreUserCase>

                <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>josso</connectionName>
                    <connectionPassword>josso</connectionPassword>
                    <connectionURL>jdbc:oracle:thin:@localhost:1521:josso_db</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>
        <sso-identity-store>
            <class>org.josso.gateway.identity.service.store.db.JDBCIdentityStore</class>
            <userQueryString>
                SELECT login FROM josso_user WHERE login = ?
            </userQueryString>
            <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>
            <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>JOSSO_USER</connectionName>
            <connectionPassword>JOSSO_PWD</connectionPassword>
            <connectionURL>jdbc:oracle:thin:@my-db-host:1521:JOSSO</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>
        <maxInactiveInterval>60</maxInactiveInterval>
        <maxSessionsPerUser>-1</maxSessionsPerUser>
        <invalidateExceedingSessions>false</invalidateExceedingSessions>
        <sessionMonitorInterval>2000</sessionMonitorInterval>
        <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>
            <algorithm>MD5</algorithm>

        </sso-session-id-generator>

    </sso-session-manager>

    <sso-audit-manager>
        <class>org.josso.gateway.audit.service.SSOAuditManagerImpl</class>
        <handlers>
            <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>
        <class>org.josso.gateway.event.security.JMXSSOEventManagerImpl</class>
        <oname>josso:type=SSOEventManager</oname>

    </sso-event-manager>

</domain>

You could also configure other JOSSO components like the SSO Agent.

Comments

Care to comment on this How-To? Help keep this document relevant by passing along any constructive feedback to the josso-docs
Site running on a free Atlassian Confluence Open Source Project License granted to JOSSO. Evaluate Confluence today.
Powered by Atlassian Confluence, the Enterprise Wiki. (Version: 2.6.0 Build:#913 Sep 27, 2007) - Bug/feature request - Contact Administrators