

OpenID Connect Single Logout¶

What is Single Logout (SLO)?

When a user logs out from a particular client application, the user will be automatically logged out from all the other client applications in the same login session. This eliminates the need to log out from each client application one by one.

Note

The following phrases will be interchangeably used within this document: - Identity provider and OpenID Connect Provider (OP) : These indicate the OAuth2 authentication servers that implement OpenID Connect (OIDC). - Client application and Relying Party (RP) : These are the OAuth2 clients that rely on OIDC for authentication. - Browser and user agent

Following are the three SLO mechanisms supported by OIDC:

OIDC Session Management
OIDC Back-Channel Logout
OIDC Front-Channel Logout

OIDC Session Management¶

This mechanism enables defining how to monitor the user's login status at the identity provider's end so that the client application can automatically log out the user who is logged out from the identity provider.

As per the OIDC session management specification , WSO2 Identity Server enables an application to monitor login status of an end user against the identity provider so that the RP can log out any end users that have logged out of the identity provider. For example, suppose there are two RPs relying on the identity provider, when an end user logs out of one of the applications, the user will be automatically logged out of the other RP. In this logout mechanism, front-channel communication is used to communicate the request messages.

Front-channel communication

Front-channel communication enables communication between two or more observable parties.
In this method, the request messages are communicated between the servers via a user agent.

Endpoint discovery¶

To enable OIDC session management, the RP needs to obtain the following OP endpoint URLs:

OP logout endpoint URL
OP iframe URL

OP logout endpoint URL¶

When a user is logged out from the RP, the RP redirects to the OP's logout endpoint URL to log out the user at the OP.
The logout endpoint URL can be discovered using the end_session_endpoint parameter in the OIDC Discovery response.

For more information on OIDC Discovery, see OpenID Connect Discovery.

The logout endpoint URL is in the following format.

Format

https://<PRODUCT_HOST>:<PRODUCT_PORT>/oidc/logout

Example

    https://localhost:9443/oidc/logout

The logout request sent by the RP to OP includes the following query parameters.

Query Parameter Applicability Description

id_token_hint

Recommended

This is the previously-issued ID token that was passed to the logout endpoint hinting about the user's current authentication session with the RP. This indicates the identity of the user that the RP is requesting to be logged out by the OP.

If the id_token_hint is passed to the logout endpoint, WSO2 Identity Server identifies the RP to which the token is issued to and redirects the user to the callback URL of the RP that is configured in WSO2 Identity Server. To learn how to configure the RP in WSO2 Identity Server, see Configurations .

If the id_token_hint is not passed to the logout endpoint, the user is redirected to the default logout page subsequent to a successful logout.

post_logout_redirect_uri

Optional

This is the URL to which the RP requests the end user's user agent be redirected after a logout.

Note

The post_logout_redirect_uri should be registered in WSO2 Identity Server based on the regex option provided for configuring multiple callback URLs.

To learn how to configure the RP with multiple callback URLs in WSO2 Server, see Configurations .

state

Optional

This is an opaque value that is used by the RP for maintaining the state between the logout request and the callback to the endpoint that is specified in the post_logout_redirect query parameter.

If the state is included in the logout request, WSO2 Identity Server passes this value back to the RP in the state query parameter when redirecting the user agent back to the RP.

OP iframe URL¶

The RP may rely on the ID token that comes with an expiration date to expire the RP session. In case the user logs out of OP prior to token expiration, there should be a mechanism for user login status verification at the OP. For this, once the session is established with the authentication request and response the login status at the OP is verified by polling a hidden OP iframe from an RP iframe.
The OP iframe URL is the URL of the OP iframe that supports cross-origin communications for session state information with the RP, using the HTML5 postMessage API. The page is loaded from an invisible iframe that is embedded in an RP page enabling it to run the OP's security context. The OP iframe URL accepts postMessage requests from the relevant RP iframe and uses postMessage to post back the user login status at the OP.
The OP iframe URL can be discoverd using the check_session_iframe parameter in the OIDC Discovery response.

For more information on OIDC Discovery, see OpenID Connect Discovery.

The OP iframe URL is in the following format.

Format

https://<PRODUCT_HOST>:<PRODUCT_PORT>/oidc/checksession

Example

https://localhost:9443/oidc/checksession

The RP should request the page from the OP iframe URL with the following query parameter.

Query Parameter	Applicability	Description
client_id	Mandatory	This is the `client key` of the RP that is configured in WSO2 Identity Server. Tip To learn the step at which the `client key` is generated when configuring the RP in WSO2 Identity Server, see step 2.g under Configurations .

How it works¶

OIDC session management works with two hidden iframes, one at the RP and the other at identity provider. The RP checks the session state by using the RP iframe to continuously poll a hidden identity provider iframe, without causing network traffic. Thereby, the RP is notified when the session state of the end user has changed. The flow of this is as follows.

The RP iframe polls the identity provider iframe for a session status.
The identity provider iframe sends back a post message about the session state as changed, unchanged or error .
If the session state is changed, the RP sends a passive request for re-authentication.
If the end user has logged out from the identity provider, the RP will receive an authentication failure message along with a new session state value. The RP handles this as an end user logout.
If the end user has not logged out, the RP will receive a successful authentication response along with a new session state value.

Configurations¶

You can configure an RP for OIDC session management in WSO2 Identity Server with either of the following methods:

OpenID Connect Dynamic Client Registration
Manual configuration through WSO2 Identity Server Management Console

Manual configuration through WSO2 Identity Server Management Console

Follow the steps below to configure an RP for OIDC session management in WSO2 Identity Server Management Console:

Sign in to the WSO2 Identity Server Management Console.

To register a web application as a service provider:

On the Main menu, click Identity > Service Providers > Add.
Enter the name of the application in the Service Provider Name text box.
Click Register. Note that you will be redirected to the Service Providers screen.

To sign the ID token with the user's tenant domain, in the Local & Outbound Authentication Configuration section, select Use tenant domain in local subject identifier check box. !!! note Alternative method to sign the ID token

    Open the `             deployment.toml           ` file in the
    `             <IS_HOME>/conf/repository/conf           `
    directory and add the following property.

    ``` java
    [authentication]
    sign_auth_response_with_tenant_of= "sp"
    ```

use-tenant-domain

In the Inbound Authentication Configuration section, click OAuth/OpenID Connect Configuration > Configure.

Enter the callback URL as given below.
oauth-callback-url

Field Description

Callback URL

This is the service provider's URL to which the authorization codes are sent. Upon a successful authentication, the browser should be redirected to this URL.

Configure multiple callback URLs

From IS 5.2.0 onwards, regex-based consumer URLs are supported when defining the callback URL. This enables you to configure multiple callback URLs for one application by entering a regex pattern as the value for the callback URL field.
For example, if you have two service providers that use the same application, you can now define a regex pattern which will work for both callback URLs instead of having to configure two different applications for the two service providers. Assume the two callback URLs for your two service providers are as follows:

https://myapp.com/callback
https://testapp:8000/callback

To configure the callback URL to work for both of these URLs, set it using a regex pattern as follows:

regexp=(https://((myapp.com)|(testapp:8000))(/callback))

Note

You must have the prefix ' regexp= ' before your regex pattern. To define a normal URL, you can specify the callback URL without this prefix.

You can also configure a regex pattern that contains dynamic values as seen below.

regexp=https://mchcon.clance.local\?id=(.*)

Click Add. Note that a client ID and client secret have been created.

You have successfully added the service provider. Similarly, register another service provider to test single logout.

To view the identity provider's logout endpoint URL, which gets called when the logout is triggered from the service provider:
1. On the Main menu, click Identity > Identity Providers > Resident.
2. Under Inbound Authentication Configuration, click OAuth2/OpenID Connect Configuration.
  
  Note that the identity provider's logout endpoint URL is listed out.

OIDC Back-Channel Logout¶

OIDC back-channel logout feature utilizes back-channel communication to log out users from a client application by directly communicating the logout requests between the client application and authorization server.

What is back-channel communication?

Back-channel communication enables communication between two or more unobservable parties.
In this method, the request messages are communicated between the servers via direct network links between the servers.
This method also enables the client application to communicate with the identity provider and resource server without user involvement as well as the identity provider to communicate with the resources server without the client application's involvement.

What is direct communication?

Direct communication enables communicating the requests between the client application and authorization server through direct network links without having to rely on a browser.

This approach is more reliable as it does not require communicating the logout requests through a user agent and maintain active RP browser sessions for the communication to succeed. Instead, when a user triggers a logout request, all the RPs belonging to the same browser session will be sent a logout token from the identity provider to initiate logouts at the RPs.

Endpoint discovery¶

To enable OIDC back-channel logout, the RP needs to obtain the OP's logout endpoint URL.

OP logout endpoint URL¶

When a user is logged out from the RP, the RP redirects to the OP's logout endpoint URL to log out the user at the OP.
The logout endpoint URL can be discovered using the end_session_endpoint parameter in the OIDC Discovery response.

For more information on OIDC Discovery, see OpenID Connect Discovery.

The logout endpoint URL is in the following format.

Format

https://<PRODUCT_HOST>:<PRODUCT_PORT>/oidc/logout

Example

https://localhost:9443/oidc/logout

The logout request sent by the RP to OP includes the following query parameters.

Query Parameter Applicability Description

id_token_hint

Recommended

This is the previously-issued ID token that was passed to the logout endpoint hinting about the user's current authentication session with the RP. This indicates the identity of the user that the RP is requesting to be logged out by the OP.

If the id_token_hint is passed to the logout endpoint, WSO2 Identity Server identifies the RP to which the token is issued to and the user's session that the RP participated in using the sid in the ID token and redirects the user to the callback URL of the RP that is configured in WSO2 Identity Server. To learn how to configure the RP in WSO2 Identity Server, see Configurations .

If the id_token_hint is not passed to the logout endpoint, the user is redirected to the default logout page subsequent to a successful logout.

When WSO2 Identity Server receives a logout request from the RP, WSO2 Identity Server identifies all other RPs that participated in the same session and triggers back-channel logout requests for them where those RPs are registered in WSO2 Identity Server with a back-channel logout URL.

post_logout_redirect_uri

Optional

This is the URL to which the RP requests the end user's user agent be redirected after a logout.

Note

The post_logout_redirect_uri should be registered in WSO2 Identity Server based on the regex option provided for configuring multiple callback URLs.

To learn how to configure the RP with multiple callback URLs in WSO2 Server, see Configurations .

state

Optional

This is an opaque valued that is used by the RP for maintaining the state between the logout request and the callback to the endpoint that is specified in the post_logout_redirect query parameter.

If the state is included in the logout request, WSO2 Identity Server passes this value back to the RP in the state query parameter when redirecting the user agent back to the RP.

How it works¶

Let's take a look at the underlying message flow of the OIDC back-channel logout.

RP registers a logout endpoint at the OP.
The session ID, which identifies the application session at the OP is injected to the ID token.

What is an ID token?

It is a JSON Web Token (JWT) containing the user's authentication status and profile information in the form of claims.
The RP triggers a user logout.
The OP identifies the session of the respective RP and obtains the session ID, which corresponds to the browser session.
The OP identifies all the client applications that share the same user session using the session ID.

The authorization server generates a logout token and sends it with the logout request to the logout endpoints of the client applications via back-channel.

What is a logout token?

Logout token is a special JWT is a type of security event token similar to ID token. It contains the following claims that are specific to the logout action and are required by the RPs to validate and verify the logout request and trigger the logout process for a user:

Claim	Definition	Description
iss	Issuer Identifier	This identifies the OP. To learn how WSO2 Identity Server manages identity providers, see Configuring a resident identity provider .
sub	Subject Identifier	This is a unique identifier that is assigned by the OP to the Client, which is the `client key` . Tip To learn the step at which the `client key` is generated when configuring the RP in WSO2 Identity Server, see step 2.f under Configurations .
aud	Audience	This is the list of clients to which the logout token is intended for.
iat	Issued At Time	This is the time at which the token was issued.
jti	JWT ID	This uniquely identifies the token and is used to prevent logout token replays.
events		This is the JSON object containing the member name `http://schemas.openid.net/event/backchannel-logout` . This should be an empty JSON object. This is to declare that this JWT is a logout token.
sid	Session ID	This identifies the session of the user agent at the RP.

Sample logout token

{
"sub": "admin",
"aud": "Fv7m40gUl7WT430oLUkOlCdr6X8a",
"iss": "https://localhost:9443/oauth2/token",
"event": {
"http://schemas.openid.net/event/backchannel-logout": {}
},
"exp": 1556562242,
"iat": 1556562122,
"jti": "ec68f2b2-01ce-4d51-94b1-9d178eaa5f7d",
"sid": "6cb64c02-ab2a-466c-a8fb-04107a165691"
}

Upon receiving the logout token, the client application validates the logout token and invalidates the user session causing the session to logout.

Configurations¶

You can configure an RP for OIDC back-channel logout in WSO2 Identity Server with either of the following methods:

OpenID Connect Dynamic Client Registration
Note

If you are configuring the RP for OIDC back-channel logout in WSO2 Identity Server through dynamic client registration, make sure you add the following parameters to the request:
- backchannel_logout_uri : This is the logoout URL.
- backchannel_logout_session_required : Set this to true .
Sample request
```
{
"redirect_uris": ["server.example.com"],
"client_name": "application_1",
"ext_param_owner": "application_owner",
"grant_types": ["password"],
"backchannel_logout_uri": "http://localhost:8080/pickup/bclogout",
"backchannel_logout_session_required": true
}
```
Manual configuration through WSO2 Identity Server Management Console

Manual configuration through WSO2 Identity Server Management Console

Follow the steps below to configure an RP for OIDC back-channel logout in WSO2 Identity Server:

Sign in to the WSO2 Identity Server Management Console.

To register a web application as a service provider:

On the Main menu, click Identity > Service Providers > Add.
Enter the name of the application in the Service Provider Name text box.
Click Register. Note that you will be redirected to the Service Providers screen.
In the Inbound Authentication Configuration section, click OAuth/OpenID Connect Configuration > Configure.

Enter the configurations as follows:
oidc-single-logout-configs

Field	Description
Callback URL	This is the service provider's URL to which the `authorization codes` are sent. Upon a successful authentication, the browser should be redirected to this URL.
Enable OIDC Backchannel Logout	This defines whether the back-channel communication is used to communicate the `logout token` or not.
Logout URL	This is the service provider's back-channel logout endpoint URL to which the `logout token` is sent to.

Click Add. Note that a client ID and client secret have been created.

You have successfully added the service provider. Similarly, register another service provider to test single logout.

To view the identity provider's logout endpoint URL, which gets called when the logout is triggered from the service provider:
1. On the Main menu, click Identity > Identity Providers > Resident.
2. Under Inbound Authentication Configuration, click OAuth2/OpenID Connect Configuration.
  
  Note that the identity provider's logout endpoint URL is listed out.

OIDC Front-Channel Logout¶

Note

OIDC front-channel logout mechanism is already added to the WSO2 Identity Server roadmap and will be available in a future WSO2 Identity Server version.

Top