Logout session

1. Introduction

This web API enables implementation of a logout page where an end-user can be sent to sign out of the Connect2id server. To prevent unwanted logouts the UI must always ask the end-user to confirm the action.

OpenID clients (relying parties) initiating the logout request are encouraged to include the user’s ID token as parameter (id_token_hint), so that the Connect2id server can properly account the event.

https://c2id.com/logout?id_token_hint=eyJraWQiOiJhb2N0IiwiYWxnIjoiUlMyNTYifQ...

Clients can also request the end-user to be redirected to some URI (post_logout_redirect_uri) after the logout dialog, regardless of whether the end-user confirms or not to logout from the IdP. An optional state parameter may be passed.

In order to use the redirection feature the client must include a valid ID token hint for the logged out end-user. The possible post logout redirection URIs must have also been registered for the given client.

https://c2id.com/logout?id_token_hint=eyJraWQiOiJhb2N0IiwiYWxnIjoiUlMyNTYifQ...
    &post_logout_redirect_uri=https://client.example.com/logout
    &state=aSh9Ohqu

The logout endpoint and request parameters are specified in OpenID Connect Session Management 1.0, the section on Relying Party initiated logout (draft 28).

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

Additional details are found in the logout endpoint configuration reference.

This API is available since Connect2id server v6.8.

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 to process a request received by the logout page.

The POST produces one of the following JSON objects:

Logout prompt – Prompts the frontend to obtain the subject’s (end-user’s) confirmation to log out of the OpenID provider. Indicated by a JSON object with "type":"confirm".
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.

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 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 received logout request with the Connect2id server. The session cookie (if any) is supplied in the sub_sid parameter. The query string is also optional:

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

{
  "sub_sid" : "0ZjiiO5wFamFtPrxC_51Rg.C64tzJ2ICqZaSObmPVO4Gg",
  "query"   : "id_token_hint=eyJraWQiOiJhb2N0IiwiYWxnIjoiUlMyNTYifQ..."
}

Example response prompting the frontend to obtain the subject’s confirmation to log out of the Connect2id server. The response contains the session details for the current 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 that 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 a subject’s (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 user 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.

Body:

A JSON object representation of one 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 subject 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 subject 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
}

The end response will be empty, unless a post logout redirection was requested by the OpenID client. If a URI is given, the logout page should redirect to it.

HTTP/1.1 ok
Content-Type: application/json

{
  "type"                     : "end",
  "post_logout_redirect_uri" : "https://client.example.com/logout"
}

With no post logout redirection:

HTTP/1.1 ok
Content-Type: application/json

{
  "type" : "end"
}

4. Representations

4.1 Logout request

Specifies a request received at the logout page (end-session endpoint).

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.

Example JSON object for a logout request, specifying a subject session identifier (SID) obtained from the browser cookie; the query parameter is omitted as no URL query string was received:

{
  "sub_sid" : "0ZjiiO5wFamFtPrxC_51Rg.C64tzJ2ICqZaSObmPVO4Gg"
}

Example logout request which also includes a query string:

{
  "sub_sid" : "0ZjiiO5wFamFtPrxC_51Rg.C64tzJ2ICqZaSObmPVO4Gg",
  "query"   : "id_token_hint=eyJraWQiOiJhb2N0IiwiYWxnIjoiUlMyNTYifQ..."
}

4.2 Logout prompt

Prompts the logout page to obtain the subject’s (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.
- [ 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).
- [ 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_session – Invalid or expired subject (end-user) session.
- invalid_logout_request – Invalid logout request submitted by the OpenID client.
- invalid_id_token_hint – The ID token hint is invalid.
- post_logout_redirect_uri_not_registered – The specified post logout redirection URI is not registered for the requesting OpenID client.
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.

Simple logout end:

{
  "type" : "end"
}

Logout end with a redirection URL:

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

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