Chapter 10. Configuring Cross-Domain Single Sign On

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.

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.

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.

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.

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.