Checking the State of a Session, and Invalidating Sessions

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 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 will disable backchannel logout as well.

AM supports Draft 05 and Draft 10 of the specification. They use different endpoints and to achieve the same end result, as you will see next.

Session Management Draft 10

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, see "Logging out of AM Using REST".

The simplest strategy 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. Note that 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
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 to 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.

Note that the URL is split for readability purposes and that 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 console 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.

Enabling Session Management Draft 10

To let clients use session management draft 10 with AM, perform the following steps:

  1. Configure the provider:

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

    2. On the Core tab, add the none|org.forgerock.oauth2.core.NoneResponseTypeHandler plugin in the Response Type Plugins field, if it is not already present.

    3. Save your changes.

    4. On the Advanced OpenID Connect tab, enable OIDC Session Management, if it is not already enabled.

    5. Save your changes.

  2. Configure the clients:

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

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

    3. Save your changes.

Session Management Draft 05

Draft 05 of the 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_iframe URL 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, see OpenID Connect 1.0 Endpoints.

Read a different version of :