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.

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

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

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:

In the AM admin UI, go to Realms > Realm Name > Services > OAuth2 Provider.
Switch to the Advanced tab and add none|org.forgerock.oauth2.core.NoneResponseTypeHandler to the Response Type Plugins settings.
Save your changes.

To enable draft 10 support in the RP client profile:

In the AM admin UI, go to Realms > Realm Name > Applications > OAuth 2.0 > Clients > Client ID > Advanced.
In Response Types, add none.
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:

In the AM admin UI, go to Realms > Realm Name > Applications > OAuth 2.0 > Clients > Client ID > OpenID Connect.
In Client Session URI, add the URL the RP uses as the <iframe src> URL.
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:

In the AM admin UI, go to Realms > Realm Name > Services > OAuth2 Provider > Advanced OpenID Connect.
Clear Enable Session Management.
Save your changes.

This also disables backchannel logout.

Access Management 7.4.1