The OpenID Connect Session Management 1.0 draft series defines a mechanism for relying parties to:
Request the providers to confirm if a specific OpenID Connect session is still valid or not when presented with an ID token.
Request session termination for a user in the provider. For example, if the user decides to log out.
To keep the process transparent to the end user, relying parties use hidden iframes to request session status from the providers and take actions based on it.
To link ID tokens to sessions, letting relying parties query AM for session status, AM creates a token in the CTS store with the link information. This also ensures that any AM instance can retrieve session information for a particular token.
Session management is enabled by default. To disable it, go to Realms > Realm Name > Services > OAuth2 Provider > Advanced OpenID Connect, and disable OIDC Session Management.
Note this disables backchannel logout as well.
Draft 10 does not specify or mandate any session-related endpoint; therefore, AM’s implementation of Draft 10 is as follows:
/oauth2/authorization. Retrieves session state for requests.
/json/sessions. (AM-specific). Logs out end users.
For more information, refer to Log out of AM using REST.
The simplest way to check session state using the authorization endpoint is
to create an iframe whose
src attribute is AM’s
/oauth2/authorize endpoint with the required parameters.
Include any other parameters required in your environment, such as client authentication methods.
For AM to validate an end-user session against an ID token, the user-agent must provide the SSO token of the end-user’s session as the tenant session cookie; therefore, the flow would resemble the following:
The following is an example of a public client requesting session state:
https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha/authorize \ ?client_id=myClient \ &response_type=none \ &id_token_hint=eyJ0eXAiOiJKV1QiLCJra…7r8soMCk8A7QdQpg \ &redirect_uri=https://www.example.com:443/callback \ &prompt=none
prompt=none. The request is a repeated authentication request for a specific end user. AM does not display user interaction pages to the end user.
id_token_hint=your-id-token. The ID token associated with an end user. AM validates the ID token against the user’s session.
response_type=none. AM should not issue a token as response.
The URL is split for readability purposes, and the end user’s SSO token must be set in a cookie in order to validate the session.
If the session is valid, and the request contains a redirection URI, AM redirects to the specified URI with no content. If the request does not contain a redirection URI, AM returns an HTTP 204 no content message.
If the session is invalid, and the request contains a redirection URI,
AM redirects to the specified URI with no content, and appends an
error_description parameter to the URL.
If the request does not contain a redirection URI,
AM returns an HTTP 400 error message and redirects to an AM admin UI page showing a message,
login required. The request requires login.
The relying party’s iframe, or the redirection page, should be able to retrieve the error messages and act in consequence. For example, redirecting the end user to a login page.
To let clients use Session Management Draft 10 with AM, follow these steps:
Configure the provider:
In the AM admin UI, go to Realms > Realm Name > Services > OAuth2 Provider.
On the Advanced tab, add the
none|org.forgerock.oauth2.core.NoneResponseTypeHandlerplugin in the Response Type Plugins field, if it is not already present.
Save your changes.
On the Advanced OpenID Connect tab, select Enable Session Management, if it is not already enabled.
Save your changes.
Configure the clients:
Go to Realms > Realm Name > Applications > OAuth 2.0 > Clients > Client ID > Advanced.
In the Response Types field, add the
Save your changes.
Draft 05 of the Session Management specification defined two endpoints for managing OpenID sessions. These endpoints have been removed from version 10 of the draft, but AM still supports them:
/oauth2/connect/checkSession. It lets clients retrieve session state. This endpoint serves the
check_session_iframeURL that allows the relying party to interact with the endpoint.
When checking session state with the check session endpoint, you must configure the Client Session URI field in the client profile as the iframe URL in the relying party.
For an alternative method of checking session state compliant with version 10 of the session management draft, see Session Management Draft 10.
/oauth2/connect/endSession. It lets clients terminate end user sessions and redirect end users to a particular page after logout.
For more information about the endpoints, refer to OpenID Connect 1.0 endpoints.