Single sign-on
Single sign-on (SSO) lets users who have authenticated to Advanced 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 PingOne Advanced Identity Cloud’s federation capabilities, such as OAuth 2.0 or SAML 2.0.
-
Web agents and Java agents both support CDSSO.
PingOne Advanced Identity Cloud also supports CDSSO with PingGateway version 6 or later. For details, refer to Single sign-on and cross-domain single sign-on in the PingGateway 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:
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, PingOne Advanced 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, PingOne Advanced 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 asDomain=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, includingopenam/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 |
Implement CDSSO
Cross-domain single sign-on (CDSSO) provides SSO capabilities for PingOne Advanced 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.abbr} also supports CDSSO with PingOne Advanced Identity Cloud. For details, refer to the PingGateway 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.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 onapp.example.net
does not receive the corresponding session token. In this case, the solution is to configure the SSO token onexample.net
. -
When the
Cookie Security
or theCDSSO Secure Enable
properties are configured in the agent profile with a regular HTTP application.If you need encrypted communications for an application protected by PingOne Advanced Identity Cloud, use the
Cookie Security
or theCDSSO 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
andnet
as well as functional equivalents, such asco.uk
andco.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.