21.4. Java™ Open Single Sign-On (JOSSO)

JBoss Portal enables seamless integration with JOSSO server version 1.8. More details on JOSSO can be found here

Note

The steps below assume that JOSS server and JBoss Portal will be deployed on the same JBoss Application Server instance. JOSSO will be configured to leverage identity services exposed by JBoss Portal to perform authentication. Procedure may be slightly different for other deployment scenarios. Both JBoss Portal and JOSSO will need to be configured to authenticate against same database or LDAP server. Please see JOSSO documentation to learn how to setup it up against proper identity store.

Note

Configuration below assumes that JOSSO is already installed and deployed in the JBoss Application Server. This involves adding proper jar files into the classpath and altering several configuration files (adding Apache Tomcat Valves, security realm and specific JOSSO configuration files). For JBoss setup please refer to JOSSO documentation

21.4.1. Integration steps

  1. Copy portal-identity-lib.jar and portal-identity-sso-lib.jar files from $JBOSS_HOME/server/default/deploy/jboss-portal.sar/lib to $JBOSS_HOME/server/default/deploy/josso.ear/josso.war/WEB-INF/lib.
  2. Edit $JBOSS_HOME/server/default/deploy/jboss-portal.sar/portal-server.war/WEB-INF/context.xml file and enable proper Apache Tomcat Valve by uncommenting following lines:
                         
    <Valve className="org.jboss.portal.identity.sso.josso.JOSSOLogoutValve"/>
    
    
  3. Edit $JBOSS_HOME/server/default/config/josso-agent-config.xml and mapping for portal web application:
                
                         
    .........
    <configuration>
        <agent:agent-configuration>
        <agent:partner-apps>
                <agent:partner-app id="jboss_portal" context="/portal"/>
            </agent:partner-apps>
        </agent:agent-configuration>
    <configuration>
    ...........
    
    
    Complete config file can look as follows:
                         
    <?xml version="1.0" encoding="UTF-8" ?>
    <!--
      ~ JOSSO: Java Open Single Sign-On
      ~
      ~ Copyright 2004-2009, Atricore, Inc.
      ~
      ~ This is free software; you can redistribute it and/or modify it
      ~ under the terms of the GNU Lesser General Public License as
      ~ published by the Free Software Foundation; either version 2.1 of
      ~ the License, or (at your option) any later version.
      ~
      ~ This software is distributed in the hope that it will be useful,
      ~ but WITHOUT ANY WARRANTY; without even the implied warranty of
      ~ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
      ~ Lesser General Public License for more details.
      ~
      ~ You should have received a copy of the GNU Lesser General Public
      ~ License along with this software; if not, write to the Free
      ~ Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
      ~ 02110-1301 USA, or see the FSF site: http://www.fsf.org.
      ~
      -->
    
    <s:beans xmlns:s="http://www.springframework.org/schema/beans"
             xmlns:jb42="urn:org:josso:agent:jboss42"
             xmlns:agent="urn:org:josso:agent:core"
             xmlns:protocol="urn:org:josso:protocol:client"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
             urn:org:josso:agent:jboss42 http://www.josso.org/schema/josso-jboss42-agent.xsd
             urn:org:josso:agent:core http://www.josso.org/schema/josso-agent.xsd
             urn:org:josso:protocol:client http://www.josso.org/schema/josso-protocol-client.xsd">
    
        <jb42:agent name="josso-jboss42-agent" sessionAccessMinInterval="1000" >
    
            <!-- Gateway LOGIN and LOGOUT URLs -->
            <gatewayLoginUrl>http://josso-01:8080/josso/signon/login.do</gatewayLoginUrl>
            <gatewayLogoutUrl>http://josso-01:8080/josso/signon/logout.do</gatewayLogoutUrl>
    
            <!-- Gateway service locator -->
            <gatewayServiceLocator>
                <!-- Other properties for ws-service-locator :
                username, password, servicesWebContext, transportSecurity
                -->
                <protocol:ws-service-locator endpoint="josso-01:8080" />
            </gatewayServiceLocator>
    
            <configuration>
                <agent:agent-configuration>
    
                    <!-- ============================================================================= -->
                    <!--                                                                               -->
                    <!-- JOSSO Parnter application definicions :                                       -->
                    <!--                                                                               -->
                    <!-- Configure all web applications that should be a josso partner application     -->
                    <!-- within this server.                                                           -->
                    <!-- For each partner application you have to define the proper web-context.      -->
                    <!-- ============================================================================= -->
                    <agent:partner-apps>
                        <agent:partner-app id="jboss_portal" context="/portal"/>
    
                    </agent:partner-apps>
                </agent:agent-configuration>
            </configuration>
            <!-- Only useful when configuring multiple security domains -->
            <!-- You can configure your own parameter builder to send parameters to your SecurityDomainMatcher  -->
            <!--
            <parametersBuilders>
                <agent:vhost-parameters-builder/>
                <agent:appctx-parameters-builder/>
            </parametersBuilders>
            -->
    
        </jb42:agent>
    
    </s:beans>
    
    
  4. Edit $JBOSS_HOME/server/default/deploy/jboss-portal.sar/portal-server.war/login.jsp and $JBOSS_HOME/server/default/deploy/jboss-portal.sar/portal-server.war/erros.jsp and uncomment following line:
                         
    <%
      response.sendRedirect(request.getContextPath() + "/josso_login/");
    %>
    
    
    (make sure to remove java style comment '/* */' - not the xml one).
  5. Edit $JBOSS_HOME/server/default/deploy/jboss-portal.sar/META-INF/jboss-service.xml file and uncomment following lines:
                      
    <mbean
        code="org.jboss.portal.identity.sso.josso.JOSSOIdentityServiceImpl"
        name="portal:service=Module,type=JOSSOIdentityService"
        xmbean-dd=""
        xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean">
        <xmbean/>
        <depends>portal:service=Module,type=IdentityServiceController</depends>
    </mbean>
    
    
    This will expose a special service in JBoss Portal that can be leveraged by JOSSO Credential and Identity Stores if the server is deployed on the same application server instance.
  6. Activate JAAS based Login Module by configuring the following:
    • $JBOSS_HOME/server/default/deploy/conf/login-config.xml
                                 
      <application-policy name="josso">            
              <authentication>
                  <login-module code="org.jboss.portal.identity.sso.josso.JOSSOLoginModule" flag="required">
                      <module-option name="debug">true</module-option>
                  </login-module>
              </authentication>
      </application-policy>
      
      
    • $JBOSS_HOME/server/default/deploy/jboss-portal.sar/portal-server.war/WEB-INF/jboss-web.xml
                                 
      <jboss-web>
      <security-domain>java:jaas/josso</security-domain>
      .........
      
      
  7. Register the JBoss Portal Identity and Credential Store by configuring the following:
    • Add the file$JBOSS_HOME/server/default/deploy/conf/josso-gateway-portal-stores.xml
                                 
      <s:beans xmlns:s="http://www.springframework.org/schema/beans"
             xmlns:portal-istore="urn:org:jboss:portal:josso:identitystore"
             xmlns:memory-sstore="urn:org:josso:memory:sessionstore"
             xmlns:memory-astore="urn:org:josso:memory:assertionstore"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="
              http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd        
              urn:org:josso:memory:sessionstore http://www.josso.org/schema/josso-memory-sessionstore.xsd
              urn:org:josso:memory:assertionstore http://www.josso.org/schema/josso-memory-assertionstore.xsd
              ">
          <!-- ===================================================================== -->
          <!-- JOSSO Identity Store, the id is very important because it is          -->
          <!-- referenced by the identity manager, auth schemes and who knows where  -->
          <!-- else.                                                                 -->
          <!-- ===================================================================== -->
          <portal-istore:portal-store id="josso-identity-store" s:scope="singleton"/>                            
      
          <!-- ===================================================================== -->
          <!-- JOSSO Session Store, the id is very important because it is           -->
          <!-- referenced by the session manager and who knows where else            -->
          <!-- ===================================================================== -->
          <memory-sstore:memory-store id="josso-session-store"/>
      
          <!-- ===================================================================== -->
          <!-- JOSSO Assertion Store, the id is very important because it is         -->
          <!-- referenced by the assertion manager and who knows where elese         -->
          <!-- ===================================================================== -->
          <memory-astore:memory-store id="josso-assertion-store"/>
      </s:beans>
      
      
    • Register the Portal Identity Store with the file $JBOSS_HOME/server/default/deploy/conf/josso-gateway-config.xml
                                 
      ............                           
      <!-- Identity, Session and Assertion Stores configuration -->
          <s:import resource="josso-gateway-portal-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" />
          -->
      ............    
      
      
  8. Enable BIND Authentication Scheme by configuring the following:
    • Uncomment the BIND Authentication Scheme in $JBOSS_HOME/server/default/deploy/conf/josso-gateway-auth.xml
                                 
      ............                           
      <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
          <!-- BIND Authentication Scheme (normally LDAP) -->
          <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
          <!-- Requires a be a bindalble credential store ! -->
          <!-- name attribute is important and must not be changed -->
          <bind-authscheme:bind-auth-scheme
                  id="josso-bind-authentication"
                  name="basic-authentication"
                  hashAlgorithm="MD5"
                  hashEncoding="HEX"
                  ignorePasswordCase="false"
                  ignoreUserCase="false">
      
              <bind-authscheme:credentialStore>
                  <s:ref bean="josso-identity-store"/>
              </bind-authscheme:credentialStore>
      
              <bind-authscheme:credentialStoreKeyAdapter>
                  <s:ref bean="josso-simple-key-adapter"/>
              </bind-authscheme:credentialStoreKeyAdapter>
          </bind-authscheme:bind-auth-scheme>
      ............    
      
      
    • Register BIND Authentication Scheme with the JOSSO Authenticator in $JBOSS_HOME/server/default/deploy/conf/josso-gateway-config.xml
                                 
      ............                           
      <!-- ===================================================================== -->
      <!-- SSO Authenticator, all authentication schemes must be configured here -->
      <!-- ===================================================================== -->
          <def-auth:authenticator id="josso-authenticator">
              <def-auth:schemes>      
              <s:ref bean="josso-bind-authentication"/>
          <!--
                  <s:ref bean="josso-basic-authentication"/>
                  <s:ref bean="josso-strong-authentication"/>
                  <s:ref bean="josso-rememberme-authentication"/>
          -->
                  <!-- Others like NTLM and BIND go here -->
          <!--
                  <s:ref bean="josso-bind-authentication"/>
          -->
             </def-auth:schemes>
          </def-auth:authenticator>
      ............    
      
      
To test the integration:
  • Go to your portal. Typically, http://localhost:8080/portal
  • Click on the "Login" link on the main portal page
  • This should bring up the JOSSO login screen instead of the default JBoss Portal login screen
  • Input your portal username and password. For built-in portal login try user:user or admin:admin
  • If login is successful, you should be redirected back to the portal with the appropriate user logged in