How to bind a logout page to the Connect2id server

This is a short guide how to integrate a logout page for your OpenID provider, compliant with the session management spec.

1. Configure the Connect2id server

Edit the logout endpoint configuration of the Connect2id server:

  • op.logout.endpoint -- Set the URL of the logout page, e.g. https://idp.example.com/ui/logout.

  • op.logout.apiAccessToken -- Generate a new token for the logout session API where the login page will bind. If you're 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 the logout page

Create a logout page at the URL which you 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.

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 safe location.

Step 1.

Upon receiving an HTTP request, post the cookie with 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, use null.

The request is authorised with the bearer access token generated above.

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 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 user session details, so you can personalise the UI.

If the user agrees, delete the session cookie, and then put the following confirmation:

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

{
  "confirm_logout" : true
}

If the user chooses not to logout, simply set confirm_logout to false:

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

{
  "confirm_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 now processed by the Connect2id server.

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",
  "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 suitable location.

Step 5.

Display the error message and stop.

Example error message response:

HTTP/1.1 OK
Content-Type: application/json

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