The Curity Identity Server support Session Management and Logout, following the respective OpenId Connect specifications for Session Management and Logout. This section describes how Curity works with Session Management and Logout.
To enable Session Management and Logout, an OAuth Session Endpoint must be defined and mapped in a service role. Doing so will automatically expose all related properties in the server’s Metadata. This Curity endpoint exposes endpoints for both session management as well as logout.
Note that Curity also supports the registration of Session Management and Logout related attributes through Dynamic Client Registration, as described in OpenId Connect specifications for Session Management and Logout.
The primary purpose of Session Management is for a client to detect whether changes have occurred in the SSO session that the user maintains with Curity: if a user is no longer logged in, or if a user is re-authenticated with another authenticator, Session Management is able to report this and the client can initiate an action.
Being able to detect this, is based on the session_state, as defined in OpenId Connect. This value will be returned from the authorize endpoint whenever the client requested an ID token by including openid in the requested scopes.
session_state
openid
This session_state value must be sent, using a JavaScript postMessage command, to the iframe that is loaded from Curity’s Session Management endpoint (i.e. the check_session_endpoint in the Metadata). This iframe will postMessage the session’s changed status back to the client. To make this work, the Session Management endpoint’s response will be framable by framers from any origin. Details can be found in the Session Management specification.
check_session_endpoint
Note
Mobile clients using a custom schema redirect_uri will have to register an Allowed Origin and use the for_origin parameter to use this feature.
redirect_uri
for_origin
If the client is notified that the user’s session status has changed, the client could make an authentication request that includes the prompt=none parameter to the Curity Identity Server from an invisible iframe, which will result in a redirect back to the client’s redirect uri with either a fresh ID token (in case the user still has a valid SSO session with Curity) or an error (when the user is no longer logged in to Curity).
prompt=none
Important
upon receipt of the postMessage from Curity’s Session Management endpoint, the client must validate the origin of the message to ensure it is coming from Curity
Hint
The Session Management endpoint is located under the root of the mapped OAuth Session endpoint, e.g. if the OAuth Session Management endpoint is mapped to /oauth/session on a service role that is hosted on https://curity.example.com, then the Session Management endpoint is at https://curity.example.com/oauth/session.
/oauth/session
https://curity.example.com
https://curity.example.com/oauth/session
Please find the details in the Session Management specification
Whenever the client logs out the user and wants to notify Curity that the user should be logged out from Curity as well, the user must be redirected to the logout path, /logout, of the OAuth Session endpoint. In the logout request, the client can optionally include the ID token that it received from Curity before. Doing so indicates that Curity should terminate the SSO session that the user has for the client. This implies that potential alternative SSO sessions that the user has established with Curity as a result of other clients that requested authentication, will remain valid.
/logout
If the client that initiates the logout flow wants the user to be redirected back after logout at Curity, it can use the post_logout_redirect_uri parameter to indicate that location. The value of this redirect is validated against a configured whitelist of allowed values for the client. In case no ID token is included in the request to logout, the client must include a client_id parameter to inform Curity which client’s settings should be used to validate the post_logout_redirect_uri. However, including an ID token or a client_id in the logout request will limit the logout to only logout the session that the user has for the requesting client. In case a “global” logout is desired (i.e. logout all the actual user’s SSO sessions), the client must also include a parameter global with value true in the request to the logout path of the OAuth Session endpoint.
post_logout_redirect_uri
client_id
global
true
GET request parameters:
Curity supports both frontchannel as well as backchannel logout notifications to be delivered at clients upon logout. Every client that has requested authentication for a user that’s being logged out will receive this notification on its registered frontchannel_logout_uri and/or backchannel_logout_uri location. This includes notiftying the client that requested the user logout.
frontchannel_logout_uri
backchannel_logout_uri
The frontchannel_logout_uri will be called with the sid and sub values of the logged out user. These values are initially sent to the client as claims in the ID token that was issued to it. The frontchannel_logout_uri will be loaded in an iframe that is opened by Curity on the origin of the Curity Identity Server. For the frame to be loaded by the browser, the client must ensure that appropriate framability headers (i.e. X-Frame-Options and/or relevant Content Security Policy settings) are returned such that the browser will actually allow the the frame to be loaded from the client’s origin.
sid
sub
X-Frame-Options
The backchannel_logout_uri will be called by POST-ing a Logout Token to it. This Logout Token will be signed using the same cryptographic keys as the ID token, and it includes the sid and sub values of the logged out user as claims.
POST
When including an ID token in the logout request, SSO sessions that the user has with other clients will not be terminated. This could cause SSO to authenticate the user without interaction if the client that requested logout requests the user to log in again.
More details can be found in the OpenId Connect Backchannel Logout specification and the OpenId Connect Frontchannel logout specification.