# OpenAM Administration Guide
Chapter 10. Configuring Cross-Domain Single Sign On

Sidebar | Prev | Next

# Chapter 10. Configuring Cross-Domain Single Sign On

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.

[D]

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.

[D]

This chapter includes the following procedures.

- Procedure 10.1, “To Enable CDSSO For a Java EE Policy Agent”

- Procedure 10.2, “To Enable CDSSO For a Web Policy Agent”

- Procedure 10.3, “To Indicate Progress During CDSSO Login”

- Procedure 10.4, “To Protect Against CDSSO Cookie Hijacking”

- Procedure 10.5, “Using SAML 2.0 With Policy Agents”

Procedure 10.1. To Enable CDSSO For a Java EE Policy Agent

1. In the OpenAM console, browse to Access Control > `Realm Name` > Agents > J2EE > `Agent Name` > SSO.

2. Scroll down and enable Cross Domain SSO.

3. 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`.

4. 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`.

5. 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.

6. 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.

7. 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).

8. Add the domains involved in CDSSO in the CDSSO Domain List.

9. 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.

10. Save your work.

Procedure 10.2. To Enable CDSSO For a Web Policy Agent

1. In the OpenAM console, browse to Access Control > `Realm Name` > Agents > Web > `Agent Name` > SSO.

2. Enable Cross Domain SSO.

3. 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`.

4. Add the domains involved in CDSSO in the Cookies Domain List.

5. 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.

6. Save your work.

Procedure 10.3. To Indicate Progress During CDSSO Login

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.

1. Edit a copy of the file `config/federation/default/cdclogin.jsp` to 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.

2. Unpack , and replace the file with your modified version.

   Also include any images you reference in the page.

3. Pack up your custom version of OpenAM, and then deploy it in your web container.

Procedure 10.4. To Protect Against CDSSO Cookie Hijacking

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.

1. In the OpenAM console, browse to Configuration > System > Platform.

2. Remove the domain such as `.example.com` from the Cookies Domains list, and replace it with the server host name such as `openam.example.com`, or if OpenAM is behind a load balancer with the load balancer host name, such as `load-balancer.example.com`.

3. Save your work.

4. In the OpenAM console, browse to Configuration > Servers and Sites > Default Server Settings > Advanced, and then make the necessary changes.

   1. Change the setting for the property `com.sun.identity.enableUniqueSSOTokenCookie` to `true`, from the default `false`.

   2. Make sure that the property `com.sun.identity.authentication.uniqueCookieName` is set to the name of the cookie that will hold the URL to the OpenAM server that authenticated the user.

      The default name is `sunIdentityServerAuthNServer`.

   Save your work.

5. Browse to Configuration > Servers and Sites > `Server Name` > Advanced, and add the property `com.sun.identity.authentication.uniqueCookieDomain`, setting the value to the fully-qualified domain name of the current OpenAM server, such as `openam.example.com`.

   Then Save your work.

6. For each Java EE policy agent, browse in the OpenAM console to Access Control > `Realm Name` > Agents > J2EE > `Agent Name` > Advanced > Custom Properties, and add `com.sun.identity.enableUniqueSSOTokenCookie=true` to the list.

7. Save your work.

8. Restart OpenAM or the container in which it runs for the configuration changes to take effect.

Procedure 10.5. Using SAML 2.0 With Policy Agents

The federation mechanism associated with SAML can be used as an alternative to CDSSO for both Web and Java EE policy agents. This assumes OpenAM is configured as an IDP on one domain, and the desired policy agent protects resources on behalf of a second instance of OpenAM, where that instance acts as an SP on a second domain.

While using SAML 2.0 adds complexity, it supports attribute mapping, which may be useful when the two domains are associated with datastores with different attributes.

1. Install a policy agent. The basic process for installing policy agents is available in the OpenAM Web Policy Agent Installation Guide and the OpenAM Java EE Policy Agent Installation Guide.

2. Now you can replace the given OpenAM Login URL and OpenAM Logout URLs with SAML2 URLs configured in the section on Managing SAML 2.0 Federation .

3. - If you have configured the Web policy agents to store their properties centralized on an OpenAM server, navigate to the URL for the OpenAM console. Select Access Control > `Realm Name` > Agents > Web > `Agent Name` > OpenAM Services.

     For the Web Agent, under the OpenAM Services tab, in the Agent Logout URL section, set up a list of application logout URLs. In the Logout Redirect URL text box, enter an appropriate URL to redirect the user after logout.

   - Alternatively, if the Web policy agents are set up to store properties on local systems, find the `OpenSSOAgentConfiguration.properties` file in the `/path/to/agent/config/` directory. You can specify OpenAM Login and Logout URLs with the `com.sun.identity.agents.config.login.url` and `com.sun.identity.agents.config.logout.url` attributes, respectively.