Backchannel Logout

 - Add migration to add backchannel logout support
 - Add parameters related to backchannel logout on OIDC Discovery View
 - Change application creation and update form
 - Change template that renders information about the application

Author: lullis

AUTHORS

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

CHANGELOG.md

@@ -6,9 +6,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 
 ## [unreleased]
+
 ### Added
 * #1506 Support for Wildcard Origin and Redirect URIs
 * #1586 Turkish language support added
+* #1545 Support for OIDC Back-Channel Logout
 
 <!--
 ### Changed

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_endpoint`.
+
+
 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,15 @@ 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_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,16 @@ 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 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,10 @@ def __init__(self, description=None):
         super().__init__(message)
 
 
+class BackchannelLogoutRequestError(OIDCError):
+    error = "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,18 @@
+import logging
+
+from django.contrib.auth.signals import user_logged_out
+from django.dispatch import receiver
+
+from .settings import oauth2_settings
+
+
+logger = logging.getLogger(__name__)
+
+
+@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
+
+    handler(user=kwargs["user"])

oauth2_provider/migrations/0013_application_backchannel_logout_uri.py

@@ -0,0 +1,18 @@
+# Generated by Django 5.2 on 2025-06-06 12:42
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('oauth2_provider', '0012_add_token_checksum'),
+    ]
+
+    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

@@ -1,11 +1,13 @@
 import hashlib
+import json
 import logging
 import time
 import uuid
 from contextlib import suppress
 from datetime import timedelta
 from urllib.parse import parse_qsl, urlparse
 
+import requests
 from django.apps import apps
 from django.conf import settings
 from django.contrib.auth.hashers import identify_hasher, make_password
@@ -14,10 +16,11 @@
 from django.urls import reverse
 from django.utils import timezone
 from django.utils.translation import gettext_lazy as _
-from jwcrypto import jwk
+from jwcrypto import jwk, jwt
 from jwcrypto.common import base64url_encode
 from oauthlib.oauth2.rfc6749 import errors
 
+from .exceptions import BackchannelLogoutRequestError
 from .generators import generate_client_id, generate_client_secret
 from .scopes import get_scopes_backend
 from .settings import oauth2_settings
@@ -76,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"
@@ -147,6 +151,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
@@ -629,6 +636,53 @@ def revoke(self):
         """
         self.delete()
 
+    def send_backchannel_logout_request(self, ttl=timedelta(minutes=10)):
+        """
+        Send a logout token to the applications backchannel logout uri
+        """
+        try:
+            assert oauth2_settings.OIDC_BACKCHANNEL_LOGOUT_ENABLED, "Backchannel logout not enabled"
+            assert self.application.algorithm != AbstractApplication.NO_ALGORITHM, (
+                "Application must provide signing algorithm"
+            )
+            assert self.application.backchannel_logout_uri is not None, (
+                "URL for backchannel logout not provided by client"
+            )
+
+            issued_at = timezone.now()
+            expiration_date = issued_at + ttl
+
+            claims = {
+                "iss": oauth2_settings.OIDC_ISS_ENDPOINT,
+                "sub": str(self.user.id),
+                "aud": str(self.application.client_id),
+                "iat": int(issued_at.timestamp()),
+                "exp": int(expiration_date.timestamp()),
+                "jti": self.jti,
+                "events": {"http://schemas.openid.net/event/backchannel-logout": {}},
+            }
+
+            # Standard JWT header
+            header = {"typ": "logout+jwt", "alg": self.application.algorithm}
+
+            # RS256 consumers expect a kid in the header for verifying the token
+            if self.application.algorithm == AbstractApplication.RS256_ALGORITHM:
+                header["kid"] = self.application.jwk_key.thumbprint()
+
+            token = jwt.JWT(
+                header=json.dumps(header, default=str),
+                claims=json.dumps(claims, default=str),
+            )
+
+            token.make_signed_token(self.application.jwk_key)
+
+            headers = {"Content-Type": "application/x-www-form-urlencoded"}
+            data = {"logout_token": token.serialize()}
+            response = requests.post(self.application.backchannel_logout_uri, headers=headers, data=data)
+            response.raise_for_status()
+        except (AssertionError, requests.RequestException) as exc:
+            raise BackchannelLogoutRequestError(str(exc))
+
     @property
     def scopes(self):
         """
@@ -859,3 +913,15 @@ def is_origin_allowed(origin, allowed_origins):
             return True
 
     return False
+
+
+def send_backchannel_logout_requests(user):
+    """
+    Creates logout tokens for all id tokens associated with the user
+    """
+    id_tokens = IDToken.objects.filter(application__backchannel_logout_uri__isnull=False, user=user)
+    for id_token in id_tokens:
+        try:
+            id_token.send_backchannel_logout_request()
+        except BackchannelLogoutRequestError as exc:
+            logger.warn(str(exc))