This chapter shows you how to configure cross-domain single sign on (CDSSO). When you have multiple domains in a single organization, CDSSO lets your OpenAM servers in one domain work with policy agents from other domains.
CDSSO is an OpenAM-specific capability. For single sign on across multiple organizations or when integrating with other access management software, use OpenAM's federation capabilities.
Cross-domain single sign on provides a safe mechanism for managing access across multiple different domains that you control. CDSSO lets OpenAM authenticate users redirected by policy agents in other DNS domains.
Single sign on depends on cookies to store session information. Yet for for security reasons, browsers do not let a web site in one domain to get access to a cookie from another domain. With CDSSO, the policy agents work around this by negotiating with OpenAM to allow access.
The Java EE policy agent allows CDSSO by using a mechanism to write the SSO token from OpenAM authentication to a cookie with the domain the host where the agent runs. The following sequence diagram illustrates this mechanism.
Whereas the Java EE policy agent has an endpoint specifically to handle the cookie domain translation, the web policy agent handles the request directly as shown in the following sequence diagram.
In the OpenAM console, browse to Access Control >
Realm Name> Agents > J2EE >Agent Name> SSO.Select Enable Cross Domain SSO.
Check that the CDSSO Redirect URI is set.
Depending on where you deployed your Java EE agent application, the default is something like
/agentapp/sunwCDSSORedirectURI.Set the list of URLs for CDSSO Servlet URL to the Cross Domain Controller Servlet URLs of the servers the agent accesses, such as
http://openam.example.com:8080/openam/cdcservlet.If the agent accesses OpenAM through a load balancer, use the load balancer URLs, such as
http://load-balancer.example.com:8080/openam/cdcservlet.Leave the CDSSO Clock Skew set to 0.
Make sure instead that the clocks on the servers where you run OpenAM and policy agents are synchronized.
Set the list of URLs for CDSSO Trusted ID Provider to the Cross Domain Controller Servlet URLs of the OpenAM servers the agent accesses, such
http://openam.example.com:8080/openam/cdcservlet.This list should include one CDC Servlet URL for every OpenAM server the agent might access. You do not need to include site or load balancer URLs.
To protect the SSO token from network snooping, you can select CDSSO Secure Enable to mark the SSO token cookie as secure.
If you select this, then the SSO token cookie can only be sent over a secure connection (HTTPS).
Add the domains involved in CDSSO in the CDSSO Domain List.
If necessary, update the Agent Root URL for CDSSO list on the Global tab page.
If the policy agent is on a server with virtual host names, add the virtual host URLs to the list.
If the policy agent is behind a load balancer, add the load balancer URL to the list.
Save your work.
In the OpenAM console, browse to Access Control >
Realm Name> Agents > Web >Agent Name> SSO.Select Enable Cross Domain SSO.
Set the list of URLs for CDSSO Servlet URL to the Cross Domain Controller Servlet URLs of the servers the agent accesses, such as
http://openam.example.com:8080/openam/cdcservlet.If the agent accesses OpenAM through a load balancer, use the load balancer URLs, such as
http://load-balancer.example.com:8080/openam/cdcservlet.Add the domains involved in CDSSO in the Cookies Domain List.
If necessary, update the Agent Root URL for CDSSO list on the Global tab page.
If the policy agent is on a server with virtual host names, add the virtual host URLs to the list.
If the policy agent is behind a load balancer, add the load balancer URL to the list.
Save your work.
The default self-submitting form page that OpenAM presents to users contains hidden fields, but is otherwise blank. If you want to show users that the operation is in progress, then customize the necessary JSP.
Edit a copy of the file
config/federation/default/cdclogin.jspto add a clue that SSO is in progress, such as an image.You can find this file where you deployed OpenAM, such as
/path/to/tomcat/webapps/openam/config/federation/default/cdclogin.jsp.When you add an image or other presentation element, make sure that you retain the form and JavaScript as is.
Unpack openam-server-10.2.0-SNAPSHOT.war, and replace the file with your modified version.
Also include any images you reference in the page.
Pack up your custom version of OpenAM, and then deploy it in your web container.
When cookies are set for an entire domain such as
.example.com, an attacker who steals a cookie can use it
from any host in the domain such as untrusted.example.com.
Cookie hijacking protection restricts cookies to the fully-qualified domain
name (FQDN) of the host where they are issued, such as
openam-server.example.com and
server-with-agent.example.com, using CDSSO to handle
authentication and authorization.
For CDSSO with cookie hijacking protection, when a client successfully authenticates OpenAM issues the master SSO token cookie for its FQDN. OpenAM issues restricted token cookies for the other FQDNs where the policy agents reside. The client ends up with cookies having different session identifiers for different FQDNs, and the OpenAM server stores the correlation between the master SSO token and restricted tokens, such that the client only has one master session internally in OpenAM.
To protect against cookie hijacking you restrict the OpenAM server domain to the server where OpenAM runs. This sets the domain of the SSO token cookie to the host running the OpenAM server that issued the token. You also enable use of a unique SSO token cookie. For your Java EE policy agents, you enable use of the unique SSO token cookie in the agent configuration as well.
In the OpenAM console, browse to Configuration > System > Platform.
Remove the domain such as
.example.comfrom the Cookies Domains list, and replace it with the server host name such asopenam.example.com, or if OpenAM is behind a load balancer with the load balancer host name, such asload-balancer.example.com.Save your work.
In the OpenAM console, browse to Configuration > Servers and Sites >
Server Name> Default Server Settings, and then make these changes:Set the property
com.sun.identity.enableUniqueSSOTokenCookietotrue.Add the property
com.sun.identity.authentication.uniqueCookieDomain, setting the value to the fully-qualified domain name of the OpenAM server, such asopenam.example.com.
Save your work.
For each Java EE policy agent, browse in the OpenAM console to Access Control >
Realm Name> Agents > J2EE >Agent Name> Advanced > Custom Properties, and addcom.sun.identity.enableUniqueSSOTokenCookie=trueto the list.Save your work.