Backchannel Logout

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,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 an IDToken as the first parameter.
+
+
 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,84 @@
+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__)
+
+
+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)
+
+    try:
+        assert oauth2_settings.OIDC_BACKCHANNEL_LOGOUT_ENABLED, "Backchannel logout not enabled"
+        assert id_token.application.algorithm != AbstractApplication.NO_ALGORITHM, (
+            "Application must provide signing algorithm"
+        )
+        assert id_token.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(id_token.user.id),
+            "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)
+        response.raise_for_status()
+    except (AssertionError, 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
+
+    user = kwargs["user"]
+    id_tokens = IDToken.objects.filter(application__backchannel_logout_uri__isnull=False, user=user)
+    for id_token in id_tokens:
+        try:
+            handler(id_token=id_token)
+        except BackchannelLogoutRequestError as exc:
+            logger.warn(str(exc))

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

@@ -76,6 +76,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 +148,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

@@ -92,6 +92,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,
@@ -144,7 +146,9 @@
     "ACCESS_TOKEN_ADMIN_CLASS",
     "GRANT_ADMIN_CLASS",
     "ID_TOKEN_ADMIN_CLASS",
+    "LOGOUT_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">

oauth2_provider/views/application.py

@@ -3,6 +3,8 @@
 from django.urls import reverse_lazy
 from django.views.generic import CreateView, DeleteView, DetailView, ListView, UpdateView
 
+from oauth2_provider.settings import oauth2_settings
+
 from ..models import get_application_model
 
 
@@ -17,33 +19,37 @@ def get_queryset(self):
         return get_application_model().objects.filter(user=self.request.user)
 
 
-class ApplicationRegistration(LoginRequiredMixin, CreateView):
+class ApplicationEditorMixin(LoginRequiredMixin):
+    def get_form_class(self):
+        """
+        Returns the form class for the application model
+        """
+        base_fields = [
+            "name",
+            "client_id",
+            "client_secret",
+            "hash_client_secret",
+            "client_type",
+            "authorization_grant_type",
+            "redirect_uris",
+            "post_logout_redirect_uris",
+            "allowed_origins",
+            "algorithm",
+        ]
+
+        if oauth2_settings.OIDC_BACKCHANNEL_LOGOUT_ENABLED:
+            base_fields.append("backchannel_logout_uri")
+
+        return modelform_factory(get_application_model(), fields=base_fields)
+
+
+class ApplicationRegistration(ApplicationEditorMixin, CreateView):
     """
     View used to register a new Application for the request.user
     """
 
     template_name = "oauth2_provider/application_registration_form.html"
 
-    def get_form_class(self):
-        """
-        Returns the form class for the application model
-        """
-        return modelform_factory(
-            get_application_model(),
-            fields=(
-                "name",
-                "client_id",
-                "client_secret",
-                "hash_client_secret",
-                "client_type",
-                "authorization_grant_type",
-                "redirect_uris",
-                "post_logout_redirect_uris",
-                "allowed_origins",
-                "algorithm",
-            ),
-        )
-
     def form_valid(self, form):
         form.instance.user = self.request.user
         return super().form_valid(form)
@@ -77,30 +83,10 @@ class ApplicationDelete(ApplicationOwnerIsUserMixin, DeleteView):
     template_name = "oauth2_provider/application_confirm_delete.html"
 
 
-class ApplicationUpdate(ApplicationOwnerIsUserMixin, UpdateView):
+class ApplicationUpdate(ApplicationOwnerIsUserMixin, ApplicationEditorMixin, UpdateView):
     """
     View used to update an application owned by the request.user
     """
 
     context_object_name = "application"
     template_name = "oauth2_provider/application_form.html"
-
-    def get_form_class(self):
-        """
-        Returns the form class for the application model
-        """
-        return modelform_factory(
-            get_application_model(),
-            fields=(
-                "name",
-                "client_id",
-                "client_secret",
-                "hash_client_secret",
-                "client_type",
-                "authorization_grant_type",
-                "redirect_uris",
-                "post_logout_redirect_uris",
-                "allowed_origins",
-                "algorithm",
-            ),
-        )

oauth2_provider/views/oidc.py

@@ -101,8 +101,15 @@ def get(self, request, *args, **kwargs):
             "code_challenge_methods_supported": [key for key, _ in AbstractGrant.CODE_CHALLENGE_METHODS],
             "claims_supported": oidc_claims,
         }
+
+        if oauth2_settings.OIDC_BACKCHANNEL_LOGOUT_ENABLED:
+            data["backchannel_logout_supported"] = True
+            # We need to issue SID claims on tokens to support this.
+            data["backchannel_logout_session_supported"] = False
+
         if oauth2_settings.OIDC_RP_INITIATED_LOGOUT_ENABLED:
             data["end_session_endpoint"] = end_session_endpoint
+
         response = JsonResponse(data)
         response["Access-Control-Allow-Origin"] = "*"
         return response

tests/presets.py

@@ -37,6 +37,12 @@
 OIDC_SETTINGS_RP_LOGOUT_DENY_EXPIRED["OIDC_RP_INITIATED_LOGOUT_ACCEPT_EXPIRED_TOKENS"] = False
 OIDC_SETTINGS_RP_LOGOUT_KEEP_TOKENS = deepcopy(OIDC_SETTINGS_RP_LOGOUT)
 OIDC_SETTINGS_RP_LOGOUT_KEEP_TOKENS["OIDC_RP_INITIATED_LOGOUT_DELETE_TOKENS"] = False
+OIDC_SETTINGS_BACKCHANNEL_LOGOUT = deepcopy(OIDC_SETTINGS_RW)
+OIDC_SETTINGS_BACKCHANNEL_LOGOUT["OIDC_BACKCHANNEL_LOGOUT_ENABLED"] = True
+
+OIDC_SETTINGS_BACKCHANNEL_LOGOUT_BAD_HANDLER = deepcopy(OIDC_SETTINGS_BACKCHANNEL_LOGOUT)
+OIDC_SETTINGS_BACKCHANNEL_LOGOUT_BAD_HANDLER["OIDC_BACKCHANNEL_LOGOUT_HANDLER"] = "not.a.real.function"
+
 REST_FRAMEWORK_SCOPES = {
     "SCOPES": {
         "read": "Read scope",