OpenID Connect logout (end-session) endpoint

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

A Connect2id server deployment can have an optional logout endpoint to

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

Single logout

This endpoint, in conjunction with the back and front-channel logout notification protocols, enables an OpenID provider together with 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 this endpoint the end-user will typically be 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 where the end-user has logged in during the session that was just closed. Once notified the applications can close their own sessions for the end-user.
  
  Note, according to the standard, the application that initiated the logout will be 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, requesting the OpenID provider to 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.
No id_token_hint or client_id – The end-user is given the choice to log out of the OpenID provider.

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 a logout endpoint is provided it is advertised in the end_session_endpoint server metadata 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

Sends the end-user to log out of the OpenID provider.

Header parameters:

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

Form parameters:

[ client_id ] The client ID. Use of this parameter is recommended.
[ id_token_hint ] Previously issued ID token to be used as hint about the end-user’s current authenticated session with the client. The ID token expiration (exp) can be in the past.

The ID token may be encrypted for confidentiality. The ID token encryption can be either to a public encryption RSA or EC JWK published at the server JWKs endpoint, or symmetric 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 about 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 ] URL to which the browser should be redirected after all user interactions at the logout endpoint are 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 URL.
[ ui_locales ] The end-user’s preferred UI locales as space delimited list, by order of preference, omitted if not specified.

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

Sends the end-user to log out of the OpenID provider.

Query parameters:

[ client_id ] The client ID. Use of this parameter is recommended.
[ id_token_hint ] Previously issued ID token to be used as hint about the end-user’s current authenticated session with the client. The ID token expiration (exp) can be in the past.

The ID token may be encrypted for confidentiality. The ID token encryption can be either to a public encryption RSA or EC JWK published at the server JWKs endpoint, or symmetric 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 about 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 ] URL to which the browser should be redirected after all user interactions at the logout endpoint are 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 URL.
[ ui_locales ] The end-user’s preferred UI locales as space delimited list, by order of preference, omitted if not specified.

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 doesn’t exist.

Example:

HTTP/1.1 404 Not Found

500 Internal Server Error

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

Example:

HTTP/1.1 500 Internal Server Error