OpenID Connect logout (end-session) endpoint

1. Notifying the IdP of user logout at a client application

A Connect2id server deployment may provide an optional logout endpoint to

let client applications (OpenID relying parties) to notify the OpenID provider that an end-user has logged out of the application, and
give the end-user a choice to log out of the OpenID provider as well.

Single logout

Together with the back and front-channel logout notification protocols, this endpoint enables an OpenID provider and participating applications to implement single logout:

The end-user chooses to log out at a participating application.
The application ends its own session for the end-user and redirects to this logout endpoint at the OpenID provider.
At the logout endpoint, the end-user is typically asked whether they also want to log out of the OpenID provider.
If the end-user chooses to log out of the OpenID provider, the Connect2id server will:
- Close its session for the end-user, and
- Dispatch back and front-channel logout notifications to all registered applications in which the end-user established a session during the OpenID provider session that was just closed.
  
  Note that, according to the standard, the application that initiated the logout is also included in the notifications if it’s registered to receive them.

Usage patterns

id_token_hint and / or client_id – Notifies the OpenID provider that the end-user has logged out of the application. The end-user is given the choice to log out of the OpenID provider as well.
id_token_hint and / or client_id + post_logout_redirect_uri + state – Same as above, but additionally requests that the OpenID provider redirect the user’s browser to a registered URL, for example back to the application. The optional state parameter enables passing of state to the redirection URL target and may be used as a measure to prevent CSRF attacks.

Specifications

For the logout (end-session) endpoint: OpenID Connect RP-Initiated Logout 1.0.
Logout notifications from an OpenID provider to subscribed relying parties:
- OpenID Connect Back-Channel Logout 1.0
- OpenID Connect Front-Channel Logout 1.0

2. The logout endpoint URL

If configured, the logout endpoint is advertised in the end_session_endpoint server metadata parameter and may look like this:

https://c2id.com/logout

3. Web API overview

Resources
[end-session-endpoint] [POST] [GET]
Errors
404 Not Found 500 Internal Server Error

4. Resources

4.1 [end-session-endpoint]

This resource supports both POST and GET. The recommended method is POST, to prevent the optional id_token_hint from potentially being recorded in web server logs.

4.1.1 POST

Initiates log out at of the OpenID provider.

Header parameters:

Content-Type Must be set to application/x-www-form-urlencoded.

Form parameters:

[ client_id ] The client ID. Clients are strongly encouraged to include this parameter, especially when using encrypted ID token hints.
[ id_token_hint ] A previously issued ID token to be used as hint about the end-user’s identity. The ID token expiration (exp) may be in the past.

The Connect2id server uses the ID token subject (sub) to verify that the logout request corresponds to the current subject (sub) of the OpenID provider session. A mismatch causes the logout request to be rejected.

Note that the optional ID token session ID (sid) is ignored and is not required to match the current OpenID provider session.

The ID token may be encrypted for confidentiality. The ID token may be encrypted either to a public RSA or EC encryption key published at the server JWK set endpoint, or symmetrically if the client is provisioned with a client_secret. The symmetric encryption must use an AES key derived from the client_secret with the dir JWE algorithm and a supported JWE method listed in the id_token_encryption_enc_values_supported server metadata.
[ logout_hint ] A hint identifying the end-user that is logging out, such as the user’s email address, telephone number or username. Analogous to the login_hint OpenID authentication request parameter. Acceptance and interpretation of this parameter is at the OpenID provider’s discretion.
[ post_logout_redirect_uri ] URI to which the browser should be redirected after all interactions at the logout endpoint have completed. The URL must be registered in the post_logout_redirect_uris metadata parameter for the requesting client. Requires a valid client_id or id_token_hint parameter.
[ state ] Optional state to append to the post logout redirection URI.
[ ui_locales ] The end-user’s preferred UI locales as a space-delimited list, ordered by preference.

Success:

Code: 200
Content-Type: text/html
Body: HTML page.

Errors:

404 Not Found
500 Internal Server Error

Example logout request with a post-logout redirection:

POST /logout HTTP/1.1
Host: c2id.com
Content-Type: application/x-www-form-urlencoded

id_token_hint=eyJraWQiOiJhb2N0IiwiYWxnIjoiUlMyNTYifQ...
&post_logout_redirect_uri=https%3A%2F%2Fclient.example.org%2Fpost-logout
&state=af0ifjsldkj

4.1.2 GET

Initiates log out at of the OpenID provider.

Query parameters:

[ client_id ] The client ID. Clients are strongly encouraged to include this parameter, especially when using encrypted ID token hints.
[ id_token_hint ] A previously issued ID token to be used as hint about the end-user’s identity. The ID token expiration (exp) may be in the past.

The Connect2id server uses the ID token subject (sub) to verify that the logout request corresponds to the current subject (sub) of the OpenID provider session. A mismatch causes the logout request to be rejected.

Note that the optional ID token session ID (sid) is ignored and is not required to match the current OpenID provider session.

The ID token may be encrypted for confidentiality. The ID token may be encrypted either to a public RSA or EC encryption key published at the server JWK set endpoint, or symmetrically if the client is provisioned with a client_secret. The symmetric encryption must use an AES key derived from the client_secret with the dir JWE algorithm and a supported JWE method listed in the id_token_encryption_enc_values_supported server metadata.
[ logout_hint ] A hint identifying the end-user that is logging out, such as the user’s email address, telephone number or username. Analogous to the login_hint OpenID authentication request parameter. Acceptance and interpretation of this parameter is at the OpenID provider’s discretion.
[ post_logout_redirect_uri ] URI to which the browser should be redirected after all interactions at the logout endpoint have completed. The URL must be registered in the post_logout_redirect_uris metadata parameter for the requesting client. Requires a valid client_id or id_token_hint parameter.
[ state ] Optional state to append to the post logout redirection URI.
[ ui_locales ] The end-user’s preferred UI locales as a space-delimited list, ordered by preference.

Success:

Code: 200
Content-Type: text/html
Body: HTML page.

Errors:

404 Not Found
500 Internal Server Error

Example logout request with an ID token hint:

GET /logout?id_token_hint=eyJraWQiOiJhb2N0IiwiYWxnIjoiUlMyNTYifQ... HTTP/1.1
Host: c2id.com

5. Errors

404 Not Found

The requested resource does not exist.

Example:

HTTP/1.1 404 Not Found

500 Internal Server Error

An unexpected internal server error has occurred. Check the Connect2id server logs for details.

Example:

HTTP/1.1 500 Internal Server Error