PingOne Advanced Identity Cloud

Backchannel logout

OpenID Connect Back-Channel Logout 1.0 defines how an OpenID provider (OP) sends logout tokens to relying parties (RPs) when an end user session terminates.

With backchannel logout, the OP communicates directly to the RP, bypassing the end user’s browser. This mechanism fits when multiple RPs get ID tokens with the same end user session and when the end user is no longer at the RP. For each RP, the OP posts a logout token to the RP’s backchannel logout URL. The RP validates the logout token, clearing any state associated with the session, end user, and issuer, and responds to the OP with the outcome.

For each logout request, PingOne Advanced Identity Cloud records an AM-BACK-CHANNEL-LOGOUT audit event message in the am-activity logs:

{
  "...": "...",
  "eventName": "AM-BACK-CHANNEL-LOGOUT",
  "operation": "Sent logout request to https://rp.example.com/logout, which responded with HTTP code 200."
}

If the RP responds, the message indicates the HTTP status code from the response. If the request times out, the message indicates there was no response.

Backchannel logout flow
Figure 1. Backchannel logout flow

Limitations

Backchannel logout has the following limitations:

  • It requires server-side sessions.

  • PingOne Advanced Identity Cloud must be acting as the OP; it does not support backchannel logout when acting as an RP.

The logout token

2.4 Logout Token defines the format as a JSON Web Token (JWT) with standard claims:

{
  "aud": "backchannelConfidentialClient", (1)
  "sub": "a0325ea4-9d9b-4056-931b-ab64704cc3da", (2)
  "auditTrackingId": "cb52bc45-549d-4a9c-86cc-20d7500e333b-91288", (3)
  "iss": "https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha", (4)
  "cause": "CLIENT_LOGOUT", (5)
  "iat": 1677065743, (6)
  "jti": "1cd8805d-6fc0-4699-a33f-a75d45b24e9e", (7)
  "events": { (8)
    "http://schemas.openid.net/event/backchannel-logout": {}
  },
  "sid": "mTNo042FCiPkgAJKjdjgCvBWvVYTB1d+zreDBnZAqvM=" (9)
}
1 The audience of the logout token; the RP having requested one or more ID tokens with the terminated user session.
2 The subject of the logout token; the end user whose session terminated. The logout token subject claim matches the ID token subject claim(s).
3 (Non-standard) The unique audit identifier for this token.
4 The OP issuing the logout token.
5 (Non-standard) Why the user session terminated, included only if the reason is known:
CLIENT_LOGOUT

The OP received a logout request.

SESSION_IDLE_TIMEOUT

The session reached its maximum idle time.

SESSION_MAX_TIMEOUT

The session reached its maximum time-to-live.

SESSION_TERMINATION

An administrator terminated the session.
6 The logout token creation time.
7 The logout token’s unique identifier.
8 A JSON object with a http://schemas.openid.net/event/backchannel-logout field, marking the JWT as a logout token. The value of the field is always an empty JSON object ({}).
9 A session ID identifying the end user’s session and the RP. The sid in the logout token matches the sid in the related ID token. The RP can use this for cleanup. If one RP has multiple ID tokens issued with the same end user session, they all share the same sid. If multiple RPs have ID tokens issued with the same end user session, the sid is different for each RP. When a session terminates, PingOne Advanced Identity Cloud posts a logout token to each RP. The logout token includes the claim when Backchannel Logout Session Required is enabled in the RP client profile. ID tokens include the sid when backchannel logout is enabled for the realm (default).

Enable backchannel logout

You configure backchannel logout in the OAuth 2.0 provider service for the realm and in the client profile of each RP.

Provider configuration

By default, the OAuth 2.0 provider supports backchannel logout without additional configuration.

You can optionally configure ID token encryption.

To disable backchannel logout support for a realm:

  1. Under Native Consoles > Access Management, go to Realms > Realm Name > Services > OAuth2 Provider > Advanced OpenID Connect.

  2. Clear Enable Session Management.

  3. Save your changes.

This also disables <iframe>-based session management.

RP configuration

RPs registering dynamically can provide the following settings during registration. To enable backchannel logout in an RP client profile manually:

  1. Under Native Consoles > Access Management, go to Realms > Realm Name > Applications > OAuth 2.0 > Clients > Client ID > OpenID Connect.

  2. In the Back Channel Logout URI field, add the RP’s logout URL.

    The logout URL can use an HTTP or HTTPS scheme, and may contain a port, a path, or query parameters; for example, https://rp.example.com:8443/logout.

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

  4. Save your changes.