PingAM 7.5.0

Session management

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

  • Get an OpenID provider (OP) to confirm whether an OIDC session is valid based on an ID token.

  • Terminate an end user session with the OP; for example, when the user signs 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 these drafts of the specification:

Each version uses different endpoints to achieve the same result.

Session management draft 10

Draft 10 does not specify any session-related endpoints. AM’s implementation of Draft 10 depends on these endpoints:

/oauth2/authorize

Retrieve session state.

/json/sessions

Terminate an end user session.

Draft 10 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://openam.example.com:8443/openam/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

Do not display user interaction pages to the end user.

id_token_hint=<id-token>

The ID token to validate against the end user’s session.

response_type=none

Do not 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.

Enable draft 10 support

To enable draft 10 support 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 draft 10 support 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.

Session management draft 05

Draft 05 defines two endpoints for session management. These endpoints are no longer present in draft 10:

/oauth2/connect/checkSession

Retrieve session state.

/oauth2/connect/endSession

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

Enable draft 05 support

The /oauth2/connect/checkSession endpoint serves as the check_session_iframe URL.

To enable draft 05 support in the RP client profile:

  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

By default, the AM OP supports draft 05 without additional configuration.

To disable 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.