Chapter 20. Single Sign ON
Prev |  | Next

## Chapter 20. Single Sign ON

### Boleslaw Dawidowicz

`<boleslaw dot dawidowicz at redhat dot com>`

### Sohil Shah

`<sshah@redhat.com>`

This chapter describes how to setup SSO in JBoss Portal

## 20.1. Overview of SSO in portal

Portal as an integration and aggregation platform provides some form of SSO by itself. When you log into the portal you gain access to many systems through portlets using a single identity. Still in many cases you need to integrate the portal infrastructure with other SSO enabled systems. There are many different Identity Management solutions on the market. In most cases each SSO framework provides its own way to plug into Java EE application. For custom configurations you need to have a good understanding of JBoss Portal Identity management and authentication mechanisms.

## 20.2. Using Tomcat Valve

JBoss Application Server embeds Apache Tomcat as the default servlet container. Tomcat provides a builtin SSO support using a valve. The Single Sign On Valve caches credentials on the server side, and then invisibly authenticate users when they reach different web applications. Credentials are stored in a host-wide session which means that SSO will be effective throughout the session.

### 20.2.1. Enabling Tomcat SSO Valve

To enable SSO valve in Tomcat you should uncomment the following line

    <Valve className=’org.apache.catalina.authenticator.SingleSignOn’/>

in the `$JBOSS_HOME/server/default/deploy/jboss-web.deployer/server.xml` file. More information can be found here.

### 20.2.2. Example of usage

Lets look a little bit closer and configure SSO between portal and other web application. As an example we'll use jmx-console web-app that comes with every JBoss Application Server installation. You can find more information on how to secure jmx-console in JBoss AS wiki.

1. Take a clean install of JBoss Application Server

2. Edit $JBOSS_HOME/server/default/deploy/jmx-console.war/WEB-INF/web.xml file and make sure it contains following content:

       <security-constraint>
         <web-resource-collection>
           <web-resource-name>HtmlAdaptor</web-resource-name>
           <description>An example security config that only allows users with the
             role JBossAdmin to access the HTML JMX console web application
           </description>
           <url-pattern>/*</url-pattern>
           <http-method>GET</http-method>
           <http-method>POST</http-method>
         </web-resource-collection>
         <auth-constraint>
           <role-name>Admin</role-name>
         </auth-constraint>
       </security-constraint>

       <security-constraint>
         <web-resource-collection>
           <web-resource-name>Public</web-resource-name>
           <url-pattern>/public/*</url-pattern>
           <http-method>GET</http-method>
           <http-method>POST</http-method>
         </web-resource-collection>
       </security-constraint>

       <login-config>
         <auth-method>BASIC</auth-method>
         <realm-name>jmx-console</realm-name>
       </login-config>

       <security-role>
          <role-name>Admin</role-name>
       </security-role>

   This will secure jmx-console web application using BASIC browser authentication and restrict access for users with Admin role only.

3. Edit $JBOSS_HOME/server/default/conf/props/jmx-console-roles.properties file and make it contain:

       admin=JBossAdmin,HttpInvoker,Admin

   This file is a simple identity store for this web application authentication. It will make user admin belongs to Admin role.

4. Deploy JBoss Portal

5. Run JBoss Application Server

6. Now you can check that when you go to

   - http://localhost:8080/portal
   - http://localhost:8080/jmx-console

   you need to authenticate separately into each of those web applications.

7. Shutdown Application Server

8. Uncomment the following line

       <Valve className=’org.apache.catalina.authenticator.SingleSignOn’/>

   in the `$JBOSS_HOME/server/default/deploy/jboss-web.deployer/server.xml` file. More information can be found here.

   Run JBoss Application Server.

Now if you log into portal as user admin with password admin, you won't be asked for credentials when accessing jmx-console. This should work in both directions.

### Note

Please note that in this example jmx-console uses BASIC authentication method. This means that user credentials are cached on the client side by browser and passed on each request. Once authenticated to clear authentication cache you may need to restart browser.

## 20.3. CAS - Central Authentication Service

This Single Sign On plugin enables seamless integration between JBoss Portal and the CAS Single Sign On Framework. Details about CAS can be found here

### 20.3.1. Integration steps

### Note

The steps below assume that CAS server and JBoss Portal will be deployed on the same JBoss Application Server instance. CAS 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 CAS will need to be configured to authenticate against same database or LDAP server. Please see CAS documentation to learn how to setup it up against proper identity store.

### Note

Configuration below assumes that JBoss Application Server is HTTPS enabled and operates on standard ports: 80 (for HTTP) and 443 (for HTTPS).

1. Install CAS server (v 3.0.7). This should be as simple as deploying single cas.war file.
2. 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/cas.war/WEB-INF/lib.
3. Edit $JBOSS_HOME/server/default/deploy/jboss-portal.sar/portal-server.war/WEB-INF/context.xml file and enable proper tomcat valve by uncommenting following lines:

       <Valve className="org.jboss.portal.identity.sso.cas.CASAuthenticationValve"
          	casLogin="https://localhost/cas/login"
          	casValidate="https://localhost/cas/serviceValidate"
          	casServerName="localhost"
          	authType="FORM"
       />

   Update valve options as follow:
   - casLogin: URL of your CAS Authentication Server
   - casValidate: URL of your CAS Authentication Server validation service
   - casServerName: the hostname:port combination of your CAS Authentication Server

   ### Note

   CAS client requires to use SSL connection. To learn how to setup JBoss Application Server to use HTTPS see here
4. Copy casclient.jar into $JBOSS_HOME/server/default/deploy/jboss-portal.sar/lib. You can download this file from CAS homepage or from JBoss repository under http://repository.jboss.com/cas/3.0.7/lib/

   ### Note

   The CAS engine does not accept self-signed SSL certificates. This requirement is fine for production use where a production level SSL certificate is available. However, for testing purposes, this can get a little annoying. Hence, if you are having this issue, you can use casclient-lenient.jar instead.
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.cas.CASAuthenticationService"
          name="portal:service=Module,type=CASAuthenticationService"
          xmbean-dd=""
          xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean">
          <xmbean/>
          <depends>portal:service=Module,type=IdentityServiceController</depends>
          <attribute name="HavingRole"></attribute>
       </mbean>

   This will expose special service in JBoss Portal that can be leveraged by CAS AuthenticationHandler if the server is deployed on the same application server instance. This AuthenticationHandler will be enabled in next 2 steps.
6. Edit $JBOSS_HOME/server/default/deploy/cas.war/WEB-INF/deployerConfigContext.xml and add following line in the authenticationHandlers section:

       <bean class="org.jboss.portal.identity.sso.cas.CASAuthenticationHandler" />

   This can replace default SimpleTestUsernamePasswordAuthenticationHandler so whole part of this config file can look as follows:

                         <property name="authenticationHandlers">
         <list>
           <!--
            | This is the authentication handler that authenticates services by means of callback via SSL, thereby validating
            | a server side SSL certificate.
            +-->
           <bean
             class="org.jasig.cas.authentication.handler.support.HttpBasedServiceCredentialsAuthenticationHandler">
             <property
               name="httpClient"
               ref="httpClient" />
           </bean>

           <!--
            | This is the authentication handler declaration that every CAS deployer will need to change before deploying CAS
            | into production.  The default SimpleTestUsernamePasswordAuthenticationHandler authenticates UsernamePasswordCredentials
            | where the username equals the password.  You will need to replace this with an AuthenticationHandler that implements your
            | local authentication strategy.  You might accomplish this by coding a new such handler and declaring
            | edu.someschool.its.cas.MySpecialHandler here, or you might use one of the handlers provided in the adaptors modules.
            +-->
           <bean class="org.jboss.portal.identity.sso.cas.CASAuthenticationHandler" />
         </list>
       </property>

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 CAS Authentication Server's 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

## 20.4. JOSSO - Java Open Single SignOn

JBoss Portal enables seamless integration with JOSSO server. 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 tomcat valves, security realm and specific JOSSO configuration files). For JBoss setup please refer to JOSSO documentation

### 20.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 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:

       <partner-apps>

             ...

             <partner-app>
                 <context>/portal</context>
             </partner-app>

             ...

         </partner-apps>

   Complete config file can look as follows:

       <?xml version="1.0" encoding="ISO-8859-1" ?>
       <agent>
         <class>org.josso.jb4.agent.JBossCatalinaSSOAgent</class>
         <gatewayLoginUrl>http://localhost:8080/josso/signon/login.do</gatewayLoginUrl>
         <gatewayLogoutUrl>http://localhost:8080/josso/signon/logout.do</gatewayLogoutUrl>
         <service-locator>
           <class>org.josso.gateway.WebserviceGatewayServiceLocator</class>
           <endpoint>localhost:8080</endpoint>
         </service-locator>
         <partner-apps>
             <partner-app>
                 <context>/partnerapp</context>
             </partner-app>
             <partner-app>
                 <context>/portal</context>
             </partner-app>
         </partner-apps>
       </agent>

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. Edit $JBOSS_HOME/server/default/deploy/josso.ear/josso.war/WEB-INF/classes/josso-gateway-config.xml and configure following elements:
   - Credential Store:

         <!-- Basic Authentication Scheme -->
         <authentication-scheme>
             <name>basic-authentication</name>
             <class>org.josso.auth.scheme.BindUsernamePasswordAuthScheme</class>

             <!-- ================================================= -->
             <!-- JBoss Portal Credential Store                           -->
             <!-- ================================================= -->
            <credential-store>
                <class>org.jboss.portal.identity.sso.josso.JOSSOIdentityStore</class>
            </credential-store>

             <!-- ================================================= -->
             <!-- Credential Store Key adapter                      -->
             <!-- ================================================= -->
             <credential-store-key-adapter>
                 <class>org.josso.gateway.identity.service.store.SimpleIdentityStoreKeyAdapter</class>
             </credential-store-key-adapter>

         </authentication-scheme>

   - SSO Identity Store:

         <sso-identity-manager>

             <class>org.josso.gateway.identity.service.SSOIdentityManagerImpl</class>

             <!-- ================================================= -->
             <!-- JBoss Portal Credential Store                     -->
             <!-- ================================================= -->
             <sso-identity-store>
                <class>org.jboss.portal.identity.sso.josso.JOSSOIdentityStore</class>
             </sso-identity-store>

             <!-- ================================================= -->
             <!-- Identity Store Key adapter                        -->
             <!-- ================================================= -->
             <sso-identity-store-key-adapter>
                 <class>org.josso.gateway.identity.service.store.SimpleIdentityStoreKeyAdapter</class>
             </sso-identity-store-key-adapter>

         </sso-identity-manager>

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

Prev | Up | Next
Chapter 19. LDAP | Home | Chapter 21. CMS Portlet