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