PingAM

Session management

The OpenID Connect (OIDC) session management 1.0 draft series defines a mechanism for a relying party (RP) to:

  • Check with the OpenID provider (OP) if an OIDC session is still active based on an ID token.

  • Terminate an authenticated session with the OP. For example, when the user logs out.

The process is transparent to the end user. An RP uses a hidden <iframe> to get the session state from the OP and take action when the state changes.

AM supports Draft 10 of the specification.

AM offers two methods for OIDC session management, which use different endpoints to achieve the same result:

Using the authorize and sessions endpoints

This method uses the following endpoints for session management:

/oauth2/authorize

Retrieve session state.

/json/sessions

Terminate an authenticated session.

Session management flow

To check session state, create an <iframe> in your RP whose src attribute targets the /oauth2/authorize endpoint with the required parameters. The user-agent sends the tenant session cookie with the request.

session-management-10

For example, a public client RP called myClient uses the following <iframe src> URL to request session state:

https://am.example.com:8443/am/oauth2/realms/root/realms/alpha/authorize \
?client_id=myClient \
&response_type=none \
&id_token_hint=<id-token> \
&redirect_uri=https://www.example.com:443/callback \
&prompt=none

The query string parameters include these settings:

prompt=none

Don’t display user interaction pages to the end user.

id_token_hint=<id-token>

The ID token to validate against the authenticated session.

response_type=none

Don’t issue a token in the response.

The following table lists the responses:

AM responses Request with redirect_uri Request without redirect_uri

Valid session

Redirect to redirect_uri with no content.

Return HTTP 204 No Content.

Invalid session

Redirect to redirect_uri with no content and an error_description parameter appended to the URL. For example, https://www.example.com:443/callback?error_description=The%20request%20requires%20login.&error=login_required.

Return HTTP 400 Bad Request and redirect to a page that displays a message such as Login required. The request requires login.

The RP’s <iframe> and the redirect_uri page must process any errors. For example, by redirecting the end user to sign in.

Configure the provider and client

To enable this method for a realm, configure the OAuth 2.0 provider:

  1. In the AM admin UI, go to Realms > Realm Name > Services > OAuth2 Provider.

  2. Switch to the Advanced tab and add none|org.forgerock.oauth2.core.NoneResponseTypeHandler to the Response Type Plugins settings.

  3. Save your changes.

To enable this method in the RP client profile:

  1. In the AM admin UI, go to Realms > Realm Name > Applications > OAuth 2.0 > Clients > Client ID > Advanced.

  2. In Response Types, add none.

  3. Save your changes.

Using the checkSession and endSession endpoints

This method uses the following endpoints for session management:

/oauth2/connect/checkSession

Retrieve session state.

This endpoint serves as the check_session_iframe URL.

/oauth2/connect/endSession

Terminate an authenticated session and redirect to a post-logout page.

Configure the client

This method is enabled by default in the OAuth 2.0 provider. You only need to configure the client profile for the RP to use it:

  1. In the AM admin UI, go to Realms > Realm Name > Applications > OAuth 2.0 > Clients > Client ID > OpenID Connect.

  2. In Client Session URI, add the URL the RP uses as the <iframe src> URL.

  3. Save your changes.

Disable session management

To disable OIDC-based session management support for a realm, configure the OAuth 2.0 provider:

  1. In the AM admin UI, go to Realms > Realm Name > Services > OAuth2 Provider > Advanced OpenID Connect.

  2. Clear Enable Session Management.

  3. Save your changes.

This also disables backchannel logout.