Identity Cloud

Single sign-on

Single sign-on (SSO) lets users who have authenticated to Identity Cloud access multiple independent services from a single login session by storing user sessions as HTTP cookies.

Cross-domain single sign-on (CDSSO) provides SSO inside the same organization within a single domain or across domains. For example, CDSSO lets servers in the DNS domain .internal.net provide authentication and authorization to web and Java agents from the .internal.net domain and other DNS domains, such as .example.net.

Because CDSSO removes the constraint of configuring SSO depending on the DNS domain, it simplifies the deployment of SSO in your environment.

When implementing CDSSO, take into account the following points:

  • For SSO across multiple organizations or when integrating with other access management software, use Identity Cloud’s federation capabilities, such as OAuth 2.0 or SAML 2.0.

  • Web agents and Java agents both support CDSSO.

    Identity Cloud also supports CDSSO with IG version 6 or later. For details, refer to Single sign-on and cross-domain single sign-on in the IG documentation.

Web agents and Java agents wrap the SSO session token inside an OpenID Connect (OIDC) JSON Web Token (JWT). During the CDSSO flow, the agents create cookies for the different domains specified in the agent profile, and the oauth2/authorize endpoint authorizes the different cookie domains as required.

The following diagram illustrates the CDSSO flow for web agents and Java agents:

Web and Java agents CDSSO flow
Figure 1. Web and Java agents CDSSO flow

Realms and SSO

When changing authentication realms, a subject leaves the current SSO realm. The new SSO realm might apply to different applications, and use a different authentication process. Logging in to a new realm means logging out of the current realm.

When a user interactively changes realms, Identity Cloud offers the option of logging out of the current realm to log in to the new realm, or choosing to remain logged in to the current realm.

The result depends on the user’s choice:

  • If the user cancels the change at this point, the user remains logged in to the current realm and is not logged in to the new realm.

  • If the user chooses to log in to the new realm, Identity Cloud first logs the user out of the current realm then prompts the user to log in to the new realm.

HTTP cookies

To understand how SSO works, you need to understand some key elements of the HTTP cookie, as described in RFC 6525, HTTP State Management Mechanism.

Within an HTTP cookie, you can store a single custom name=value pair, such as sessionid=value. Other properties within a cookie are as follows:

Domain

Also known as the cookie domain, this is the domain with which the cookie is associated. The default value is the current domain. To work with multiple subdomains, set the Domain to a URL such as Domain=server.example.net.

Path

The directory in the URL to which the cookie applies. If Path=/openam, the cookie applies to the /openam subdirectory of the URL, and lower level directories, including openam/XUI.

Expires

You can limit the lifetime of a cookie with an Expires property set to a time based on UTC (GMT).

Do not take a shortcut with a top-level domain. Web browser clients are designed to ignore cookies set to top-level domains including com, net, and co.uk. In addition, a cookie with a value such as Domain=app1.example.net will not work for similar subdomains, such as `app2.example.net.

Implement CDSSO

Cross-domain single sign-on (CDSSO) provides SSO capabilities for Identity Cloud and web or Java agents within a single domain or across domains in the same organization.

CDSSO is the only mode of operation for web and Java agents, so no additional configuration is required to make it work.

IG also supports CDSSO with Identity Cloud. For details, refer to the ForgeRock Identity Gateway Gateway Guide.

Troubleshooting SSO

In general, problems with single sign-on relate to some sort of mismatch of domain names. For example, a cookie that is configured on a third-level domain, such as sso.example.net, will not work with an application on a similar domain, such as app.example.net. The following list describes scenarios that may lead to similar problems:

  • When a cookie domain does not match a domain for the protected application.

    Assume the application is configured on a domain named example.org. That application will not receive an SSO token configured on the example.net domain.

  • When a third-level domain is used for the SSO token.

    If an SSO token is configured on sso.example.net, an application on app.example.net does not receive the corresponding session token. In this case, the solution is to configure the SSO token on example.net.

  • When the Cookie Security or the CDSSO Secure Enable properties are configured in the agent profile with a regular HTTP application.

    If you need encrypted communications for an application protected by Identity Cloud, use the Cookie Security or the CDSSO Secure Enable properties and make sure the application is accessible over HTTPS.

  • When the path listed in the cookie does not match the path for the application.

    Perhaps the cookie is configured with a /helloworld path; that will not match an application that might be configured with a /hellomars path. In that case, the application will not receive the cookie.

  • When an inappropriate name is used for the cookie domain.

    As noted earlier, client browsers are configured to ignore first-level domains, such as com and net as well as functional equivalents, such as co.uk and co.jp.

  • When working with different browsers.

    The name=value pairs described earlier may not apply to all browsers. The requirements for an HTTP cookie sent to an IE browser may differ from the requirements for other standard browsers, such as Firefox and Chrome. Based on anecdotal reports, IE does not recognize domain names that start with a number. In addition, IE reportedly refuses cookies that include the underscore (_) character in the FQDN.

Copyright © 2010-2024 ForgeRock, all rights reserved.