OpenID Connect Single Logout

OpenID Connect Single Logout

architect

Overview

Single Logout (SLO) is the counterpart to Single Sign On (SSO). SSO improves usability by minimizing the number of re-authentications and enabling the user to have authenticated sessions at different clients without having to provide the credentials every time. SSO also improves security. This argument is even more true for SLO. By supporting an SLO protocol a user can initiate a logout and get all sessions terminated without having to actively logout from every client. As a result a client implementing SLO protects its users and their data across a whole system because it ensures that there are no active sessions left from an SSO session that may be hijacked or otherwise misused.

OpenID Connect Logout

Logout aims to invalidate an active session. Depending on the implementation, session information resides on different places:

  • Session information is stored in the User Agent (e.g. in a cookie)
  • Session information is stored server side (e.g. in a database)

To address the different architectures OpenID Connect defines three logout mechanisms:

Session Management defines a mechanism for an OpenID client (Relying Party, RP) to monitor a user’s login status at the OpenID provider (OP, namely the Curity Identity Server). When the user logs out of the OpenID provider the client should terminate its session with the user as well.

Front-Channel Logout is handled through the user agent. For each client that has a session for the user from the OpenID provider and that supports the front-channel logout mechanism an iframe is rendered. This means that logout requests of all clients are performed in parallel.

Back-Channel Logout specifies a server-to-server communication for the logout request. Therefore there is no dependency on the user agent. As a result, users will get logged out from the client even in case the user agent was closed which will not work in the other specifications.

RP-initiated Logout

All mechanisms are eventually initiated by a logout request from the client. The Curity Identity Server publishes an endpoint called end_session_endpoint for the client-initiated (single) logout. To start a logout of the Curity Identity Server, the client will first decommission the user’s local security context (logout), and then call the end session endpoint URL at the Curity Identity Server.

A logout request looks similar to the following:

GET https://idsvr.example.com/session/logout
    ?id_token_hint=id_token_issued_to_client
    &post_logout_redirect_uri=https://client1.example.com/logged_out
    &state=random_string

The following parameters are defined by the specification:

id_token_hint: When providing the previously issued ID token, the OpenID provider gets an indication about the identity of the end user and the client that requested the logout. (recommended)

post_logout_redirect_uri: A registered, white-listed URL that the OpenID provider should redirect the user’s user agent to after a logout has been performed. (optional)

state: If specified, the OpenID provider will include the value in the callback to the post_logout_redirect_uri. In this way, the client can maintain the state between the logout request and the callback. (optional)

visualization of rp-initiated logout

  1. The user initiates the logout from the client. The client cleans up any security context for the user.
  2. The browser session is updated to reflect the logout (e.g. cookies are deleted). The user gets redirected to the end_session_endpoint.
  3. The Curity Identity Server cleans the user’s SSO session in the Authentication Service.
  4. After logout the Curity Identity Server triggers a logout at other clients using the front- or back-channel logout mechanism or a combination of both (single logout).
  5. After successful logout the user will return to the client using the post_redirect_uri if specified.

Session Management

If the OpenID provider supports Session Management, it will return a session_state as part of the Authentication Response. The session state is unique per client and user. However, a session state may be changed through login or logout activities of other clients. Using Session Management the user can logout from the Curity Identity Server and the client can monitor the session and initiate a (local) logout in case the session at the Curity Identity Server was terminated.

In detail, the Curity Identity Server publishes an endpoint called check_session_iframe that is loaded by the client in an iframe. This iframe is referred to as OP iframe in the documentation. The purpose of this iframe is to determine if a given session state has changed or not. The client will from within an iframe, the RP iframe, periodically post a message to the OP iframe to check for changes of the session state. The check has three possible outputs:

  • unchanged - session unchanged
  • changed - session changed because of some user activity (e.g. user logged out)
  • error - the OP iframe was not able to process the request (e.g. malformed message)

In case the OP iframe returns an error it is up to the client to handle the error as long as the user does not get re-authenticated since that may result in an infinite loop.

In case of a change the client must perform re-authentication to check if the user logged out or if the session changed because of other reasons. If the user logged out, the client also terminates its user sessions.

session management

  1. In Session Management Specification the Authentication Request is made as usual.
  2. The user is requested to authenticate through the Authentication Service. A new session with the Curity Identity Server is established.
  3. The Authentication Response includes the session_state as a query parameter. The client must save this value. It is required for checking the session state in step 5.
  4. The check_session_iframe from the Curity Identity Server and the client’s RP iframe are loaded into the DOM of the page.
  5. The client sends a message from the RP iframe to the OP iframe to detect any changed login state. To do this, it includes the session_state received in step 3 and its client_id. The OP iframe validates the message and posts the result back to the client’s RP iframe.
  6. If the state has changed, then a new Authentication Request is made with prompt=none and the previously issued ID token in id_token_hint.
  7. A successful response contains a new ID token and session_state.
  8. The client should check the ID token. If the user of the new ID token does not match the current user, the client should handle the case as logout. If the user is unchanged, the client updates the session_state and keeps polling. If the response is error=login_required, consent_required or interaction_required, then the client should handle the case as logout and guide the user for further processing.

Front-Channel Logout

When supporting front-channel logout the OpenID client provides an endpoint called frontchannel_logout_uri that is added during the registration process. The OpenID provider may issue ID tokens that include a unique session ID, the sid. Upon receiving a logout request, the Curity Identity Server will render an iframe with the registered logout URI as a source. Actually, it will render such an iframe for each additional client with an active session for the user that supports front-channel logout. Each client will then trigger a logout as soon as its logout URI got rendered in an iframe. When rendering the iframe the Curity Identity Server will always include the issuer ID and session ID independently if the client requires the values or not. The Curity Identity Server therefore always adds the session ID when issuing ID tokens.

front-channel

  1. The client initiates a logout request.

  2. The Curity Identity Server cleans the user’s SSO session in the Authentication Service.

  3. The Curity Identity Server responds with an HTML page that embeds an iframe for each client that has a front-channel logout URI configured.

  4. Each iframe is fetched from the clients’ frontchannel_logout_uri with the issuer ID in the iss query string argument and the session ID in the sid. The frontchannel_logout_uri is included in the dynamic configuration of a client.

  5. After successful logout, if the client provided a valid post_logout_redirect_uri as part of the client-initiated logout, the user agents is redirected there (not shown in the above figure).

Back-Channel Logout

As with the other specifications a back-channel logout starts with a client-initiated logout request. The OpenID provider will post a logout request to all clients that the user logged in at and that have a backchannel_logout_uri registered. This back-channel logout request includes a logout token, a signed JWT similar to the ID token. The client validates the token and uses its claims to identify the session that should be terminated.

back-channel

  1. The client initiates a logout request.

  2. The Curity Identity Server cleans the user’s SSO session in the Authentication Service.

  3. The Curity Identity Server creates a back-channel logout request and posts the logout_token to the client’s registered backchannel_logout_uri.

  4. After successful logout, if the client provided a valid post_logout_redirect_uri as part of the client-initiated logout, the user agent is redirected there (not shown in the above figure).

Note that session information stored in the user agent are not available in the back-channel. Therefore clients must implement an application-specific method of terminating and clearing sessions which may be more complicated than just clearing session cookies which is often what happens during front-channel logout.


The Curity Solution

Curity provides the full benefits of OAuth and OpenID Connect standards, but also offers additional functionality to combat the risk for scope explosion.

There is also special handling of claims and scopes, such as mapping claims to specific clients and custom groupings that allow for greater flexibility and a more manageable architecture.

More information

For more information, see the mentioned articles above, or the Curity Developer Portal

Let’s Stay in Touch!

Get the latest on identity management, API Security and authentication straight to your inbox.

Keep up with our latest articles and how-tos using RSS feeds