Skip to content
Connect2id

How to integrate a logout UI with a Connect2id server

This is a mini guide how to integrate a logout page (UI) for your OpenID provider server, compliant with the relying-party-initiated logout and the front-channel logout standards.

1. Configure the Connect2id server

Edit the logout endpoint configuration of the Connect2id server:

  • op.logout.endpoint – Set to the URL of the logout page, e.g. to https://c2id.com/ui/logout.

  • op.logout.apiAccessToken – Generate a new token for the logout session API. On Linux you can generate a secure 32 character random string with the pwgen 32 command.

  • op.logout.sessionLifetime – You can leave this setting as it is.

Remember to restart the Connect2id server so that the updated configuration can take effect!

2. Create a logout page

Create a logout page at the URL configured above. It must be on the same domain as the login page, so both pages can access the cookie for the user sessions with the Connect2id server.

Logout confirmation

Sample logout page

Connect2id provides a sample logout page which you can use as a starting point to create your own OpenID provider logout page.

In order to process logout requests, the page must be able to access the logout session API exposed by the Connect2id server. Access to this API is secured by means of the token configured above. Make sure the token is stored in the web app settings for the logout page, or in some other secure location.

The logout session API represents a simple finite state machine, and thus it resembles the principle of the authorisation session API.

Step 1.

Upon receiving an HTTP request obtain the following:

  • The cookie for the user session ID (sub_sid), if present.

  • The request parameters string, if present. For an HTTP POST this is the application/x-www-form-urlencoded form parameters. For an HTTP GET this is the URI query string.

Post them to the logout session API. If no session cookie or query string is present omit the parameter or make it null.

The request is authorised with the configured bearer access token.

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

Step 2.

The Connect2id server will process the logout request parameters and respond with a JSON object:

Step 3.

Display a simple dialog to let the user confirm that the logout is intended and whether they also want to logout from the OpenID provider.

The logout prompt will include the session details, so you can personalise the UI.

If the client object is set the logout request included a valid id_token_hint and / or client_id.

The id_token_hint_presented indicates whether the logout request included a valid ID token hint. This input can be used to implement policies that require all relying parties to include an ID token hint in the logout request, else treat the request as suspicious and require an explicit user confirmation to ensure the logout request was not unsolicited.

If the user chooses to log out of the OpenID provider submit the following confirmation:

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

{
  "op_logout" : true
}

If the user chooses to remain logged with the OpenID provider submit a confirmation with op_logout set to false:

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

{
  "op_logout" : false
}

If the logout request is deemed suspicious do nothing.

The PUT must be to the logout sid given in the logout prompt.

Go to step 4.

Step 4.

With the end response the logout request is completed by the Connect2id server.

The sub_session_closed indicates whether the user session with the OpenID provider was closed. If true delete the user session cookie. If false leave the session cookie so the browser login state remains.

If the response includes a post_logout_redirect_uri, redirect to it.

Example end response with redirect:

HTTP/1.1 OK
Content-Type: application/json

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

If the client didn’t request a redirection after the logout dialog, you may still redirect the browser, for example the OpenID provider login page.

If the response includes frontchannel_logout_uris, create a hidden iframe for each one to notify any subscribed OpenID relying parties where the user is recorded to have a session of the logout event via the front channel. You can find more information in the front-channel logout notification spec. OpenID relying parties subscribed for back-channel notifications will be notified by the Connect2id server directly.

HTTP/1.1 OK
Content-Type: application/json

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

Step 5.

Display the human readable error_description from the error message and stop.

Example error message response:

HTTP/1.1 OK
Content-Type: application/json

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