Backchannel logout

OpenID Connect Back-Channel Logout 1.0 Draft 06 defines how a provider can send a logout token to the relevant relying parties when an end user session linked to an ID token becomes invalid.

When backchannel logout is enabled, AM sends a logout token to a URL configured in the relying party’s client profile. This URL must be a page or application in the relying party that is capable of dealing with the token.

AM stores a list of logged in clients in the end user’s session so that, when it becomes invalid, AM has a list of URLs to which it needs to send the logout token to.

This is particularly important in scenarios where different relying parties use the same user session to obtain ID tokens. By storing the URLs in the session itself, AM ensures that all the related relying parties receive a logout token.

Next, the relying party validates the logout token, and clears any state associated with the combination of session ID, user, and issuer. Finally, it sends a response to AM with the outcome of the logout, as explained in 2.8 Back-Channel Logout Response of the draft.

Depending on which status code AM receives, it logs an audit event of the type AM-BACK-CHANNEL-LOGOUT in the activity log file, which resembles the following:

{
  "_id":"cb52bc45-549d-4a9c-86cc-20d7500e333b-96127",
  "eventName":"AM-BACK-CHANNEL-LOGOUT",
  "transactionId":"cb52bc45-549d-4a9c-86cc-20d7500e333b-94750",
  ...
  ...
  "operation":"Sent logout request to https://rp.example.com:8443/logout, which responded with HTTP code 200.",
  ...
}

AM will log the HTTP code that the relying party returns, or an error if there is no response before the request times out.

The following simplified diagram illustrates a possible backchannel logout flow:

Figure 1. Backchannel Logout Flow

Backchannel logout limitations

The current implementation of backchannel logout in AM has the following limitations:

It is only supported for server-side sessions.
AM currently only supports backchannel logout when acting as the provider.

The logout token

The logout token is defined in section 2.4 Logout Token of the draft. The following is an example logout token issued by AM, and the description of its claims:

{
  "aud": "backchannelConfidentialClient", (1)
  "sub": "(usr!ForgerockDemo)", (2)
  "auditTrackingId": "cb52bc45-549d-4a9c-86cc-20d7500e333b-91288", (3)
  "iss": "https://openam.example.com:8443/openam/oauth2/backchannelSubRealm", (4)
  "cause": "CLIENT_LOGOUT", (5)
  "iat": 1614005410, (6)
  "jti": "1cd8805d-6fc0-4699-a33f-a75d45b24e9e", (7)
  "events": { (8)
    "http://schemas.openid.net/event/backchannel-logout": {}
  },
  "sid": "mTNo042FCiPkgAJKjdjgCvBWvVYTB1d+zreDBnZAqvM=" (9)
}

1	Specifies the audience of the logout token. In this case, the client that requested the ID token(s) related to the user that has been logged out.
2	Specifies the subject of the logout token. In this case, the user that has been logged out. The subject of the logout token matches the subject of the ID token(s).
3	(AM-specific) Determines the unique audit identifier for this token.
4	Specifies the authorization server that issued the logout token.
5	(AM-specific) Documents the reason why the user was logged out, if known. Possible values are: CLIENT_LOGOUT. AM has received a call to the sessions endpoint to end the session. SESSION_TERMINATION. An administrative user has terminated the session. SESSION_MAX_TIMEOUT. AM terminated the session because it reached its maximum time-to-live. SESSION_IDLE_TIMEOUT. AM terminated the session because it reached its maximum idle time. If the reason is not known, the claim does not show in the token.
6	Specifies the creation time of the logout token.
7	Specifies the unique identifier for the logout token.
8	Specifies a JSON object that contains the `http://schemas.openid.net/event/backchannel-logout` URL, which marks the JWT as a logout token. The value of the object is always an empty JSON object (`{}`).
9	Specifies a session ID that identifies the relying party’s session with the provider. The `sid` in the logout token matches the `sid` in the related ID token, and therefore, the relying party can match both when doing session clean up operations. If a relying party requests several ID tokens using the same end user session, they will all share the same `sid`. However, if several relying parties use the same user session to obtain ID tokens, the `sid` in them will be different. When the end user’s session becomes invalid, AM will send logout tokens to all the relying parties involved. Note that the claim is only populated in the logout token if Backchannel Logout Session Required is enabled in the client profile. See Enable backchannel logout.

Enable backchannel logout

To enable backchannel logout, first configure the OAuth 2.0 provider for the realm, and next configure the clients that will use the feature:

Configure the OAuth 2.0 provider:

In the AM admin UI, go to Realms > Realm Name > Services > OAuth2 Provider > Advanced OpenID Connect.

Enable OIDC Session Management , if it is not already enabled.

OIDC Session Management is enabled by default, and it is also required for Session Management.

When enabled, AM will always add a sid to the ID tokens, regardless of whether clients have logout URLs configured in them or not.

Save your changes.
Review the logout token signing secret.

AM signs logout tokens with the same secret it uses to sign ID tokens. For more information, see Secret ID mappings for signing OpenID Connect tokens.
Configure AM to encrypt the logout tokens.

Encryption is disabled by default. To enable it, you must configure ID token encryption as well. For more information, see Encrypt ID tokens and backchannel logout tokens.

Configure the clients:
- In the AM admin UI, go to Realms > Realm Name > Applications > OAuth 2.0 > Clients > Client ID > OpenID Connect.
- In the Back Channel Logout URI field, set the URL in the relying party to where AM will send the logout token during backchannel logout.
  
  This URL can use the http or the https schemes, and may contain a port, a path, or query parameters, depending on the implementation of the relying party. For example, https://my-rp.example.com:8443/logout.
- If the logout token must contain the session ID (sid), enable Backchannel Logout Session Required.
- Save your changes, and configure as many clients as required.
  
  Clients registering dynamically can provide their backchannel logout configuration, too.

The backchannel logout Postman collection

ForgeRock provides a backchannel logout Postman collection to try out the functionality. The source for the REST calls, including the prerequisites needed to run the collection, is provided as a downloadable JSON file collection.

Backchannel logout relies on a relying party that can acknowledge the logout token and send a response back to AM. To emulate this, you can send a mock server in Postman.

Perform the following steps to download, configure, and run the backchannel logout Postman collection:

Download and install Postman.
Download the ForgeRock OpenID Connect backchannel logout collection.
Import the collection in Postman:
- Go to File > Import … > Upload Files.
- Select the collection you downloaded, and click Open. Then, click Import.
Create a Postman mock server.

Follow the instructions in the Setting Up Mock Servers in the Postman Documentation.

The mock server will work as the relying party. Inspect the requests sent to the mock server to see the logout tokens sent by AM.

When you create a mock server, Postman presents you with some information and the URL you can use to call it. For example, https://f4a08510-2f95-4990-8cb0-5a4f281a8bac.mock.pstmn.io.

Save this URL; you need to configure it in the following step of this procedure.
Configure the collection’s variables to suit your environment:
- In Postman, on the Collections tab, select the ForgeRock OpenID Connect Backchannel Logout Collection. From the more options menu (…), select Edit.
- Click on the Variables tab, and change at least the value of the following variables:
  - URL_base
    
    Configure the URL of your AM environment. For example, https://openam.example.com:8443/openam.
  - admin_password
    
    Configure the password of the administrative user, such as amAdmin, that the collection will use to create AM configuration objects.
  - back_channel_logout_uri
    
    Configure the backchannel logout URL of your relying party, or the URL of the Postman mock server.
- Click Update to save your changes.
  
  You are ready to start running the collection.
The collection is divided into the following folders:
- Prerequisites, containing REST calls to configure a new realm containing an authorization server, and to create the clients and users required to run the collection.
- OpenID Connect Backchannel Logout Flow, containing REST calls for the authorization code grant flow, and to log out the demo user.
- Mock Response, containing a REST call to send AM a response when using the mock server.
Run the collection.
(Mock server only) On the mockup server window, check the request body of the Mock Up Response to see the logout token.

Example Postman Mock Up Server Window with the Response Body Expanded
Inspect the contents of the logout token.

Tokens created by the collection are not encrypted.

Open the AM activity audit log.

Check for an entry with event name AM-BACK-CHANNEL-LOGOUT with the logout request, and the relying party’s response. For example:

{
 "_id":"cb52bc45-549d-4a9c-86cc-20d7500e333b-96127",
 "eventName":"AM-BACK-CHANNEL-LOGOUT",
 "transactionId":"cb52bc45-549d-4a9c-86cc-20d7500e333b-94750",
 ...
 ...
 "operation":"Sent logout request to https://f4a08510-2f95-4990-8cb0-5a4f281a8bac.mock.pstmn.io, which responded with HTTP code 200."
 ...
 }