OpenID Connect logout
Ory OAuth2 and OpenID Connect allows you to implement:
- OpenID Connect RP-Initiated Logout 1.0,
- OpenID Connect Front-Channel Logout 1.0
- OpenID Connect Back-Channel Logout 1.0
This document shows how to perform OpenID Connect front-channel and back-channel logout using Ory OAuth2 and OpenID Connect.
OpenID Connect Front-Channel Logout 1.0
OpenID Connect Front-Channel Logout 1.0 allows an OAuth2 client to register a
frontchannel_logout_uri field. If
frontchannel_logout_uri is set to a valid URL, Ory redirects the user-agent (typically browser) to that URL after a logout
occurred. This allows the OAuth2 client application to log out the end user in its own system as well, for example by deleting a
cookie or invalidating the user session.
Ory OAuth2 and OpenID Connect always appends query parameters values
sid to the Front-Channel Logout URI. Each OpenID
Connect ID token is issued with a
sid claim that will match the
sid value from the Front-Channel Logout URI. Ory OAuth2 and
OpenID Connect automatically executes the required HTTP redirects to make this work.
To use OpenID Connect Front-Channel Logout 1.0 with Ory OAuth2 and OpenID Connect, follow these steps:
- Register a
frontchannel_logout_urifield with a valid URL in your OAuth2 client application.
- When a logout occurs, Ory redirects the user-agent (browser) to the specified URL.
- The OAuth2 client application can then log out the end user in its own system as well, for example by deleting a cookie or invalidating the user session.
OpenID Connect Back-Channel Logout 1.0
OpenID Connect Back-Channel Logout 1.0 is a feature that allows an OAuth2 client to register
backchannel_logout_session_required fields. If
backchannel_logout_uri is set to a valid URL, a HTTP POST request with
Content-Type application/x-www-form-urlencoded and a
logout_tokenis sent to the set URL when the end user logs out. The
logout_token is a JWT signed with the same key that's used to sign OpenID Connect ID tokens. You should thus validate the
logout_token using the ID token public key (get it from
logout_token contains the following
iss: Issuer identifier for the issuer of the response. The
issvalue is a case-sensitive URL that uses the HTTPS scheme. URL contains scheme, host, and optionally port number and path components. No query or fragment components allowed.
aud: Audience(s) that this ID token is intended for. It contains the OAuth 2.0
client_idof the as an audience value.
iat: Time at which the JWT was issued. Can be used to determine the age of the JWT.
jti: A unique identifier for the JWT. Can be used to prevent the JWT from being replayed. This is helpful for a one time use token.
events: Claim whose value is a JSON object containing the member name http://schemas.openid.net/event/backchannel-logout. This declares that the JWT is a Logout Token. The corresponding member value MUST be a JSON object and SHOULD be the empty JSON object
sid: Session ID - A session ID that is used to associate a particular session with an ID Token. The value is passed as a parameter to the logout endpoint when logging out of the OP.
logout_token is validated, the endpoint returns a HTTP 200 OK response with cache-control headers set to
Cache-Control: no-cache, no-store
Since the back-channel logout flow is not executed using the user-agent (such as a browser), the session cookie of the end-user is not available to the OAuth 2.0 Client, and the session has to be invalidated by some other means.
Send the ID token in 'id_token_hint'
id_token_hint is an optional query parameter that can be provided in the logout request to indicate which OpenID Connect ID
Token was used to authenticate the user. This parameter is useful for identifying the user's session and ensuring that the user is
properly logged out.
id_token_hint is not provided, the logout request may still succeed, but it could lead to issues in cases where the
OAuth 2.0 Client has multiple sessions for the same user, the session cookie is no longer available, or the login request was not
remembered. In such cases, without the
id_token_hint, the OAuth 2.0 Client may not know which session to log out.
It is, therefore, recommended to always send the
id_token_hint parameter in the logout request to avoid such issues if possible.
Redirect after logout
post_logout_redirect_uri parameter in the OpenID Connect front and back-channel logout flow is used to redirect the user's
browser to a specified URL after the logout process is complete.
To make the
post_logout_redirect_uri parameter work, the OAuth 2.0 Client should follow these steps:
- Allow the
post_logout_redirect_uri: Each OAuth 2.0 Client can whitelist a list of URIs that can be used as the
post_logout_redirect_uriparameter value using the
post_logout_redirect_urisfield. This field should be set to a list of valid URIs that the OAuth 2.0 Client allows as the
- Set the
post_logout_redirect_uriparameter value in the logout request: When making the logout request to Ory OAuth2 & OpenID Connect, the OAuth 2.0 Client should include the
post_logout_redirect_uriparameter value in the URL query. The value should be set to the desired redirect URL.
- Set the
stateparameter value in the logout request: When making the logout request, the OAuth 2.0 Client should include a
stateparameter value in the URL query. This value should be a random string used to maintain state between the logout request and the response. After the logout process is complete, the state value will be returned in the URL query of the redirect back to the OAuth 2.0 Client's application.
- Set the
id_token_hintparameter value in the logout request: When making the logout request, the OAuth 2.0 Client should include an
id_token_hintparameter value in the URL query. This value should be set to the ID Token that was issued by Ory OAuth2 & OpenID Connect to the user during the authentication process. If included, this parameter value can help to ensure that the logout process can be performed even if no session cookie exists any more.
Logout logic diagram
The following diagram explains the different parameters and expected behavior of the logout flow: