Single Sign-On
Single sign-on (SSO) lets users who have authenticated to AM access multiple independent services from a single login session by storing user sessions as HTTP cookies[2].
Cross-domain single sign-on (CDSSO) is an AM-specific capability that provides SSO inside the same organization within a single domain or across domains. For example, CDSSO allows your AM servers in the DNS domain .internal.net to provide authentication and authorization to web and Java agents from the .internal.net domain and other DNS domains, such as .example.net.
Since 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 AM's federation capabilities, such as OAuth 2.0 or SAML v2.0.
Web Agents and Java Agents both support CDSSO.
AM also supports CDSSO with IG version 6 or later. For more information, see Single Sign-On and Cross-Domain Single Sign-On in the ForgeRock Identity Gateway Gateway Guide.
CDSSO supports CTS-based and client-based sessions. For more information about session state impact on CDSSO, see Impact of Storage Location for Sessions.
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:
About 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. For AM, logging in to a new realm means logging out of the current realm.
When a user interactively changes realms through the AM console, AM 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, AM first logs the user out of the current realm, and then prompts the user to log in to the new realm.
About 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
Normally set to the full URL that was used to access the configurator. To work with multiple subdomains, the
Domainshould be set to a URL likeDomain=server.example.net. This is also known as the cookie domain.- Path
The directory in the URL to which the cookie applies. If the
Path=/openam, the cookie applies to the/openamsubdirectory of the URL, and lower level directories, includingopenam/XUI.- Secure
If the
Securename is included, the cookie can be transferred only over HTTPS. When a request is made over HTTP, the cookie is not made available to the application.For more information, see "Configuring Secure Session Cookies".
- HttpOnly
When the
HttpOnlyflag is included, that cookie will not be accessible through JavaScript. According to RFC 6265, the noted flag "instructs the user agent to omit the cookie when providing access to cookies via 'non-HTTP' APIs (for example, a web browser API that exposes cookies to scripts)."For more information, see "Configuring HttpOnly Session Cookies".
- Expires
The lifetime of a cookie can be limited, with an
Expiresname configured with a time, based on UTC (GMT).
Warning
Do not take a shortcut with a top-level domain. Web browser clients today are designed to ignore cookies set to top-level domains including com, net, and co.uk. In addition, a cookie with a value like Domain= app1.example.net will not work for similar subdomains, such as app2.example.net.
Implementing CDSSO
CDSSO provides SSO capabilities for AM servers and web or Java agents within a single domain or across domains in the same organization.
CDSSO is the only mode of operation of Web Agents and Java Agents and, therefore, no additional configuration is required to make it work. You must, however, protect the session cookie against hijacking. For more information, see "Enabling Restricted Tokens for CDSSO Session Cookies".
Tip
IG also supports CDSSO with AM. For more information, see 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 theexample.netdomain.When a third-level domain is used for the SSO token.
If an SSO token is configured on
sso.example.net, an application onapp.example.netdoes not receive the corresponding session token. In this case, the solution is to configure the SSO token onexample.net.When the
Cookie Securityor theCDSSO Secure Enableproperties are configured in the agent profile with a regular HTTP application.If you need encrypted communications for an application protected by AM, use the
Cookie Securityor theCDSSO Secure Enableproperties 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
/helloworldpath; that will not match an application that might be configured with a/hellomarspath. 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
comandnetas well as functional equivalents, such asco.ukandco.jp.When working with different browsers
The
name=valuepairs 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.When a client-based session cookie exceeds the maximum size permitted by the browser
As described in Session Cookies and Session Security, the default size of the
iPlanetDirectoryProcookie is approximately 2,000 bytes. When you customize AM sessions by adding attributes, the cookie size grows. Browsers allow cookie sizes between 4,000 and 5,200 bytes, depending on the browser. AM single sign-on does not support a cookie size that exceeds the maximum cookie size allowed by the browser.