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
andsessions
endpointsThis method of session management is based on Draft 10 of the OIDC Session Management specification.
-
Using the
checkSession
andendSession
endpointsThis method is based on earlier drafts of the specification.
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.
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 |
Return HTTP 204 No Content. |
Invalid session |
Redirect to |
Return HTTP 400 Bad Request and redirect to a page that displays a message such as
|
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:
-
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 this method 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.
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:
-
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
To disable OIDC-based 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.