Products » Connect2id server » Documentation » Integration »

Logout session API

1. Introduction

This Connect2id server web API lets an Identity Provider (IdP) 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 IdP with a logout request. The page at the logout endpoint calls this API to verify the request parameters and determine whether to ask the end-user for a logout confirmation.

  • The IdP -- Logout triggered from an IdP page or backend service, by calling this API directly.

To prevent unsolicited logouts and CSRF attacks this API requires RP-initiated logout requests to be confirmed by the end-user. In the confirmation prompt the end-user is given the choice to log out of the IdP as well. The API doesn't require confirmation of IdP-initiated requests, 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 IdP.

    Effects:

  • IdP logout -- For all IdP-initiated logout requests, or RP-initiated logout requests when the end-user chooses to proceed with an IdP 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 IdP 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 our mini guide.

2. Web API overview

Resources
Representations Errors

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 frontend 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 (if the user had logged out of the IdP or their IdP 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:

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:

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 string is optional as the logout request has no mandatory parameters:

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 IdP-initiated logout request. Just include the session cookie (if any) and set the initiator 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 frontend to obtain the end-user's confirmation of RP logout and optional additional IdP logout. The response contains the session details, client details for the requesting RP, and other contextual information. The logout sid is needed 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" : "[email protected]" } },
  "client"                : { "client_id"        : "Eegh1are",
                              "client_type"      : "confidential",
                              "application_type" : "web",
                              "name"             : "My App",
                              "uri"              : "https://my-app.com" }
}

Response with a logout end if the end-user has no current session with the IdP:

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 didn't confirm the RP logout this PUT call must not be made.

In addition to the confirmation, this call can include the end-user's request for an IdP logout.

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:

Success:

  • Code: 200

  • Content-Type: application/json

  • Body: {object} A JSON object representation of a logout end.

Errors:

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

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 IdP:

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 IdP session was closed, hence 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 IdP and the session cookie must be kept:

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) URI query string received at the logout endpoint, 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 (the IdP). 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 IdP 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. Since v12.15.

  • [ 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 IdP's discretion. Since v12.15.

  • [ 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. 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.

  • [ ui_locales ] {string array} The end-user's preferred UI locales, by order of preference, omitted if not specified. Since v12.15.

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" : "[email protected]" } }
}

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. Since v12.15.
    • 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 IdP logout by closing the end-user session with the IdP. If false the end-user will remain logged in with the IdP. Since v12.15.

  • [ confirm_logout = false ] {true|false} Identical to op_logout. Deprecated in v12.15, to be removed in v14.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 the end-user session in response to an IdP-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 IdP 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
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"
}