17.4. Use Single Sign On (SSO) In A Web Application

Overview

Single Sign On (SSO) capabilities are provided by the web and Infinispan subsystems. Use this procedure to configure SSO in web applications.

Prerequisites

  • You need to have a configured security domain which handles authentication and authorization.
  • The infinispan subsystem needs to be present. It is present in the full-ha profile for a managed domain, or by using the standalone-full-ha.xml configuration in a standalone server.
  • The web cache-container and SSO cache-container must each be present. The initial configuration files already contain the web cache-container, and some of the configurations already contain the SSO cache-container as well. Use the following commands to check for and enable the SSO cache container. Note that these commands modify the ha profile of a managed domain. You can change the commands to use a different profile, or remove the /profile=ha portion of the command, for a standalone server.

    Example 17.1. Check for the web cache-container

    The profiles and configurations mentioned above include the web cache-container by default. Use the following command to verify its presence. If you use a different profile, substitute its name instead of ha. 
    /profile=ha/subsystem=infinispan/cache-container=web/:read-resource(recursive=false,proxies=false,include-runtime=false,include-defaults=true)
    If the result is success the subsystem is present. Otherwise, you need to add it.

    Example 17.2. Add the web cache-container

    Use the following three commands to enable the web cache-container to your configuration. Modify the name of the profile as appropriate, as well as the other parameters. The parameters here are the ones used in a default configuration. 
    /profile=ha/subsystem=infinispan/cache-container=web:add(aliases=["standard-session-cache"],default-cache="repl",module="org.jboss.as.clustering.web.infinispan")
    /profile=ha/subsystem=infinispan/cache-container=web/transport=TRANSPORT:add(lock-timeout=60000)
    /profile=ha/subsystem=infinispan/cache-container=web/replicated-cache=repl:add(mode="ASYNC",batching=true)

    Example 17.3. Check for the SSO cache-container

    Run the following Management CLI command: 
    /profile=ha/subsystem=infinispan/cache-container=web/:read-resource(recursive=true,proxies=false,include-runtime=false,include-defaults=true)
    Look for output like the following: "sso" => {
    If you do not find it, the SSO cache-container is not present in your configuration.

    Example 17.4. Add the SSO cache-container

    /profile=ha/subsystem=infinispan/cache-container=web/replicated-cache=sso:add(mode="SYNC", batching=true)
  • The web subsystem needs to be configured to use SSO. The following command enables SSO on the virtual server called default-host, and the cookie domain domain.com. The cache name is sso, and reauthentication is disabled. 
    /profile=ha/subsystem=web/virtual-server=default-host/sso=configuration:add(cache-container="web",cache-name="sso",reauthenticate="false",domain="domain.com")
  • Each application which will share the SSO information needs to be configured to use the same <security-domain> in its jboss-web.xml deployment descriptor and the same Realm in its web.xml configuration file.
Differences Between Clustered and Non-Clustered SSO Valves

Clustered SSO allows sharing of authentication between separate hosts, while non-clustered SSO does not. The clustered and non-clustered SSO valves are configured the same way, but the clustered SSO includes the cacheConfig, processExpiresInterval and maxEmptyLife parameters, which control the clustering replication of the persisted data.

Example 17.5. Example Clustered SSO Configuration

Because clustered and non-clustered SSO configurations are so similar, only a clustered configuration is shown. This example uses a security domain called tomcat. 
<jboss-web>
	<security-domain>tomcat</security-domain>
	<valve>
		<class-name>org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn</class-name>
		<param>
			<param-name>maxEmptyLife</param-name>
			<param-value>900</param-value>
		</param>
	</valve>
</jboss-web>

Table 17.1. SSO Configuration Options

Option Description
cookieDomain
The host domain to be used for SSO cookies. The default is /. To allow app1.xyz.com and app2.xyz.com to share SSO cookies, you could set the cookieDomain to xyz.com.
maxEmptyLife
Clustered SSO only. The maximum number of seconds an SSO valve with no active sessions will be usable by a request, before expiring. A positive value allows proper handling of shutdown of a node if it is the only one with active sessions attached to the valve. If maxEmptyLife is set to 0, the valve terminates at the same time as the local session copies, but backup copies of the sessions, from clustered applications, are available to other cluster nodes. Allowing the valve to live beyond the life of its managed sessions gives the user time to make another request which can then fail over to a different node, where it activates the backup copy of the session. Defaults to 1800 seconds (30 minutes).
processExpiresInterval
Clustered SSO only. The minimum number of seconds between efforts by the valve to find and invalidate SSO instances which have expired the MaxEmptyLife timeout. Defaults to 60 (1 minute).
requiresReauthentication
If true, each request uses cached credentials to reauthenticate to the security realm. If false (the default), a valid SSO cookie is sufficient for the valve to authenticate each new request.
Invalidate a Session

An application can programmatically invalidate a session by invoking method javax.servlet.http.HttpSession.invalidate().

Report a bug