OIDC Back-Channel Logout

The Back-Channel Logout implements OpenID Connect Back-Channel Logout 1.0 and can be used to notify applications about session termination at the OpenID Provider. This guide will explain how back-channel logout is implemented inside ZITADEL and gives some usage examples.

In this guide we assume your already familiar with getting and validation token. You should already have a good understanding on the following topics before starting with this guide:

• Integrate your app with the OIDC flow to obtain tokens
• Claims
• Scope
• Audience

Concept

ZITADEL provides the possibility for OpenID Connect clients to be notified about the session termination, for example if a user signs out from another application using the same SSO session. This allows the application to also invalidate the user's session without the need for an active browser session.

1. When an unauthenticated user visits your application,
2. it will create an authorization request to the authorization endpoint.
3. The Authorization Server (ZITADEL) will send an HTTP 302 to the user's browser, which will redirect them to the login UI.
4. The user will have to authenticate using the demanded auth mechanics.
5. Your application will be called on the registered callback path (redirect_uri) for the authorization code exchange. See OIDC Flow for more details. On successful exchange, an SSO session will be created.
6. If the user opens another application,
7. the application will also create an authorization request to the authorization endpoint.
8. ZITADEL can then reuse the existing SSO session and will not ask the user to authenticate again and directly return the code for exchange. See OIDC Flow again for details.
9. At a later point, the user signs out from one of the applications, in this case the second one.
10. The application will redirect the user to the end_session endpoint.
11. ZITADEL will terminate the SSO session and redirect the user back to the application's post_logout_redirect_uri. The application can delete the local session.
12. ZITADEL will also send a back-channel logout request to every registered application with previously opened sessions. The application can then invalidate the user's session without the need for an active browser session.

Indicating Support

As required by the specification, ZITADEL will advertise the backchannel_logout_supported and backchannel_logout_session_supported on the discovery endpoint by default. The latter boolean indicates, that ZITADEL will provide a session ID (sid) claim as part of the logout token. This provides the possibility to match the exact SSO session, which was terminated.

Client

To enable the back-channel logout on an application, they simply need to register a backchannel_logout_uri as part of their settings, e.g. creating an OIDC application.

As soon as the URI is set, every new authorization request will register a back-channel notification to be sent once the session is terminated by a user sign out.

Back-Channel Request

When the session is terminated, ZITADEL will send back-channel logout requests asynchronously to every registered application of the corresponding session. The request is an application/x-www-form-urlencoded POST request to the registered URI including a logout_token parameter in the body.

Please be aware that body may contain other values in addition to logout_token. Values that are not understood by the implementation must be ignored.

Logout Token

The logout_token sent in the request is a JWT similar to an ID Token.

The following Claims are used within the Logout Token:

Validation

Verify the Logout Token the same way you verify an ID Token including signature validation, issuer, audience, expiration and issued at time claim checks. Make sure that either a subject (sub) and / or a session ID (sid) is present in the token to identify the user or its session. Also, check that the events claim contains the http://schemas.openid.net/event/backchannel-logout value. Optionally, you can also verify that the TokenID (jti) has not been used before.

For details on how to validate the logout token, please refer to the OpenID Connect Back-Channel Logout specification.

Example

This example assumes that your application is registered with client_id 243864426485212395@example and the back-channel logout URI is set to https://example.com/logout.

Authentication

When the user signed in to your application, ZITADEL issued the following id_token:

eyJhbGciOiJSUzI1NiIsImtpZCI6IjI5NjkzMzA1NjAxNzY0Nzg3NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAiLCJzdWIiOiIxNjQ4NDk0OTQyOTc0NzczNzciLCJhdWQiOlsiMjQzODY0NDI2NDg1MjEyMzk1QGV4YW1wbGUiLCIyNDM4NjQzODExNjk4ODY0NDMiXSwiZXhwIjoxNzMzNzgyNDQ0LCJpYXQiOjE3MzM3MzkyNDQsImF1dGhfdGltZSI6MTczMzczOTI0NCwiYW1yIjpbInVzZXIiLCJtZmEiXSwiYXpwIjoiMjQzODY0NDI2NDg1MjEyMzk1QGV4YW1wbGUiLCJjbGllbnRfaWQiOiIyNDM4NjQ0MjY0ODUyMTIzOTVAZXhhbXBsZSIsImF0X2hhc2giOiJSWVFPSkJuT01LS0hrN1VnLWY1eFJnIiwic2lkIjoiVjFfMjk3MzY0ODE4OTgwMDM0MDA0In0K.lZxHE_Z4tiaDQE-DPtYjnvb0H9rz4wMoGfBMeEm4EG837DGJb7RTq7PuMHWc4Z2e_6lilwfVBWDEOhmrnjmkQwDVxInbbJfN0NiWgeqoW-C1SZ_G00UVIbJdaxPy2-haRihDNNpy0Gjmi7q3FkGXGqkJx9S7ZtC5ISbXLnqfbRbuapoMs7hHNf-Iltf8v7dMs3K8dcAPSHJm0X0x6Cu1ZMeAS2a6H05xKXGM0bRK830AZlL8xmxTNj_q_WZKzxz304XrRNHvYRcHKmJqURSHvRNUR38QeNaiKzINlV2sVvPEY6Dru_PHSPNFu7YLWiUi34VUla6VTxy9ctI_BtI4nw

This represents the following claims:

{
  "iss": "http://localhost:8080",
  "sub": "164849494297477377",
  "aud": [
    "243864426485212395@example",
    "243864381169886443"
  ],
  "exp": 1733782444,
  "iat": 1733739244,
  "auth_time": 1733739244,
  "amr": [
    "user",
    "mfa"
  ],
  "azp": "243864426485212395@example",
  "client_id": "243864426485212395@example",
  "at_hash": "RYQOJBnOMKKHk7Ug-f5xRg",
  "sid": "V1_297364818980034004"
}

As you can see, the sid claim is present in the token. This represents the application's specific session ID of the user session.

Sign Out and Back-Channel Logout

When the user signs out from another application, ZITADEL will send a POST request to https://example.com/logout with the following body:

POST /logout HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded

logout_token=eyJhbGciOiJSUzI1NiIsImtpZCI6IjI5NjkzMzA1NjAxNzY0Nzg3NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAiLCJzdWIiOiIxNjQ4NDk0OTQyOTc0NzczNzciLCJhdWQiOlsiMjQzODY0NDI2NDg1MjEyMzk1QGV4YW1wbGUiXSwiaWF0IjoxNzMzNzM5MjUyLCJleHAiOjE3MzM3NDAxNTMsImp0aSI6IjI5NzM2NDgzNDQ5ODkyMTEzNyIsImV2ZW50cyI6eyJodHRwOi8vc2NoZW1hcy5vcGVuaWQubmV0L2V2ZW50L2JhY2tjaGFubmVsLWxvZ291dCI6e319LCJzaWQiOiJWMV8yOTczNjQ4MTg5ODAwMzQwMDQifQo.ELOPuS61fy8GgCKEtru5df4-9GI4-KQlNf_DMp6b5mtJZIrfykA_M7lYOxOskYhTDicBoQ2jjOjzsDqktI4r6ptD068c5LEOx-k2OVk7ybADsK7tht5omYy4tsbHmkDCZN065WMH0SQH7NKGroVW-MACi6Peuiz3nlQsfho0EnLECqhZT60qxu6qtofvBVhHe15Zlkzffy0vxjKEIeJoTmX_cNVsHlrC_n1vTqZStBrkqu3_rwZxZuynX47vf7_kj_kKhJ3TffRF561n1AP5xnhZ9i--rnaucbGtGGImlKi2sdqC4GzjtdlaKJaRuVF-91x758SLBxqJXPucroJoWw

{
  "iss": "http://localhost:8080",
  "sub": "164849494297477377",
  "aud": [
    "243864426485212395@example"
  ],
  "iat": 1733739252,
  "exp": 1733740153,
  "jti": "297364834498921137",
  "events": {
    "http://schemas.openid.net/event/backchannel-logout": {}
  },
  "sid": "V1_297364818980034004"
}

After validating the token, the application can now invalidate the user's local session based on the sid claim.

Some applications might also want to delete all user sessions. In this case, the sub claim can be used to identify the user.