Logout session

1. Introduction

This Connect2id server web API handles logout requests:

Initiated by an OpenID relying party – A relying party (RP) can notify the Connect2id server that an end-user has been logged out of the RP by sending their browser to an end-session page. At that point the user can be asked if they also want to log out of the Connect2id server. This API provides the page with validation of the session cookie and any received request parameters (ID token hint and post-logout redirection URL).
Initiated by the OpenID provider – Logout can of course also be triggered by a UI, policy or logic belonging to the IdP.

An end-session page must be declared in the Connect2id server configuration in order to have its URL published in the OpenID provider metadata and enable this API to handle RP-initiated logout requests.

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 request parameters are specified in OpenID Connect Session Management 1.0, the section on Relying Party initiated logout (draft 28). The hidden iframes for clearing browser session state of concerned relying parties is specified in OpenID Connect Front-Channel Logout 1.0 (draft 02).

This API was introduced in Connect2id server v6.8 and was extended in v7.3 to support IdP-initiated logout and OpenID Connect front-channel notifications.

For help with implementing a logout page check our 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 403 Forbidden 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 prompts the frontend to obtain the end-user’s confirmation to log out of the OpenID provider. Indicated by a JSON object with "type":"confirm".
Logout end – For a valid OP-initiated logout request returns any relying parties’ front-channel logout URIs to notify via hidden iframes. Indicated by a JSON object with "type":"end".
Logout error – Notifies the frontend that 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 identifier of the tenant. The tenant can be alternatively specified by the Tenant-ID header. Applies to the multitenant edition of the Connect2id server.
[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 a RP-initiated logout request received at the end-session page. The session cookie (if any) is supplied in the sub_sid parameter. The received query string is optional:

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 OP-initiated logout request. Just include the session cookie (if any) and set the initiator to “OP”. There will be no prompt (confirmation) step after that.

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 frontend to obtain the end-user’s confirmation to log out of the Connect2id server. The response contains the session details for the current end-user (subject). The logout sid is needed to submit the user’s confirmation back to the Connect2id server.

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

{
  "type"        : "confirm",
  "sid"         : "eyJhbGciOiJIUzI1NiJ9.eyJzdWJfc2lkIjoieVJoajZFajRmbmNrT3...",
  "sub_session" : { "sub"           : "alice",
                    "auth_time"     : 12345678,
                    "acr"           : "http://loa.c2id.com/high",
                    "amr"           : [ "mfa", "otp", "pwd" ],
                    "creation_time" : 1234567,
                    "max_life"      : 20160,
                    "auth_life"     : 1440,
                    "max_idle"      : 15,
                    "data"          : { "name"  : "Alice Adams",
                                        "email" : "alice@wonderland.net" } }
}

If the session cookie is invalid or expired, the Connect2id server will return an error message. This means there is nobody to logout.

HTTP/1.1 OK
Content-Type: application/json

{
  "type"              : "error",
  "error"             : "invalid_session",
  "error_description" : "Invalid / expired / missing subject session",
}

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

3.2.1 PUT

Submits an end-user’s confirmation (yes or no) to log out of the Connect2id server.

Important: If the user chose to log out of the Connect2id server, the page must delete the session cookie must be deleted before submitting the logout confirmation.

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 identifier of the tenant. The tenant can be alternatively specified by the Tenant-ID header. Applies to the multitenant edition of the Connect2id server.
[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 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 submission of a confirmation that the end-user also wants to log out of the Connect2id server:

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

{
  "confirm_logout" : true
}

If the end-user doesn’t agree to log out of the OpenID provider:

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

{
  "confirm_logout" : false
}

Example end response with a post logout redirection URL and a set of hidden iframes to create for front-channel logout:

HTTP/1.1 ok
Content-Type: application/json

{
  "type"                     : "end",
  "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:

HTTP/1.1 ok
Content-Type: application/json

{
  "type" : "end"
}

4. Representations

4.1 Logout request

Specifies a logout request.

JSON object members:

[ sub_sid ] {string} The subject (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) URI query string received at the logout page, omitted or null if none.
[ 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 to also sign out of the OpenID provider.

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 subsequent request. Not to be confused with the subject (end-user) session identifier.
sub_session {object} A JSON object representation of the current subject (end-user) session.
[ client ] {object} A JSON object representation of the registered details for the requesting client, if identified by a submitted ID token hint, 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. Since v7.3.
- [ 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.

Example logout prompt, with no requesting client identified:

{
  "type"        : "confirm",
  "sid"         : "eyJhbGciOiJIUzI1NiJ9.eyJzdWJfc2lkIjoieVJoajZFajRmbmNrT3...",
  "sub_session" : { "sub"           : "alice",
                    "auth_time"     : 12345678,
                    "acr"           : "http://loa.c2id.com/high",
                    "amr"           : [ "mfa", "otp", "pwd" ],
                    "creation_time" : 1234567,
                    "max_life"      : 20160,
                    "auth_life"     : 1440,
                    "max_idle"      : 15,
                    "data"          : { "name"  : "Alice Adams",
                                        "email" : "alice@wonderland.net" } }
}

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:
- invalid_logout_request – Invalid logout request submitted by the OpenID relying party.
- rp_initiated_logout_refused – Relying party initiated logout refused, the OpenID Connect logout (end-session) endpoint is disabled.
- invalid_session – Invalid or expired subject (end-user) session.
- invalid_id_token_hint – The received ID token hint is invalid.
- post_logout_requires_id_token_hint – Post-logout redirection requires an ID token hint.
- post_logout_redirect_uri_not_registered – The post logout redirection URI is not registered for the requesting OpenID relying party.
error_description {string} The error description.

Example logout error:

{
  "type"              : "error",
  "error"             : "invalid_session",
  "error_description" : "Invalid / expired / missing subject session"
}

4.4 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.
[ post_logout_redirect_uri ] {string} If set, the logout page should redirect the browser to the URL.
[ frontchannel_logout_uris ] {string array} If set, the URLs for the hidden browser iframes to facilitate the dispatch of front-channel logout notifications to all concerned OpenID relying parties. See OpenID Connect Front-Channel Logout 1.0.

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 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"
}

403 Forbidden

The logout session endpoint is disabled.

Example:

HTTP/1.1 403 Not Found
Content-Type: application/json

{
  "error"             : "endpoint_disabled",
  "error_description" : "Logout (end-session) endpoint disabled by op.logout.endpoint configuration"
}

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
Content-Type: application/json

{
  "error"             : "server_error",
  "error_description" : "Internal server error: Something bad happened",
  "stack"             : "Exception in thread...",
  "note"              : "See the server logs for additional details"
}