Products » Connect2id server » Documentation » Guides »

How to bind a logout page to the Connect2id server

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

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 where the login page will bind. 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 starting point to create your own branded 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.

Step 1.

Upon receiving an HTTP request, post the cookie holding the user session ID (sub_sid) and the query string (query) to the logout session endpoint. If no session cookie or query string is found 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 respond with a JSON object.

If the JSON object is an logout prompt, go to step 3.

If the JSON object is a logout end, go to step 4.

If the JSON object is a logout error, go to step 5.

Step 3.

Display a simple dialog, asking if the user wants to log out of the OpenID provider. The logout prompt will include the available user session details, so you can personalise the UI.

The id_token_hint_presented will indicate if 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 additional user confirmation to ensure the logout request was not unsolicited.

If the user chooses to log out of the OpenID provider put 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 in set the confirm_logout to false:

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

{
  "op_logout" : false
}

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 OpenID client didn't request a redirection after the logout dialog, you may still redirect the browser to some appropriate page, 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 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"
}