> ## Documentation Index
> Fetch the complete documentation index at: https://auth0.com/llms.txt
> Use this file to discover all available pages before exploring further.

> Describes how to configure OIDC back-channel logout with your Auth0 services.

# Configure OIDC Back-Channel Logout

<Card title="Before you start">
  To use Back-Channel Logout, your application must meet the following requirements:

  * Your OIDC Back-Channel Logout URI endpoint must be exposed over the internet for your Auth0 tenant to access.
  * Production-ready applications must use TLS. To learn more, read [TLS (SSL) Versions and Ciphers](/docs/customize/custom-domains/self-managed-certificates/tls-ssl).
  * The application must be able to store the provided session identifier (`sid`) and associate it with the user sessions it creates. We recommend production applications use durable session storage.
  * The application must be able to retrieve an existing session by the `sid` during the logout process without using client-side cookies. Cookies exist within the browser and are inaccessible to the logout callback endpoint.
</Card>

## Availability

OIDC Back-Channel Logout is available for all Enterprise plan customers. You should check the OIDC standard `/.well-known/*` metadata endpoint to determine if your application meets the requirements.

```json lines theme={null}
GET https://acme.eu.auth0.com/.well-known/openid-configuration

HTTP 200
{ ..., "backchannel_logout_supported": true, 
  "backchannel_logout_session_supported": true }
```

## Back-Channel Logout restrictions

Back-Channel Logout URLs are called on publicly-exposed endpoints and must adhere to certain restrictions:

1. You must use the HTTPS protocols. Unencrypted HTTP or other protocols are not permitted.
2. You must not use Auth0 subdomains. Some Auth0 subdomains are:

   * auth0.com
   * auth0app.com
   * webtask.io
   * webtask.run
3. We do not recommend using IP addresses without domains. IP addresses must be public IPs to use Back-Channel Logout. IP addresses from internal, reserved, or loopback ranges are not permitted.

## Configure Auth0

Register your application to receive Logout Tokens via <Tooltip tip="Auth0 Dashboard: Auth0's main product to configure your services." cta="View Glossary" href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or <Tooltip tip="Auth0 Dashboard: Auth0's main product to configure your services." cta="View Glossary" href="/docs/glossary?term=Management+API">Management API</Tooltip>.

<Tabs>
  <Tab title="Auth0 Dashboard">
    #### Subscribe applications

    1. Navigate to [**Auth0 Dashboard > Applications**](https://manage.auth0.com/#/applications).
    2. Choose the application you want to register.
    3. Select the **Settings** tab.
    4. Under the **OpenID Connect Back-Channel Logout > Back-Channel Logout URI**, add the application logout URI that will receive the logout\_tokens
    5. Once complete, select **Save Changes**.

           <Frame>
             <img src="https://mintlify.s3.us-west-1.amazonaws.com/auth0/docs/images/cdy7uua7fh8z/19uQRkVswdmaO8gHTVTXCc/0564bfeda05bc7df90af9e8ee852047f/Screenshot_2024-11-05_at_13.31.54.png" alt="Auth0 Dashboard > Applications > Settings" />
           </Frame>

    #### Unsubscribe applications

    Unsubscribing your application stops the service from tracking new logins and sending logout events. The service discards pending logout events once your application is unsubscribed.

    To unsubscribe your application, delete the back-channel logout URL.

    1. Navigate to [Auth0 Dashboard > Applications](http://manage.auth0.com/#/applications).
    2. Choose the application you want to register.
    3. Select the **Settings** tab.
    4. Under the **OpenID Connect Back-Channel Logout > Back-Channel Logout URI**
    5. Remove the back-channel URL.
    6. Once complete, select **Save Changes**.

           <Frame>
             <img src="https://mintlify.s3.us-west-1.amazonaws.com/auth0/docs/images/cdy7uua7fh8z/5SlrBhwrNbJx0Wdw2kQ19t/9b69eb926e44c35b426daa76a851a5db/Screenshot_2024-11-05_at_13.31.54.png" alt="Auth0 Dashboard > Applications > Settings" />
           </Frame>

    For auditing purposes, the service always logs subscribing or unsubscribing back-channel logout URLs as `API Operation Event` in Auth0 tenant logs. To learn more, read [Logs](/docs/deploy-monitor/logs).
  </Tab>

  <Tab title="Management API">
    #### Subscribe application

    Add the `oidc_logout` property to `PATCH` a client through the Management API:

    ```bash cURL lines theme={null}
    PATCH /api/v2/clients/{id}
    "oidc_logout": {
      "backchannel_logout_urls": ["http://acme.eu.auth0.com/events"]
    }
    ```

    <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
      The request can include the other application parameters.
    </Callout>

    #### Unsubscribe application

    Remove the `oidc_logout` parameter:

    ```bash cURL lines theme={null}
    PATCH https://acme.eu.auth0.com/api/v2/clients/{id}
    {
      "oidc_logout": {
        "backchannel_logout_urls": []
      }
    }
    ```
  </Tab>
</Tabs>

## Configure your application

Once you have configured Back-Channel Logout via the Auth0 Dashboard or Management API, configure your application to use the service based on the technology or framework.

1. Implement end-user authentication according to your application type.

   1. End-users should be able to log in to the application, and a session should be created.
   2. An ID token should be issued from Auth0 and should be accessible in the application backend for further processing.
2. Extend the login process to save the `sid` and, optionally, sub claims after the ID token is validated.

   1. These claims must be saved against the current application session.
   2. The session management functions should be able to retrieve a specific session by the `sid` value.
3. Configure the Back-Channel Logout endpoint:

   1. The endpoint must process only `HTTP POST` requests.
   2. Extract the `logout_token` parameter and validate it as a regular JWT according to the spec.
   3. Verify that the token contains an events claim with a JSON object value and a member named `http://schemas.openid.net/event/backchannel-logout`.
   4. Verify that the token contains the `sid` and/or `sub` claims.
   5. Verify that the token does NOT contain the `nonce` claim. This is required to prevent abuse by distinguishing the Logout Token from the ID token.
   6. Once the token is validated, retrieve the session corresponding to the received `sid` and/or `sub` value and terminate it. The exact application session termination process depends on the implementation details. For example, this event may need to be communicated to the front-end.

## OIDC Back-Channel Logout request example

Coded token payload:

```bash cURL lines theme={null}
POST /backchannel-logout HTTP/1.1
Host: rp.example.org
Content-Type: application/x-www-form-urlencoded

logout_token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImdwY3ZFT0FPREE2T3pXRmw3ODVxbCJ9.eyJpc3MiOiJodHRwczovL2FydGV4LWRldi5ldS5hdXRoMC5jb20vIiwic3ViIjoiYXV0aDB8NjAyZTkzZGI4M2ZhNmYwMDc0OWEyM2U2IiwiYXVkIjoiVHVoTkx2N3VsWEQzUmZ5TGxTTWJPdnN6endKSkZQcE8iLCJpYXQiOjE2OTgxNjA5MjgsImV4cCI6MTY5ODE2MTA0OCwianRpIjoiNDRhOTEyMTUtZGZiNC00ZGZlLWExZWItZmNhZmE5MTFkZWJhIiwiZXZlbnRzIjp7Imh0dHA6Ly9zY2hlbWFzLm9wZW5pZC5uZXQvZXZlbnQvYmFja2NoYW5uZWwtbG9nb3V0Ijp7fX0sInRyYWNlX2lkIjoiODFiMzM2YTk0YTRhNTcwNyIsInNpZCI6IjM3NVVJcF9JRDVtQ1RDbEllQkVIcFhmR3dxNTF0Rl9MIn0.aEoAL_U-EPlf3f7Fup-bu7Yv0S0GOnrkL8Njd6j6UNqZcr5VrWWFf3CWvkRi7Cm6wMgU2qIMhb7643ca8-ajR7zHlMu0Z3r-gfd2D1xudKLyUSC3v2D5WJZz5I8xMZ_LWtIN2W3l4SQFO9MgK_7F3x0WIWXo9KPC9tgOaOLPnsiv__MutM1ZakoCsJPddl5gVM4TYtHOue6WM7SOXZNa3SSiv57YQOX2KNCL7sWmZp_J1OXKy8lsgkNFqiOVwu39p4sgjKYEXQU0G-I0yY_aeNbnlnxFG6OuxaDt_zwg6AvKglLSNGqrrvzy4GsYJi5HMGZ1GsSs7rQLg7Iuu6JM-A
```

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  Token expiration is 2 minutes (120 sec).
</Callout>

Decoded token payload:

```json JSON lines theme={null}
{
   "iss": "https://artex-dev.eu.auth0.com/",
   "sub": "auth0|602e93db83fa6f00749a23e6",
   "aud": "TuhNLv7ulXD3RfyLlSMbOvszzwJJFPpO",
   "iat": 1698160928,
   "exp": 1698161048,
   "jti": "44a91215-dfb4-4dfe-a1eb-fcafa911deba",
   "events": {
         "http://schemas.openid.net/event/backchannel-logout": {}
   },
   "trace_id": "81b336a94a4a5707",
   "sid": "375UIp_ID5mCTClIeBEHpXfGwq51tF_L"
}
```

## Expected responses

* **HTTP 200**:  Confirms user logout from the specific application.
* **HTTP 400**: Indicates an incorrect request. The request is not understood or the token failed validation. Auth0 records the problem in tenant logs but does not attempt further requests for this specific session.

## Troubleshoot issues

### Application did not receive the logout events

If your application did not receive a logout request after a logout event.

1. Make sure your application has a Back-Channel Logout URL registered in Auth0 Dashboard.
2. Ensure the Back-Channel Logout URL is reachable from the Auth0 tenant.
3. Ensure a valid session is established. The end-user must log in to your specific application via Auth0.

   <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
     Applications receive logout events only if end-users log in to that specific app with Auth0.  If the end-user logs in to other applications, logout events do not trigger.
   </Callout>
4. Check Auth0 tenant logs for messages about unsuccessful logout message delivery.
5. Make sure the logout is triggered via the standard logout endpoint. Other events do not trigger the logout events.
6. If possible, check for blocked requests on the web server and/or application firewall logs.

#### I can't find OIDC Back-Channel Logout tenant logs

This feature will be gradually released to all tenants starting 3 October 2023. You may still receive [tenant log event codes](/docs/deploy-monitor/logs/log-event-type-codes) `sslo` for `oidc_backchannel_logout_succeeded` or `fslo` for `oidc_backchannel_logout_failed`.

### Client app cannot verify the received Logout Token

If the transaction still fails with a 400 error:

1. Check if the token is a standard base64-encoded JWT. Some web servers may truncate long parameters. To learn more, read [Signing Algorithms](/docs/get-started/applications/signing-algorithms).
2. If possible, capture a token and verify that it’s a JWT. Use a verified source, like [JWT.IO](http://jwt.io).
3. Make sure the verification function fetches the tenant signing key dynamically via [JSON Web Key Sets](/docs/secure/tokens/json-web-tokens/json-web-key-sets) (JWKS).

   <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
     We do not recommend hardcoding a static key. If your configuration requires the static key to be hardcoded, ensure the configuration contains the latest public key from the Auth0 tenant.
   </Callout>

### Response Timeout Errors

Auth0 will wait five seconds for the application OIDC Back-Channel Logout URL to respond. After this time, it will record a "Failed OIDC Back-Channel Logout request" in the tenant logs with an empty response description.

## Learn more

* [Log Users Out of Auth0 with OIDC Endpoint](/docs/authenticate/login/logout/log-users-out-of-auth0)
* [Log Users Out of Applications](/docs/authenticate/login/logout/log-users-out-of-applications)
* [Log Users Out of Identity Providers](/docs/authenticate/login/logout/log-users-out-of-idps)