Managing OpenID Connect User Sessions

Logging in to the OpenID provider and obtaining tokens are well-stabilised processes in the OpenID spec. However, keeping the client relying party informed of the session's validity is not as straightforward. The end user's session in AM is unavailable to the relying party, and therefore the only information the client has is the expiration time of the ID token, which may be undesirable.

OpenID Connect Session Management 1.0 - draft -10 defines a mechanism for relying parties to:

  • Request AM to confirm if a specific OpenID Connect session is still valid or not.

  • Terminate end user sessions in AM.

When Session Management is enabled, AM links ID tokens to sessions. This ensures relying parties can track end users' sessions and request that end users log again if their sessions have expired.

To keep the process transparent to the end user, relying parties use hidden iframes to pass messages between AM and themselves. By embedding iframes in the relying party, they can periodically request session status from AM.

Session Management is enabled by default, and sessions are always stored in the CTS token store. To disable Session Management, go to Realms > Realm Name > Services > OAuth2 Provider > Advanced OpenID Connect, and disable the Store Ops Tokens switch.

Draft 05 of the of the Session Management spec 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 "Retrieving Session State without the Check Session Endpoint".

  • /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.

Retrieving Session State without the Check Session Endpoint

You can retrieve session state by sending a request to the authorization endpoint that contains the following parameters:

  • 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.

    To use this response type, ensure that the none response type plugin is configured in the OAuth 2.0 provider. See Authorization Server Configuration.

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:

  • The relying party obtains an ID token related to an end user. This may have happened at any point in time. For example, when the end user registered with the relying party to use its services.

  • The end user requests additional services from the relying party.

  • The relying party, still holding the end user's ID token, requests that AM checks if the user has a valid session.

  • AM returns session state.

  • The relying party makes a decision based on AM's response; either provide the services, or request the end user to log in again.

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

https://openam.example.com:8443/openam/oauth2/realms/root/authorize \
?client_id=myClient \
&response_type=none \
&id_token_hint=eyJ0eXAiOiJKV1QiLCJra...7r8soMCk8A7QdQpg \
&redirect_uri=https://www.example.com:443/callback \
&prompt=none

Note that 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. 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.

Your 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.

Tip

To retrieve session state using this mechanism, the OAuth 2.0/OpenID provider must be configured for Session Management and the client relying party must have the none value configured as a valid response type.


Read a different version of :