Informing Relying Parties that a Session has Expired

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 back-channel 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 back-channel logout flow:

Back-Channel Logout Flow
Back-Channel Logout Flow

Back-Channel Logout Limitations

The current implementation of back-channel logout in AM has the following limitations:

  • It is only supported for CTS-based sessions.

  • AM currently only supports back-channel 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).

The subject claim is in the format (type!subject), where:

  • subject is the identifier of the user/identity, or the name of the OAuth 2.0/OpenID Connect client that is the subject of the token.

  • type can be one of the following:

    • age. Specifies that the subject is an OAuth 2.0/OpenID Connect-related user-agent or client. For example, an OAuth 2.0 client, a Remote Consent Service agent, and a Web and Java Agent internal client.

    • usr. Specifies that the subject is a user/identity.

For example, (usr!demo), or (age!myOAuth2Client).

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 "Enabling Back-Channel Logout".

Enabling Back-Channel Logout

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

  1. Configure the OAuth 2.0 provider:

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

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

      Note

      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.

    3. Save your changes.

    4. (Optional) 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.

    5. (Optional) 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 "Encrypting ID Tokens and Backchannel Logout Tokens".

  2. Configure the clients:

    1. In the AM console, go to Realms > Realm Name > Applications > OAuth 2.0 > Clients > Client Name > OpenID Connect.

    2. In the Back Channel Logout URI field, set the URL in the relying party to where AM will send the logout token during back-channel 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.

    3. (Optional) If the logout token must contain the session ID (sid), enable Backchannel Logout Session Required.

    4. Save your changes, and configure as many clients as required.

      Tip

      Clients registering dynamically can provide their back-channel logout configuration, too.

The Back-Channel Logout Postman Collection

ForgeRock provides a back-channel 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.

Back-channel 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 back-channel logout Postman collection:

  1. Download and install Postman.

  2. Download the ForgeRock OpenID Connect Back-Channel Logout Collection.

  3. Import the collection in Postman:

    1. Go to File > Import ... > Upload Files.

    2. Select the collection you downloaded, and click Open. Then, click Import.

  4. (Optional) 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.

  5. Configure the collection's variables to suit your environment:

    1. In Postman, on the Collections tab, select the ForgeRock OpenID Connect Back-Channel Logout Collection. Click on the ... button, and then on Edit.

      The Edit Collection page appears.

    2. 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 back-channel logout URL of your relying party, or the URL of the Postman mock server.

    3. 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 Back-Channel 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.

  6. Run the collection.

  7. (Optional) (Mock server only) On the mockup server window, check the request body of the Mock Up Response to see the logout token.

  8. Inspect the contents of the logout token.

    Tokens created by the collection are not encrypted.

  9. 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."
 ...
 }
Read a different version of :