Logout session

1. Overview

This Connect2id server web API lets an OpenID provider handle requests for end-user logout.

The requests for logout can be initiated by:

An OpenID relying party (RP) – By sending the end-user to the logout endpoint of the OpenID provider with a logout request. The page at the logout endpoint uses this API to validate the parameters of the request and find out whether the end-user must confirm the logout.
The OpenID provider – Logout triggered from a UI or service in the OpenID provider domain, by calling this API directly.

To prevent unsolicited logouts and CSRF attacks this API requires RP-initiated requests for logout to be confirmed by the end-user. In the confirmation the end-user is given the choice to log out of the OpenID provider as well. The end-user is never asked to confirm logout requests initiated by the OpenID provider, assuming they had a prior CSRF check.

The scope of logout can thus be:

RP-only logout – For an RP-initiated logout request when the end-user chooses to remain logged in with the OpenID provider.

Effects:
- The client_id of the RP is removed from the session rps list.
- If the RP is registered to receive back or front-channel logout notifications the Connect2id server will trigger them.
OpenID provider wide logout – For all OpenID provider initiated logout requests, or RP-initiated logout requests when the end-user chooses to proceed with an OpenID provider logout.

Effects:
- The Connect2id server ends the current end-user session. Note that other sessions of the end-user (in other browsers and devices) with the OpenID provider remain unaffected.
- For all RPs in the session rps list that are registered to receive back or front-channel logout notifications the Connect2id server will trigger them.

To enable handling of RP-initiated logout requests by this API a logout (end-session) endpoint must be declared in the Connect2id server configuration. Its URL will then be published in the OpenID provider metadata.

Access to the logout session API is protected by means of a long-lived token. The token must be passed with each HTTP request in the Authorization header:

Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

The logout endpoint and its request parameters are specified in RP-Initiated Logout 1.0. The hidden HTML iframes for delivering front-channel logout notifications to subscribed RPs is specified in Front-Channel Logout 1.0.

For help with implementing a logout page check out the guide.

2. Web API overview

Resources
/logout-sessions/rest/v1/ [POST] /logout-sessions/rest/v1/{sid} [PUT]
Representations	Errors
Logout request Logout prompt Logout error Logout confirmation Logout end	400 Bad Request 401 Unauthorized 500 Internal Server Error

3. Resources

3.1 /logout-sessions/rest/v1/

3.1.1 POST

Starts a new logout session with the Connect2id server.

The POST produces one of the following JSON objects:

Logout prompt – For a valid RP-initiated logout request and a present end-user session prompts the page to obtain the end-user’s confirmation. Indicated by a JSON object with "type":"confirm".
Logout end – For a valid RP-initiated logout request but no present end-user session (the user has logged out of the Connect2id server or their session expired). Indicated by a JSON object with "type":"end".
Logout error – The submitted logout request cannot be performed. Indicated by a JSON object with "type":"error".

Header parameters:

Authorization Must specify the configured bearer access token for this web API.
Content-Type Must be set to application/json.
[ Issuer ] The issuer URL when issuer aliases are configured, or the issuer URL for a tenant (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Tenant-ID header.
[ Tenant-ID ] The tenant ID. The tenant can be alternatively specified by the Issuer header. Applies to the multitenant edition of the Connect2id server.

Body:

A JSON object representation of a logout request.

Success:

Code: 200
Content-Type: application/json
Body: {object} A JSON object representation of a logout prompt, logout end or a logout error. The JSON objects can be differentiated by their type value.

Errors:

400 Bad Request
401 Unauthorized
403 Forbidden
500 Internal Server Error

Example POST to process an RP-initiated logout request received at the logout endpoint. The session cookie (if any) is passed in the sub_sid parameter. The query is optional as the logout request has no mandatory parameters. Here it includes an id_token_hint:

POST /logout-sessions/rest/v1/ HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
Content-Type: application/json

{
  "sub_sid" : "WYqFXK7Q4HFnJv0hiT3Fgw.-oVkvSXgalUuMQDfEsh1lw",
  "query"   : "id_token_hint=eyJraWQiOiJhb2N0IiwiYWxnIjoiUlMyNTYifQ..."
}

Example POST for an OpenID provider-initiated logout request. Includes the OpenID provider session cookie for the end-user (if any), the initiator is set to OP:

POST /logout-sessions/rest/v1/ HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
Content-Type: application/json

{
  "sub_sid"   : "WYqFXK7Q4HFnJv0hiT3Fgw.-oVkvSXgalUuMQDfEsh1lw",
  "initiator" : "OP"
}

Example response prompting the page to obtain the end-user’s confirmation of RP logout and optional additional OpenID provider logout. The response contains the session details, client details for the requesting RP, and other contextual information. The logout sid may be needed later, to submit the user’s confirmation to the Connect2id server.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "type"                  : "confirm",
  "sid"                   : "eyJhbGciOiJIUzI1NiJ9.eyJzdWJfc2lkIjoieVJoajZFaj...",
  "id_token_hint_present" : true,
  "sub_session"           : { "sub"           : "alice",
                              "auth_time"     : 1657615133,
                              "acr"           : "https://loa.c2id.com/high",
                              "amr"           : [ "mfa", "otp", "pwd" ],
                              "creation_time" : 1657615133,
                              "max_life"      : 20160,
                              "auth_life"     : 1440,
                              "max_idle"      : 15,
                              "data"          : { "name"  : "Alice Adams",
                                                  "email" : "alice@example.com" } },
  "client"                : { "client_id"        : "Eegh1are",
                              "client_type"      : "confidential",
                              "application_type" : "web",
                              "name"             : "My App",
                              "uri"              : "https://my-app.com" }
}

Response with a logout end when the end-user doesn’t have a session with the Connect2id server (and no post-logout redirection was requested). There is no OpenID provider session to close, hence no need for further interaction with the end-user:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "type"               : "end",
  "sub_session_closed" : false
}

If the logout request cannot be fulfilled the Connect2id server will return an error message.

Example error for an RP-initiated logout request with an invalid id_token_hint and / or client_id parameter. The exact error cause is recorded in the server log.

HTTP/1.1 OK
Content-Type: application/json

{
  "type"              : "error",
  "error"             : "invalid_id_token_hint",
  "error_description" : "Invalid ID token hint or client ID"
}

3.2 /logout-sessions/rest/v1/{sid}

3.2.1 PUT

Submits an end-user’s confirmation of an RP-initiated logout. If the end-user did not confirm the RP logout this call must not be made.

In addition to the confirmation, this call can include the end-user’s choice to also log out of the OpenID provider.

Path parameters:

sid {string} The logout session identifier (SID).

Header parameters:

Authorization Must specify the configured bearer access token for this web API.
Content-Type Must be set to application/json.
[ Issuer ] The issuer URL when issuer aliases are configured, or the issuer URL for a tenant (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Tenant-ID header.
[ Tenant-ID ] The tenant ID (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Issuer header.

Body:

A JSON object representation of the obtained logout confirmation.

Success:

Code: 200
Content-Type: application/json
Body: {object} A JSON object representation of a logout end.

Errors:

400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

Example confirmation that the end-user logged out of the RP, but chose to remain logged in with the OpenID provider:

PUT /logout-sessions/rest/v1/eyJhbGciOiJIUzI1NiJ9... HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
Content-Type: application/json

{
  "op_logout" : false
}

If the end-user chose to log out of the OpenID provider:

PUT /logout-sessions/rest/v1/eyJhbGciOiJIUzI1NiJ9... HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
Content-Type: application/json

{
  "op_logout" : true
}

Example end response with a post logout redirection URL and a set of hidden HTML iframes to create for front-channel logout. The sub_session_closed indicates the Connect2id server session for the end-user was closed, thus the session cookie is to be deleted:

HTTP/1.1 ok
Content-Type: application/json

{
  "type"                     : "end",
  "sub_session_closed"       : true,
  "post_logout_redirect_uri" : "https://client.example.com/logout",
  "frontchannel_logout_uris" : [ "https://client.example.com/fc?iss=...",
                                 "https://client.example.org/fc?iss=...",
                                 "https://client.example.net/fc?iss=..." ]
}

Example minimal end response with no post logout redirection and no front-channel logout iframes. The sub_session_closed indicates the end-user chose to remain logged in with the OpenID provider:

HTTP/1.1 ok
Content-Type: application/json

{
  "type"               : "end",
  "sub_session_closed" : false
}

4. Representations

4.1 Logout request

Specifies a logout request.

JSON object members:

[ sub_sid ] {string} The end-user session identifier (SID), saved in a browser cookie, omitted or null if none. The SID is used to retrieve the session of the present end-user.
[ query ] {string} The raw (not decoded) logout request parameters received at the logout endpoint, omitted or null if none.

If the logout endpoint received an HTTP POST with a Content-Type of application/x-www-form-urlencoded this must be the form parameters string.

If the logout endpoint received an HTTP GET this must be the URI query string.
[ initiator = “RP” ] {“RP”|“OP”} The logout request initiator. “RP” indicates the request was initiated by an OpenID relying party, “OP” by the OpenID provider. Defaults to “RP”.

Example JSON object for a logout request initiated by an RP, specifying an end-user session identifier (SID) obtained from the browser cookie. The query parameter is omitted as no URL query string was received:

{
  "sub_sid" : "WYqFXK7Q4HFnJv0hiT3Fgw.-oVkvSXgalUuMQDfEsh1lw"
}

Example RP-initiated logout request which also includes a query string:

{
  "sub_sid" : "WYqFXK7Q4HFnJv0hiT3Fgw.-oVkvSXgalUuMQDfEsh1lw",
  "query"   : "id_token_hint=eyJraWQiOiJhb2N0IiwiYWxnIjoiUlMyNTYifQ..."
}

4.2 Logout prompt

Prompts the logout page to obtain the end-user’s confirmation of RP logout. In addition to that the end-user should also be asked if they want to log out of the OpenID provider as well.

The id_token_hint_present indicates whether the request included a valid ID token hint and may be used as policy input to potentially skip the user confirmation.

JSON object members:

type {string} Set to confirm. Used to differentiate this object from a logout error and logout end.
sid {string} The logout session identifier, used to refer to the logout session in the next request. Not to be confused with the subject (end-user) session identifier.
sub_session {object} A JSON object representation of the current end-user session.
id_token_hint_present {true|false} Indicates whether an ID token hint was included in the RP logout request. Note that if the ID token hint was found invalid or not matching the current session subject this results in a invalid_id_token_hint error.
[ logout_hint ] {string} 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.
[ client ] {object} A JSON object representation of the registered details for the requesting client, if identified by a submitted ID token hint and / or client ID, else omitted.
- client_id {string} The identifier of the client application.
- client_type {“confidential”|“public”} Indicates the OAuth client type. Public clients may be granted limited scopes and should be denied incremental authorisation.
- application_type {“web”|“native”} The client application type.
- [ contacts ] {string array} Array of e-mail addresses of people responsible for the client.
- [ name ] {string} Optional name of the client application to be presented to the end-user. May use language tags (BCP47).
- [ uri ] {string} Optional URI of the home page of the client application to be presented to the end-user in a followable fashion. May use language tags (BCP47).
- [ logo_uri ] {string} Optional logo of the client application to be presented to the end-user. May use language tags (BCP47).
- [ policy_uri ] {string} Optional URI of a page describing how the end-user profile data will be used by the client application, to be presented to the end-user in a followable fashion. May use language tags (BCP47).
- [ tos_uri ] {string} Optional URI of a page describing the client application’s terms of service, to be presented to the end-user in a followable fashion. May use language tags (BCP47).
- [ scope ] {string array} Optional OAuth 2.0 scope values that the client application may request. These values are set at client registration; their semantics and treatment is policy matter and may be ignored.
- [ data ] {object} Optional client data.
[ ui_locales ] {string array} The end-user’s preferred UI locales, by order of preference, omitted if not specified.

Example logout prompt, indicating the RP logout request included no id_token_hint to identify the end-user session and no client_id to identify the caller RP:

{
  "type"                  : "confirm",
  "sid"                   : "eyJhbGciOiJIUzI1NiJ9.eyJzdWJfc2lkIjoieVJoajZFaj...",
  "id_token_hint_present" : false,
  "sub_session"           : { "sub"           : "alice",
                              "auth_time"     : 1657615133,
                              "acr"           : "https://loa.c2id.com/high",
                              "amr"           : [ "mfa", "otp", "pwd" ],
                              "creation_time" : 1657615133,
                              "max_life"      : 20160,
                              "auth_life"     : 1440,
                              "max_idle"      : 15,
                              "data"          : { "name"  : "Alice Adams",
                                                  "email" : "alice@example.com" } }
}

4.3 Logout error

Logout error. Should be displayed to the end-user.

JSON object members:

type {string} Set to error. Used to differentiate this object from a logout prompt and logout end.
error {string} The error code:
- rp_initiated_logout_refused – The relying party initiated logout was refused due to a disabled logout (end-session) endpoint.
- invalid_request – Invalid RP-initiated logout request.
- invalid_id_token_hint – The ID token hint and / or client ID in the RP-initiated logout request are invalid. This error can also indicate a mismatch between the ID token subject and the session subject. Note, the ID token verification performed by the logout session API allows expired tokens (with “exp” in the past).
- post_logout_requires_id_token_hint – Post-logout redirection requires an ID token hint or a client ID.
- post_logout_redirect_uri_not_registered – The post logout redirection URL is not registered for the requesting OpenID relying party.
error_description {string} The error description.
[ ui_locales ] {string array} The end-user’s preferred UI locales, by order of preference, omitted if not specified. Since v12.15.

Example logout error:

{
  "type"              : "error",
  "error"             : "invalid_id_token_hint",
  "error_description" : "Invalid ID token hint or client ID"
}

4.4 Logout confirmation

End-user confirmation of an RP-initiated logout.

JSON object members:

[ op_logout = false ] {true|false} If true the Connect2id server will perform an OpenID provider logout by closing its end-user session. If false the end-user remains logged in with the OpenID provider.
[ confirm_logout = false ] {true|false} Identical to op_logout. Deprecated in v12.15, to be removed in v15.0.

4.5 Logout end

The final response from the Connect2id server after processing a logout request.

JSON object members:

type {string} Set to end. Used to differentiate this object from a logout prompt and logout error.
sub_session_closed {true|false} When true indicates the Connect2id server closed its end-user session in response to an OpenID provider initiated logout request, or in response to an RP-initiated logout request with a submitted end-user confirmation that included the choice to log out of the OpenID provider as well. To be used as a hint to delete the browser cookie linked to the session. Note that the deletion of the session cookie is not critical and not absolutely necessary, because the session ID is invalidated on the server side. Since v13.6.
[ post_logout_redirect_uri ] {string} If set, the logout page should redirect the browser to this URL.
[ frontchannel_logout_uris ] {string array} If set, the URLs of the hidden browser HTML iframes to dispatch front-channel logout notifications to all concerned OpenID relying parties. See OpenID Connect Front-Channel Logout 1.0.
[ ui_locales ] {string array} The end-user’s preferred UI locales, by order of preference, omitted if not specified.

Simple logout end:

{
  "type" : "end"
}

Logout end with a redirection URL:

{
  "type"                     : "end",
  "post_logout_redirect_uri" : "https://client.example.com/logout?state=abc..."
}

Logout end with a redirection URL and three URLs to render in hidden HTML iframes to notify subscribed OpenID relying parties of the logout via the front-channel:

{
  "type"                     : "end",
  "post_logout_redirect_uri" : "https://client.example.com/logout?state=abc...",
  "frontchannel_logout_uris" : [ "https://client.example.com/fc?iss=...",
                                 "https://client.example.org/fc?iss=...",
                                 "https://client.example.net/fc?iss=..." ]
}

5. Errors

400 Bad Request

Invalid or malformed request.

Example:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error"             : "invalid_request",
  "error_description" : "Bad request: Invalid JSON: Unexpected token foo at position 3."
}

401 Unauthorized

The request was denied due to an invalid or missing bearer access token.

Example:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer
Content-Type: application/json

{
  "error"             : "missing_token",
  "error_description" : "Unauthorized: Missing Bearer access token"
}

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