Backchannel Logout

AUTHORS

@@ -106,6 +106,7 @@ Peter McDonald
 Petr Dlouhý
 pySilver
 @realsuayip
+Raphael Lullis
 Rodney Richardson
 Rustem Saiargaliev
 Rustem Saiargaliev

CHANGELOG.md

@@ -17,6 +17,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 * #1637 Support for Django 6.0
+* #1545 Support for OIDC Back-Channel Logout
 
 ### Removed
 * #1636 Remove support for Python 3.8 and 3.9
@@ -31,6 +32,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Support for Python 3.14 (Django >= 5.2.8)
 * #1539 Add device authorization grant support
 
+<!--
+### Changed
+### Deprecated
+### Removed
+-->
 ### Fixed
 * #1252 Fix crash  when 'client' is in token request body
 * #1496 Fix error when Bearer token string is empty but preceded by `Bearer` keyword.

docs/oidc.rst

@@ -169,6 +169,29 @@ This feature has to be enabled separately as it is an extension to the core stan
    }
 
 
+Backchannel Logout Support
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+`Backchannel Logout`_ is an extension to the core standard which
+allows the OP to send direct requests to terminate sessions at the RP.
+
+.. code-block:: python
+
+   OAUTH2_PROVIDER = {
+       # OIDC has to be enabled to use Backchannel logout
+       "OIDC_ENABLED": True,
+       "OIDC_ISS_ENDPOINT": "https://idp.example.com", # Required for issuing logout tokens
+       # Enable and configure Backchannel Logout Support
+       "OIDC_BACKCHANNEL_LOGOUT_ENABLED": True,
+       # ... any other settings you want
+   }
+
+.. _Backchannel Logout: https://openid.net/specs/openid-connect-backchannel-1_0.html
+
+To make use of this, the application being created needs to provide a
+valid ``backchannel_logout_uri``.
+
+
 Setting up OIDC enabled clients
 ===============================
 

docs/settings.rst

@@ -361,6 +361,7 @@ When is set to ``False`` (default) the `OpenID Connect RP-Initiated Logout <http
 endpoint is not enabled. OpenID Connect RP-Initiated Logout enables an :term:`Client` (Relying Party)
 to request that a :term:`Resource Owner` (End User) is logged out at the :term:`Authorization Server` (OpenID Provider).
 
+
 OIDC_RP_INITIATED_LOGOUT_ALWAYS_PROMPT
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Default: ``True``
@@ -400,6 +401,21 @@ discovery metadata from ``OIDC_ISS_ENDPOINT`` +
 If unset, the default location is used, eg if ``django-oauth-toolkit`` is
 mounted at ``/o``, it will be ``<server-address>/o``.
 
+OIDC_BACKCHANNEL_LOGOUT_ENABLED
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Default: ``False``
+
+When is set to ``False`` (default) the `OpenID Connect Backchannel Logout <https://openid.net/specs/openid-connect-backchannel-1_0.html>`_
+extension is not enabled. OpenID Connect Backchannel Logout enables the :term:`Authorization Server` (OpenID Provider) to submit a JWT token to an endpoint controlled by the :term:`Client` (Relying Party)
+indicating that a session from the :term:`Resource Owner` (End User) has ended.
+
+OIDC_BACKCHANNEL_LOGOUT_HANDLER
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Default: ``oauth2_provider.handlers.send_backchannel_logout_request``
+
+Upon logout, the :term:`Authorization Server` (OpenID Provider)  will look for all ID Tokens associated with the user on applications that support Backchannel Logout. For every id token that is found, the function defined here will be called. The default function can be used as-is, but if you need to override or customize it somehow (e.g, if you do not want to execute these requests on the same HTTP request-response from the user logout view), you can change this setting to any function that takes ``id_token`` as a keyword argument.
+
+
 OIDC_RESPONSE_TYPES_SUPPORTED
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Default::

oauth2_provider/apps.py

@@ -7,4 +7,4 @@ class DOTConfig(AppConfig):
 
     def ready(self):
         # Import checks to ensure they run.
-        from . import checks  # noqa: F401
+        from . import checks, handlers  # noqa: F401

oauth2_provider/checks.py

@@ -26,3 +26,18 @@ def validate_token_configuration(app_configs, **kwargs):
         return [checks.Error("The token models are expected to be stored in the same database.")]
 
     return []
+
+
+@checks.register()
+def validate_backchannel_logout(app_configs, **kwargs):
+    errors = []
+
+    if oauth2_settings.OIDC_BACKCHANNEL_LOGOUT_ENABLED:
+        if not oauth2_settings.OIDC_ENABLED:
+            errors.append(checks.Error("OIDC_ENABLED must be True to enable OIDC backchannel logout."))
+        if not callable(oauth2_settings.OIDC_BACKCHANNEL_LOGOUT_HANDLER):
+            errors.append(checks.Error("OIDC_BACKCHANNEL_LOGOUT_HANDLER must be a callable."))
+        if not oauth2_settings.OIDC_ISS_ENDPOINT:
+            errors.append(checks.Error("OIDC_ISS_ENDPOINT must be set to enable OIDC backchannel logout."))
+
+    return errors

oauth2_provider/exceptions.py

@@ -35,6 +35,11 @@ def __init__(self, description=None):
         super().__init__(message)
 
 
+class BackchannelLogoutRequestError(OIDCError):
+    error = "backchannel_logout_request_failed"
+    description = "Backchannel logout request failed."
+
+
 class InvalidRequestFatalError(OIDCError):
     """
     For fatal errors. These are requests with invalid parameter values, missing parameters or otherwise

oauth2_provider/handlers.py

@@ -0,0 +1,110 @@
+import json
+import logging
+from datetime import timedelta
+
+import requests
+from django.contrib.auth.signals import user_logged_out
+from django.dispatch import receiver
+from django.utils import timezone
+from jwcrypto import jwt
+
+from .exceptions import BackchannelLogoutRequestError
+from .models import AbstractApplication, get_id_token_model
+from .settings import oauth2_settings
+
+
+IDToken = get_id_token_model()
+
+logger = logging.getLogger(__name__)
+
+BACKCHANNEL_LOGOUT_TIMEOUT = getattr(oauth2_settings, "OIDC_BACKCHANNEL_LOGOUT_TIMEOUT", 5)
+
+
+def send_backchannel_logout_request(id_token, *args, **kwargs):
+    """
+    Send a logout token to the applications backchannel logout uri
+    """
+
+    ttl = kwargs.get("ttl") or timedelta(minutes=10)
+
+    if not oauth2_settings.OIDC_BACKCHANNEL_LOGOUT_ENABLED:
+        raise BackchannelLogoutRequestError("Backchannel logout not enabled")
+
+    if id_token.application.algorithm == AbstractApplication.NO_ALGORITHM:
+        raise BackchannelLogoutRequestError("Application must provide signing algorithm")
+
+    if not id_token.application.backchannel_logout_uri:
+        raise BackchannelLogoutRequestError("URL for backchannel logout not provided by client")
+
+    if not oauth2_settings.OIDC_ISS_ENDPOINT:
+        raise BackchannelLogoutRequestError("OIDC_ISS_ENDPOINT is not set")
+
+    try:
+        issued_at = timezone.now()
+        expiration_date = issued_at + ttl
+
+        claims = {
+            "iss": oauth2_settings.OIDC_ISS_ENDPOINT,
+            "sub": str(id_token.user.pk),
+            "aud": str(id_token.application.client_id),
+            "iat": int(issued_at.timestamp()),
+            "exp": int(expiration_date.timestamp()),
+            "jti": id_token.jti,
+            "events": {"http://schemas.openid.net/event/backchannel-logout": {}},
+        }
+
+        # Standard JWT header
+        header = {"typ": "logout+jwt", "alg": id_token.application.algorithm}
+
+        # RS256 consumers expect a kid in the header for verifying the token
+        if id_token.application.algorithm == AbstractApplication.RS256_ALGORITHM:
+            header["kid"] = id_token.application.jwk_key.thumbprint()
+
+        token = jwt.JWT(
+            header=json.dumps(header, default=str),
+            claims=json.dumps(claims, default=str),
+        )
+
+        token.make_signed_token(id_token.application.jwk_key)
+
+        headers = {"Content-Type": "application/x-www-form-urlencoded"}
+        data = {"logout_token": token.serialize()}
+        response = requests.post(
+            id_token.application.backchannel_logout_uri,
+            headers=headers,
+            data=data,
+            timeout=BACKCHANNEL_LOGOUT_TIMEOUT,
+        )
+        response.raise_for_status()
+    except requests.RequestException as exc:
+        raise BackchannelLogoutRequestError(str(exc))
+
+
+@receiver(user_logged_out)
+def on_user_logged_out_maybe_send_backchannel_logout(sender, **kwargs):
+    handler = oauth2_settings.OIDC_BACKCHANNEL_LOGOUT_HANDLER
+    if not oauth2_settings.OIDC_BACKCHANNEL_LOGOUT_ENABLED or not callable(handler):
+        return
+
+    now = timezone.now()
+    user = kwargs["user"]
+
+    # Get ID tokens for user where Application has backchannel_logout_uri configured
+    # and scope doesn't contain offline_access (those sessions persist beyond logout)
+    id_tokens = (
+        IDToken.objects.filter(user=user, application__backchannel_logout_uri__isnull=False, expires__gt=now)
+        .exclude(scope__icontains="offline_access")
+        .exclude(application__backchannel_logout_uri="")
+        .select_related("application")
+        .order_by("application", "-expires")
+    )
+
+    # Group by application and send one request per application
+    applications_notified = set()
+    for id_token in id_tokens:
+        if id_token.application not in applications_notified:
+            applications_notified.add(id_token.application)
+            try:
+                handler(id_token=id_token)
+            except BackchannelLogoutRequestError as exc:
+                logger.warning(str(exc))

oauth2_provider/migrations/0015_application_backchannel_logout_uri.py

@@ -0,0 +1,19 @@
+# Generated by Django 5.2 on 2025-06-06 12:42
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("oauth2_provider", "0014_alter_help_text"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="application",
+            name="backchannel_logout_uri",
+            field=models.URLField(
+                blank=True, help_text="Backchannel Logout URI where logout tokens will be sent", null=True
+            ),
+        ),
+    ]

oauth2_provider/models.py

@@ -79,6 +79,7 @@ class AbstractApplication(models.Model):
     * :attr:`client_secret` Confidential secret issued to the client during
                             the registration process as described in :rfc:`2.2`
     * :attr:`name` Friendly name for the Application
+    * :attr:`backchannel_logout_uri` Backchannel Logout URI (OIDC-only)
     """
 
     CLIENT_CONFIDENTIAL = "confidential"
@@ -152,6 +153,9 @@ class AbstractApplication(models.Model):
         help_text=_("Allowed origins list to enable CORS, space separated"),
         default="",
     )
+    backchannel_logout_uri = models.URLField(
+        blank=True, null=True, help_text=_("Backchannel Logout URI where logout tokens will be sent")
+    )
 
     class Meta:
         abstract = True

oauth2_provider/settings.py

@@ -101,6 +101,8 @@
         "client_secret_post",
         "client_secret_basic",
     ],
+    "OIDC_BACKCHANNEL_LOGOUT_ENABLED": False,
+    "OIDC_BACKCHANNEL_LOGOUT_HANDLER": "oauth2_provider.handlers.send_backchannel_logout_request",
     "OIDC_RP_INITIATED_LOGOUT_ENABLED": False,
     "OIDC_RP_INITIATED_LOGOUT_ALWAYS_PROMPT": True,
     "OIDC_RP_INITIATED_LOGOUT_STRICT_REDIRECT_URIS": False,
@@ -154,6 +156,7 @@
     "GRANT_ADMIN_CLASS",
     "ID_TOKEN_ADMIN_CLASS",
     "REFRESH_TOKEN_ADMIN_CLASS",
+    "OIDC_BACKCHANNEL_LOGOUT_HANDLER",
 )
 
 

oauth2_provider/templates/oauth2_provider/application_detail.html

@@ -45,6 +45,11 @@ <h3 class="block-center-heading">{{ application.name }}</h3>
                 <p><b>{% trans "Allowed Origins" %}</b></p>
                 <textarea class="input-block-level" readonly>{{ application.allowed_origins }}</textarea>
             </li>
+
+            <li>
+              <p><b>{% trans "Backchannel Logout URI" %}</b></p>
+              <input class="input-block-level" type="text" value="{{ application.backchannel_logout_uri }}" readonly>
+            </li>
         </ul>
 
         <div class="btn-toolbar">