Session management

AUTHORS

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

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 * #1506 Support for Wildcard Origin and Redirect URIs
 * #1586 Turkish language support added
+* Support for OIDC Session Management (https://openid.net/specs/openid-connect-session-1_0.html)
 
 <!--
 ### Changed

docs/oidc.rst

@@ -381,6 +381,39 @@ token, so you will probably want to reuse that::
             claims["color_scheme"] = get_color_scheme(request.user)
             return claims
 
+
+Session Management
+==================
+
+The `OpenID Connect Session Management 1.0
+<https://openid.net/specs/openid-connect-session-1_0.html>`_
+specification defines how to monitor the End-User's login status at
+the OpenID Provider on an ongoing basis so that the Relying Party can
+log out an End-User who has logged out of the OpenID Provider.
+
+To enable it, you will need to add
+``oauth2_provider.middleware.OIDCSessionManagementMiddleware`` to MIDDLEWARES and set
+``OIDC_SESSION_MANAGEMENT_ENABLED`` to ``True`` on
+``OAUTH2_PROVIDER``. You will also need to provide a string on
+``OIDC_SESSION_MANAGEMENT_DEFAULT_SESSION_KEY``. This setting is
+needed to ensure that the browser state for all unauthenticated users
+is fixed and the same even if you are running multiple server
+processes :::
+
+    import os
+
+    MIDDLEWARES = [
+        # Other middleware...
+        oauth2_provider.middleware.OIDCSessionManagementMiddleware,
+    ]
+
+    OAUTH2_PROVIDER = {
+        # ... other settings
+        "OIDC_SESSION_MANAGEMENT_ENABLED": True,
+        "OIDC_SESSION_MANAGEMENT_DEFAULT_SESSION_KEY": os.environ.get("OIDC_DEFAULT_SESSION_KEY"),
+    }
+
+
 Customizing the login flow
 ==========================
 

docs/settings.rst

@@ -315,6 +315,12 @@ Default: ``False``
 
 Whether or not :doc:`oidc` support is enabled.
 
+OIDC_SESSION_MANAGEMENT_ENABLED
+~~~~~~~~~~~~
+Default: ``False``
+
+Whether or not :doc:`oidc` support is enabled.
+
 OIDC_RSA_PRIVATE_KEY
 ~~~~~~~~~~~~~~~~~~~~
 Default: ``""``
@@ -353,6 +359,18 @@ this you must also provide the service at that endpoint.
 If unset, the default location is used, eg if ``django-oauth-toolkit`` is
 mounted at ``/o/``, it will be ``<server-address>/o/userinfo/``.
 
+OIDC_SESSION_IFRAME_ENDPOINT
+~~~~~~~~~~~~~~~~~~~~~~
+Default: ``""``
+
+The url of the session frame endpoint. Used to advertise the location of the
+endpoint in the OIDC discovery metadata. Changing this does not change the URL
+that ``django-oauth-toolkit`` adds for the userinfo endpoint, so if you change
+this you must also provide the service at that endpoint.
+
+If unset, the default location is used, eg if ``django-oauth-toolkit`` is
+mounted at ``/o/``, it will be ``<server-address>/o/session-iframe/``.
+
 OIDC_RP_INITIATED_LOGOUT_ENABLED
 ~~~~~~~~~~~~~~~~~~~~~~~~
 Default: ``False``

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_session_management_configuration(app_configs, **kwargs):
+    oidc_session_enabled = oauth2_settings.OIDC_SESSION_MANAGEMENT_ENABLED
+    has_default_key = oauth2_settings.OIDC_SESSION_MANAGEMENT_DEFAULT_SESSION_KEY is not None
+    if oidc_session_enabled and not has_default_key:
+        return [
+            checks.Error(
+                "OIDC Session management is enabled, OIDC_SESSION_MANAGEMENT_DEFAULT_SESSION_KEY is required."
+            )
+        ]
+    return []

oauth2_provider/middleware.py

@@ -5,6 +5,7 @@
 from django.utils.cache import patch_vary_headers
 
 from oauth2_provider.models import get_access_token_model
+from oauth2_provider.settings import oauth2_settings
 
 
 log = logging.getLogger(__name__)
@@ -63,3 +64,22 @@ def __call__(self, request):
                 log.exception(e)
         response = self.get_response(request)
         return response
+
+
+class OIDCSessionManagementMiddleware:
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+    def __call__(self, request):
+        response = self.get_response(request)
+        if not oauth2_settings.OIDC_SESSION_MANAGEMENT_ENABLED:
+            return response
+
+        cookie_name = oauth2_settings.OIDC_SESSION_MANAGEMENT_COOKIE_NAME
+        if request.user.is_authenticated:
+            session_key_bytes = request.session.session_key.encode("utf-8")
+            hashed_key = hashlib.sha256(session_key_bytes).hexdigest()
+            response.set_cookie(cookie_name, hashed_key)
+        else:
+            response.delete_cookie(cookie_name)
+        return response

oauth2_provider/settings.py

@@ -73,7 +73,11 @@
     "ALLOWED_SCHEMES": ["https"],
     "ALLOW_URI_WILDCARDS": False,
     "OIDC_ENABLED": False,
+    "OIDC_SESSION_MANAGEMENT_ENABLED": False,
+    "OIDC_SESSION_MANAGEMENT_COOKIE_NAME": "oidc_ua_agent_state",
+    "OIDC_SESSION_MANAGEMENT_DEFAULT_SESSION_KEY": None,
     "OIDC_ISS_ENDPOINT": "",
+    "OIDC_SESSION_IFRAME_ENDPOINT": "",
     "OIDC_USERINFO_ENDPOINT": "",
     "OIDC_RSA_PRIVATE_KEY": "",
     "OIDC_RSA_PRIVATE_KEYS_INACTIVE": [],

oauth2_provider/templates/oauth2_provider/base.html

@@ -35,6 +35,8 @@
         }
 
     </style>
+    {% block js %}
+    {% endblock js %}
 </head>
 
 <body>

oauth2_provider/templates/oauth2_provider/check_session_iframe.html

@@ -0,0 +1,63 @@
+{% extends "oauth2_provider/base.html" %}
+
+{% block title %}Check Session IFrame{% endblock %}
+
+{% block js %}
+<script language="JavaScript" type="text/javascript">
+ async function sha256(message) {
+   // Encode the message as UTF-8
+   const msgBuffer = new TextEncoder().encode(message)
+
+   // Generate the hash
+   const hashBuffer = await crypto.subtle.digest('SHA-256', msgBuffer)
+   const hashArray = Array.from(new Uint8Array(hashBuffer))
+   return hashArray.map(b => b.toString(16).padStart(2, '0')).join('')
+ }
+
+ window.addEventListener("message", receiveMessage)
+
+ async function receiveMessage(e) {
+   // e.data has client_id and session_state
+   if (!e.data || typeof e.data != 'string' || e.data == 'error') {
+     return
+   }
+
+   try {
+     const [clientId, sessionStateImage] = e.data.split(' ')
+     const [sessionState, salt] = sessionStateImage.split('.')
+
+     let userAgentState
+     try {
+       userAgentState = getUserAgentState()
+     }
+     catch (err) {
+       userAgentState = ''
+     }
+     const knownImage = await sha256(`${clientId} ${e.origin} ${userAgentState} ${salt}`)
+
+     const status = sessionState == knownImage ? 'unchanged' : 'changed'
+     e.source.postMessage(status, e.origin)
+   } catch(err) {
+     e.source.postMessage(`error: ${err}`, e.origin)
+   }
+ }
+
+
+ function getUserAgentState() {
+   const cookieName = "{{ cookie_name }}"
+   if (document.cookie && document.cookie !== '') {
+     const cookies = document.cookie.split(';')
+     for (var i = 0; i < cookies.length; i++) {
+       const cookie = cookies[i].trim()
+       // Does this cookie string begin with the name we want?
+       if (cookie.substring(0, cookieName.length + 1) === (cookieName + '=')) {
+         return decodeURIComponent(cookie.substring(cookieName.length + 1))
+       }
+     }
+   }
+   throw new Error('OIDC Session Cookie not set')
+ }
+</script>
+{% endblock %}
+
+{% block content %}OIDC Session Management OP Iframe{% endblock content %}

oauth2_provider/urls.py

@@ -42,6 +42,7 @@
     ),
     path(".well-known/jwks.json", views.JwksInfoView.as_view(), name="jwks-info"),
     path("userinfo/", views.UserInfoView.as_view(), name="user-info"),
+    path("session-iframe/", views.SessionIFrameView.as_view(), name="session-iframe"),
     path("logout/", views.RPInitiatedLogoutView.as_view(), name="rp-initiated-logout"),
 ]
 

oauth2_provider/utils.py

@@ -1,8 +1,11 @@
 import functools
+import hashlib
 
 from django.conf import settings
 from jwcrypto import jwk
 
+from .settings import oauth2_settings
+
 
 @functools.lru_cache()
 def jwk_from_pem(pem_string):
@@ -32,3 +35,11 @@ def get_timezone(time_zone):
 
             return pytz.timezone(time_zone)
         return zoneinfo.ZoneInfo(time_zone)
+
+
+def session_management_state_key(request):
+    """
+    Determine value to use as session state.
+    """
+    key = request.session.session_key or str(oauth2_settings.OIDC_SESSION_MANAGEMENT_DEFAULT_SESSION_KEY)
+    return hashlib.sha256(key.encode("utf-8")).hexdigest()

oauth2_provider/views/__init__.py

@@ -15,5 +15,11 @@
     ScopedProtectedResourceView,
 )
 from .introspect import IntrospectTokenView
-from .oidc import ConnectDiscoveryInfoView, JwksInfoView, RPInitiatedLogoutView, UserInfoView
+from .oidc import (
+    ConnectDiscoveryInfoView,
+    JwksInfoView,
+    RPInitiatedLogoutView,
+    SessionIFrameView,
+    UserInfoView,
+)
 from .token import AuthorizedTokenDeleteView, AuthorizedTokensListView

oauth2_provider/views/base.py

@@ -1,6 +1,7 @@
 import hashlib
 import json
 import logging
+import secrets
 from urllib.parse import parse_qsl, urlencode, urlparse
 
 from django.contrib.auth.mixins import LoginRequiredMixin
@@ -21,6 +22,7 @@
 from ..scopes import get_scopes_backend
 from ..settings import oauth2_settings
 from ..signals import app_authorized
+from ..utils import session_management_state_key
 from .mixins import OAuthLibMixin
 
 
@@ -140,6 +142,35 @@ def form_valid(self, form):
         except OAuthToolkitError as error:
             return self.error_response(error, application)
 
+        if oauth2_settings.OIDC_SESSION_MANAGEMENT_ENABLED:
+            # https://openid.net/specs/openid-connect-session-1_0.html#CreatingUpdatingSessions
+
+            # When the OP supports session management, it MUST also
+            # return the Session State as an additional session_state
+            # parameter in the Authentication Response, the value is
+            # based on a salted cryptographic hash of Client ID,
+            # origin URL, and OP User Agent state.
+            parsed = urlparse(uri)
+            client_origin = f"{parsed.scheme}://{parsed.netloc}"
+
+            # Create random salt.
+            salt = secrets.token_urlsafe(16)
+            encoded = " ".join(
+                [
+                    credentials["client_id"],
+                    client_origin,
+                    session_management_state_key(self.request),
+                    salt,
+                ]
+            ).encode("utf-8")
+            hashed = hashlib.sha256(encoded)
+            session_state = f"{hashed.hexdigest()}.{salt}"
+
+            # Add the session_state parameter to the query string
+            qs = dict(parse_qsl(parsed.query))
+            qs["session_state"] = session_state
+            uri = parsed._replace(query=urlencode(qs)).geturl()
+
         self.success_url = uri
         log.debug("Success url for the request: {0}".format(self.success_url))
         return self.redirect(self.success_url, application)
@@ -214,10 +245,7 @@ def get(self, request, *args, **kwargs):
                 for token in tokens:
                     if token.allow_scopes(scopes):
                         uri, headers, body, status = self.create_authorization_response(
-                            request=self.request,
-                            scopes=" ".join(scopes),
-                            credentials=credentials,
-                            allow=True,
+                            request=self.request, scopes=" ".join(scopes), credentials=credentials, allow=True
                         )
                         return self.redirect(uri, application)