Skip to main content

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 iss and 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:

  1. Register a frontchannel_logout_uri field with a valid URL in your OAuth2 client application.
  2. When a logout occurs, Ory redirects the user-agent (browser) to the specified URL.
  3. 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_uri and 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 /.well-known/jwks.json). The logout_token contains the following claims:

  • iss: Issuer identifier for the issuer of the response. The iss value 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_id of 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 example claims
{
  "iss": "https://server.example.com",
  "aud": "s6BhdRkqt3",
  "iat": 1471566154,
  "jti": "bWJq",
  "sid": "08a5019c-17e1-4977-8f42-65a12843ea02",
  "events": {
    "http://schemas.openid.net/event/backchannel-logout": {}
  }
}

After the logout_token is validated, the endpoint returns a HTTP 200 OK response with cache-control headers set to

Cache-Control: no-cache, no-store
Pragma: no-cache

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.

When the 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​

The 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:

  1. 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_uri parameter value using the post_logout_redirect_uris field. This field should be set to a list of valid URIs that the OAuth 2.0 Client allows as the post_logout_redirect_uri.
  2. Set the post_logout_redirect_uri parameter 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_uri parameter value in the URL query. The value should be set to the desired redirect URL.
  3. Set the state parameter value in the logout request: When making the logout request, the OAuth 2.0 Client should include a state parameter 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.
  4. Set the id_token_hint parameter value in the logout request: When making the logout request, the OAuth 2.0 Client should include an id_token_hint parameter 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: