Access Management 7.2.2

Session management

The OpenID Connect Session Management 1.0 draft series defines a mechanism for relying parties to:

  • Request the providers to confirm whether a specific OpenID Connect session is still valid 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 and, therefore, let 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 that this also disables backchannel logout.

AM supports Draft 05 and Draft 10 of the specification. The drafts use different endpoints to achieve the same end result.

Session management draft 10

Session management draft 10 does not specify or mandate any session-related endpoint. AM’s implementation of draft 10 is therefore as follows:

  • /oauth2/authorization. Retrieves session state for requests.

  • /json/sessions. (AM-specific). Logs out end users.

    For more information, see Log out of AM over REST.

The easiest 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.

You must also include any other parameter 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 iplanetDirectoryPro cookie. Therefore, the flow would resemble the following:

Session management flow
Figure 1. Session management flow

The following is an example of a public client requesting session state:

https://openam.example.com:8443/openam/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. Specifies that the request is a repeated authentication request for a specific end user. AM will not display any user interaction pages to the end user.

  • id_token_hint=your-id-token. Specifies the ID token associated with an end user. AM validates the ID token against the user’s session.

  • response_type=none. Specifies that AM should not issue any token as response.

The URL is split for readability purposes.

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. For example:

https://www.example.com:443/callback?error_description=The%20request%20requires%20login.&error=login_required

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, such as 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.

Enable session management draft 10

To let clients use session management draft 10 with AM, follow these steps:

  1. Configure the provider:

    • Go to Realms > Realm Name > Services > OAuth2 Provider.

    • On the Advanced tab, add the none|org.forgerock.oauth2.core.NoneResponseTypeHandler plugin 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.

  2. Configure the clients:

    • Go to Realms > Realm Name > Applications > OAuth 2.0 > Clients > Client Name > OpenID Connect > Advanced.

    • In the Response Types field, add the none type.

    • Save your changes.

Session management draft 05

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 lets clients retrieve session state. This endpoint serves the check_session_iframe URL that allows the relying party to interact with the endpoint.

    When checking session state with the checkSession 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 lets clients terminate end user sessions and redirect end users to a particular page after logout.

For more information about the endpoints, see OpenID Connect 1.0 endpoints.

Copyright © 2010-2024 ForgeRock, all rights reserved.