Backchannel Logout

 - 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

AUTHORS

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

CHANGELOG.md

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

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/admin.py

@@ -10,6 +10,8 @@
     get_grant_model,
     get_id_token_admin_class,
     get_id_token_model,
+    get_logout_token_model,
+    get_logout_token_admin_class,
     get_refresh_token_admin_class,
     get_refresh_token_model,
 )
@@ -51,6 +53,14 @@ class IDTokenAdmin(admin.ModelAdmin):
     list_select_related = ("application", "user")
 
 
+class LogoutTokenAdmin(admin.ModelAdmin):
+    list_display = ("user", "application", "id_token")
+    raw_id_fields = ("user",)
+    search_fields = ("user__email",) if has_email else ()
+    list_filter = ("application",)
+    list_select_related = ("application", "user", "id_token")
+
+
 class RefreshTokenAdmin(admin.ModelAdmin):
     list_display = ("token", "user", "application")
     raw_id_fields = ("user", "access_token")
@@ -62,16 +72,19 @@ class RefreshTokenAdmin(admin.ModelAdmin):
 access_token_model = get_access_token_model()
 grant_model = get_grant_model()
 id_token_model = get_id_token_model()
+logout_token_model = get_logout_token_model()
 refresh_token_model = get_refresh_token_model()
 
 application_admin_class = get_application_admin_class()
 access_token_admin_class = get_access_token_admin_class()
 grant_admin_class = get_grant_admin_class()
 id_token_admin_class = get_id_token_admin_class()
+logout_token_admin_class = get_logout_token_admin_class()
 refresh_token_admin_class = get_refresh_token_admin_class()
 
 admin.site.register(application_model, application_admin_class)
 admin.site.register(access_token_model, access_token_admin_class)
 admin.site.register(grant_model, grant_admin_class)
 admin.site.register(id_token_model, id_token_admin_class)
+admin.site.register(logout_token_model, logout_token_admin_class)
 admin.site.register(refresh_token_model, refresh_token_admin_class)

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/checks.py

@@ -13,6 +13,7 @@ def validate_token_configuration(app_configs, **kwargs):
             oauth2_settings.ACCESS_TOKEN_MODEL,
             oauth2_settings.ID_TOKEN_MODEL,
             oauth2_settings.REFRESH_TOKEN_MODEL,
+            oauth2_settings.LOGOUT_TOKEN_MODEL,
         )
     )
 
@@ -26,3 +27,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,17 @@
+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_logouttoken.py

@@ -0,0 +1,35 @@
+# Generated by Django 5.2 on 2025-06-02 18:31
+
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+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_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=settings.OAUTH2_PROVIDER_APPLICATION_MODEL)),
+                ('id_token', models.OneToOneField(null=True, on_delete=django.db.models.deletion.SET_NULL, to=settings.OAUTH2_PROVIDER_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',
+            },
+        ),
+    ]