Backchannel Logout: Models and Views

 - Add migration to add backchannel logout support
 - Add model for Logout Token
 - Add admin for Logout Token
 - 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

oauth2_provider/admin.py

@@ -51,6 +51,14 @@ class IDTokenAdmin(admin.ModelAdmin):
     list_select_related = ("application", "user")
 
 
+class LogoutTokenAdmin(admin.ModelAdmin):
+    list_display = ("user", "application")
+    raw_id_fields = ("user",)
+    search_fields = ("user__email",) if has_email else ()
+    list_filter = ("application",)
+    list_select_related = ("application", "user")
+
+
 class RefreshTokenAdmin(admin.ModelAdmin):
     list_display = ("token", "user", "application")
     raw_id_fields = ("user", "access_token")

oauth2_provider/apps.py

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

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,34 @@
+import logging
+
+from django.contrib.auth.signals import user_logged_out
+from django.dispatch import receiver
+
+from .exceptions import BackchannelLogoutRequestError
+from .settings import oauth2_settings
+from .models import get_logout_token_model, get_application_model, get_access_token_model
+
+
+logger = logging.getLogger(__name__)
+
+LogoutToken = get_logout_token_model()
+Application = get_application_model()
+AccessToken = get_access_token_model()
+
+
+@receiver(user_logged_out)
+def on_user_logged_out_maybe_send_backchannel_logout(sender, **kw):
+    if not oauth2_settings.OIDC_BACKCHANNEL_LOGOUT_ENABLED:
+        return
+
+    request = kw["request"]
+    user = kw["user"]
+
+    applications = Application.objects.exclude(backchannel_logout_uri__isnull=True)
+    for application in applications:
+        logout_token = LogoutToken.objects.create(
+            user=user, session_key=request.session.session_key, application=application
+        )
+        try:
+            logout_token.send_backchannel_logout_request()
+        except BackchannelLogoutRequestError as exc:
+            logger.warn(str(exc))

oauth2_provider/migrations/0013_application_backchannel_logout_session_required_and_more.py

@@ -0,0 +1,61 @@
+# Generated by Django 5.2 on 2025-05-05 02:41
+
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+from oauth2_provider.settings import oauth2_settings
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("oauth2_provider", "0012_add_token_checksum"),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="application",
+            name="backchannel_logout_session_required",
+            field=models.BooleanField(default=False, help_text="Include SID claim in logout token?"),
+        ),
+        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
+            ),
+        ),
+        migrations.CreateModel(
+            name="LogoutToken",
+            fields=[
+                ("id", models.BigAutoField(primary_key=True, serialize=False)),
+                ("created", models.DateTimeField(auto_now_add=True)),
+                (
+                    "application",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE, to=oauth2_settings.APPLICATION_MODEL
+                    ),
+                ),
+                (
+                    "id_token",
+                    models.OneToOneField(
+                        null=True,
+                        on_delete=django.db.models.deletion.SET_NULL,
+                        to=oauth2_settings.ID_TOKEN_MODEL,
+                    ),
+                ),
+                (
+                    "user",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="%(app_label)s_%(class)s",
+                        to=settings.AUTH_USER_MODEL,
+                    ),
+                ),
+            ],
+            options={
+                "abstract": False,
+                "swappable": "OAUTH2_PROVIDER_LOGOUT_TOKEN_MODEL",
+            },
+        ),
+    ]

oauth2_provider/models.py

@@ -2,6 +2,7 @@
 import logging
 import time
 import uuid
+import json
 from contextlib import suppress
 from datetime import timedelta
 from urllib.parse import parse_qsl, urlparse
@@ -14,16 +15,17 @@
 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
+import requests
 
 from .generators import generate_client_id, generate_client_secret
 from .scopes import get_scopes_backend
 from .settings import oauth2_settings
 from .utils import jwk_from_pem
 from .validators import AllowedURIValidator
-
+from .exceptions import BackchannelLogoutRequestError
 
 logger = logging.getLogger(__name__)
 
@@ -76,6 +78,9 @@ 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)
+    * :attr:`backchannel_logout_session_required` Whether application requires
+                                 session id claim in sent in token (OIDC-only)
     """
 
     CLIENT_CONFIDENTIAL = "confidential"
@@ -147,6 +152,12 @@ 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"
+    )
+    backchannel_logout_session_required = models.BooleanField(
+        default=False, help_text=_("Include SID claim in logout token?")
+    )
 
     class Meta:
         abstract = True
@@ -650,6 +661,75 @@ class Meta(AbstractIDToken.Meta):
         swappable = "OAUTH2_PROVIDER_ID_TOKEN_MODEL"
 
 
+class AbstractLogoutToken(models.Model):
+    TTL = timedelta(minutes=10)
+
+    id = models.BigAutoField(primary_key=True)
+    user = models.ForeignKey(
+        settings.AUTH_USER_MODEL, on_delete=models.CASCADE, related_name="%(app_label)s_%(class)s"
+    )
+    application = models.ForeignKey(oauth2_settings.APPLICATION_MODEL, on_delete=models.CASCADE)
+    id_token = models.OneToOneField(oauth2_settings.ID_TOKEN_MODEL, null=True, on_delete=models.SET_NULL)
+    created = models.DateTimeField(auto_now_add=True)
+
+    @property
+    def expires(self):
+        return self.created + self.TTL
+
+    @property
+    def jwt_claim_dictionary(self):
+        claims = {
+            "iss": oauth2_settings.OIDC_ISS_ENDPOINT,
+            "sub": str(self.user.id),
+            "aud": str(self.application.client_id),
+            "iat": int(self.created.timestamp()),
+            "exp": int(self.expires.timestamp()),
+            "jti": str(self.jti),
+            "events": {"http://schemas.openid.net/event/backchannel-logout": {}},
+        }
+
+        if session_key:
+            claims["sid"] = session_key
+
+        return claims
+
+    def get_serialized_jwt(self):
+        # 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(self.jwt_claim_dictionary, default=str),
+        )
+        token.make_signed_token(self.application.jwk_key)
+        return token.serialize()
+
+    def send_backchannel_logout_request(self):
+        if not oauth2_settings.OIDC_BACKCHANNEL_LOGOUT_ENABLED:
+            return
+        try:
+            if self.application.backchannel_logout_session_required:
+                assert bool(self.session_key), "No Session ID provided"
+
+            headers = {"Content-Type": "application/x-www-form-urlencoded"}
+            data = {"logout_token": self.get_serialized_jwt()}
+            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))
+
+    class Meta:
+        abstract = True
+
+
+class LogoutToken(AbstractLogoutToken):
+    class Meta(AbstractLogoutToken.Meta):
+        swappable = "OAUTH2_PROVIDER_LOGOUT_TOKEN_MODEL"
+
+
 def get_application_model():
     """Return the Application model that is active in this project."""
     return apps.get_model(oauth2_settings.APPLICATION_MODEL)
@@ -670,6 +750,11 @@ def get_id_token_model():
     return apps.get_model(oauth2_settings.ID_TOKEN_MODEL)
 
 
+def get_logout_token_model():
+    """Return the IDToken model that is active in this project."""
+    return apps.get_model(oauth2_settings.LOGOUT_TOKEN_MODEL)
+
+
 def get_refresh_token_model():
     """Return the RefreshToken model that is active in this project."""
     return apps.get_model(oauth2_settings.REFRESH_TOKEN_MODEL)
@@ -699,6 +784,11 @@ def get_id_token_admin_class():
     return id_token_admin_class
 
 
+def get_logout_token_admin_class():
+    """Return the LogoutToken admin class that is active in this project."""
+    return oauth2_settings.LOGOUT_TOKEN_ADMIN_CLASS
+
+
 def get_refresh_token_admin_class():
     """Return the RefreshToken admin class that is active in this project."""
     refresh_token_admin_class = oauth2_settings.REFRESH_TOKEN_ADMIN_CLASS
@@ -729,6 +819,7 @@ def batch_delete(queryset, query):
     access_token_model = get_access_token_model()
     refresh_token_model = get_refresh_token_model()
     id_token_model = get_id_token_model()
+    logout_token_model = get_logout_token_model()
     grant_model = get_grant_model()
     REFRESH_TOKEN_EXPIRE_SECONDS = oauth2_settings.REFRESH_TOKEN_EXPIRE_SECONDS
 
@@ -756,6 +847,11 @@ def batch_delete(queryset, query):
     else:
         logger.info("refresh_expire_at is %s. No refresh tokens deleted.", refresh_expire_at)
 
+    logout_token_query = models.Q(created__lt=now - logout_token_model.TTL)
+    logout_tokens = logout_token_model.objects.filter(logout_token_query)
+    logout_tokens_delete_no = batch_delete(logout_tokens, logout_token_query)
+    logger.info("%s Expired logout tokens deleted", logout_tokens_delete_no)
+
     access_token_query = models.Q(refresh_token__isnull=True, expires__lt=now)
     access_tokens = access_token_model.objects.filter(access_token_query)
 

oauth2_provider/settings.py

@@ -30,6 +30,7 @@
 APPLICATION_MODEL = getattr(settings, "OAUTH2_PROVIDER_APPLICATION_MODEL", "oauth2_provider.Application")
 ACCESS_TOKEN_MODEL = getattr(settings, "OAUTH2_PROVIDER_ACCESS_TOKEN_MODEL", "oauth2_provider.AccessToken")
 ID_TOKEN_MODEL = getattr(settings, "OAUTH2_PROVIDER_ID_TOKEN_MODEL", "oauth2_provider.IDToken")
+LOGOUT_TOKEN_MODEL = getattr(settings, "OAUTH2_PROVIDER_LOGOUT_TOKEN_MODEL", "oauth2_provider.LogoutToken")
 GRANT_MODEL = getattr(settings, "OAUTH2_PROVIDER_GRANT_MODEL", "oauth2_provider.Grant")
 REFRESH_TOKEN_MODEL = getattr(settings, "OAUTH2_PROVIDER_REFRESH_TOKEN_MODEL", "oauth2_provider.RefreshToken")
 
@@ -61,12 +62,14 @@
     "APPLICATION_MODEL": APPLICATION_MODEL,
     "ACCESS_TOKEN_MODEL": ACCESS_TOKEN_MODEL,
     "ID_TOKEN_MODEL": ID_TOKEN_MODEL,
+    "LOGOUT_TOKEN_MODEL": LOGOUT_TOKEN_MODEL,
     "GRANT_MODEL": GRANT_MODEL,
     "REFRESH_TOKEN_MODEL": REFRESH_TOKEN_MODEL,
     "APPLICATION_ADMIN_CLASS": "oauth2_provider.admin.ApplicationAdmin",
     "ACCESS_TOKEN_ADMIN_CLASS": "oauth2_provider.admin.AccessTokenAdmin",
     "GRANT_ADMIN_CLASS": "oauth2_provider.admin.GrantAdmin",
     "ID_TOKEN_ADMIN_CLASS": "oauth2_provider.admin.IDTokenAdmin",
+    "LOGOUT_TOKEN_ADMIN_CLASS": "oauth2_provider.admin.LogoutTokenAdmin",
     "REFRESH_TOKEN_ADMIN_CLASS": "oauth2_provider.admin.RefreshTokenAdmin",
     "REQUEST_APPROVAL_PROMPT": "force",
     "ALLOWED_REDIRECT_URI_SCHEMES": ["http", "https"],
@@ -92,6 +95,8 @@
         "client_secret_post",
         "client_secret_basic",
     ],
+    "OIDC_BACKCHANNEL_LOGOUT_ENABLED": False,
+    "OIDC_BACKCHANNEL_LOGOUT_SESSION_ENABLED": False,
     "OIDC_RP_INITIATED_LOGOUT_ENABLED": False,
     "OIDC_RP_INITIATED_LOGOUT_ALWAYS_PROMPT": True,
     "OIDC_RP_INITIATED_LOGOUT_STRICT_REDIRECT_URIS": False,

oauth2_provider/templates/oauth2_provider/application_detail.html

@@ -45,6 +45,17 @@ <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>
+
+            <li>
+              <p><b>{% trans "Backchannel Logout Session Required" %}</b></p>
+              <p>{{ application.backchannel_logout_session_required|yesno:_("yes,no") }}</p>
+            </li>
+
         </ul>
 
         <div class="btn-toolbar">