OIDC Back-Channel Logout Initiators

Learn how OIDC Back-Channel Logout Initiators work and how to configure them for your application(s).

OIDC Back-Channel Logout Initiators allow you to remotely log out users from their applications based on session termination events. OIDC Back-Channel Logout Initiators work across protocols—for example, an identity provider-initiated (IdP-initiated) SAML logout request—and are unaffected by third-party cookie restrictions.

This feature is an extension to the standard OIDC back-channel specification. You can configure it to initiate an OIDC Back-Channel Logout request for specific session termination events, such as a password change or session expiration, or for all session termination events.

Administrators can enable this feature for specific applications with the Auth0 Management API.

How OIDC Back-Channel Logout Initiators work

Initiators bind an OIDC Back-Channel Logout response to a session termination event. They capture the event and use it to trigger an OIDC logout token in all applications associated with the given session.

Initiators do not control session management in your tenant, including session termination events.

The following diagram illustrates how an OIDC Back-Channel Logout Initiator works for a password change event:

Configure OIDC Back-Channel Logout Initiators

You can configure OIDC Back-Channel Logout Initiators with the Auth0 Management API.

Management API

You can configure the OIDC Back-Channel Logout Initiators for an application with the Management API by using the Update a Client endpoint.

1. Get an Management API access token with the update:clients scope.

2. Call the Update a Client endpoint with the appropriate configuration data in the payload. For example, to log out an application after a password change event, provide the following:

   JSON

   PATCH /api/v2/clients/{yourClientId}
   {
     ...
     "oidc_logout": {
       "backchannel_logout_urls": ["https://example.com/cb"]
       "backchannel_logout_initiators": {
         "mode":"custom",
         "selected_initiators": ["rp-logout", "idp-logout", "password-changed"]
       }
     }
     ...
   }
   

Properties

The backchannel_logout_initiators object supports the following properties:

Property	Type	Required?	Description	Supported values
mode	string	Required	Configuration method for enabling initiators.	custom, all
selected_initiators	array	Required if mode is custom	List of initiators to enable.	rp-logout, idp-logout, password-changed, session-expired, session-revoked, account-deleted, email-identifier-changed

mode property

The mode property determines the configuration method for enabling initiators.

By default, it is set to custom, which allows you to specify which initiators you want to enable. If you want your application to logout anytime the IdP session ends, set it to all.

The mode property supports the following values:

Value	Description
custom	Enables only the initiators listed in the selected_initiators array.
all	Automatically enables all current and future initiators.

selected_initiators property

The selected_initiators property contains the list of initiators to be enabled for the given application.

The selected_initiators property supports the following values:

Value	Description
rp-logout	Request was initiated by a relying party (RP).
idp-logout	Request was initiated by an external identity provider (IdP).
password-changed	Request was initiated by a password change.
session-expired	Request was initiated by session expiration.
session-revoked	Request was initiated by session deletion.
account-deleted	Request was initiated by an account deletion.
email-identifier-changed	Request was initiated by an email identifier change.

Examples

Subscribe an application to all current and future initiators

JSON

PATCH /api/v2/clients/{yourClientId}

{
  ...
  "oidc_logout": {
    "backchannel_logout_urls": ["https://example.com/cb"]
    "backchannel_logout_initiators": {
      "mode":"all"
    }
  }
  ...
}

Subscribe an application to password-changed initiator only (rp-logout and idp-logout are required)

JSON

PATCH /api/v2/clients/{yourClientId}

{
  ...
  "oidc_logout": {
    "backchannel_logout_urls": ["https://example.com/cb"]
    "backchannel_logout_initiators": {
      "mode":"custom",
      "selected_initiators": ["rp-logout", "idp-logout", "password-changed"]
    }
  }
  ...
}

Unsubscribe all initiators (rp-logout remains the default)

JSON

PATCH /api/v2/clients/{yourClientId}

{
  ...
  "oidc_logout": {
	  "backchannel_logout_urls": ["https://example.com/cb"]
  }
  ...
}

Dashboard

OpenID Connect Back-Channel Logout can be configured alongside the rest of your application settings. This feature automatically activates once a Back-Channel Logout URI is provided.

Selected initiators only

Only the required initiators (rp-logout and idp-logout) will be subscribed to by default. Any additional initiators, including any added in the future, must first be selected before they can initiate a logout from your application.

Select this option if you want your application to log out only for initiators you select.

All supported initiators

All supported initiators, including any added in the future, will be subscribed to by default.

Select this option if you want your application to log out any time the IdP session ends.