From 05c2832d8dab845499c1abb1f690c09db0e11fa1 Mon Sep 17 00:00:00 2001 From: Andrew Weinstein Date: Wed, 16 Oct 2024 22:57:12 -0600 Subject: [PATCH 1/2] docs: add documentation for post_authenticate signal --- docs/index.rst | 1 + docs/signals.rst | 25 +++++++++++++++++++++++++ 2 files changed, 26 insertions(+) create mode 100644 docs/signals.rst diff --git a/docs/index.rst b/docs/index.rst index ae55c12e..d3dcc5c8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -38,6 +38,7 @@ Contents settings_ref config_guides middleware + signals rest_framework demo troubleshooting diff --git a/docs/signals.rst b/docs/signals.rst new file mode 100644 index 00000000..44c7b534 --- /dev/null +++ b/docs/signals.rst @@ -0,0 +1,25 @@ +Django Signals +================ + +**django-auth-adfs** uses Django `Signals ` +to allow the application to listen for and execute custom logic at certain points in the authentication +process. Currently, the following signals are supported: + +* ``post_authenticate``: sent after a user has been authenticated through either the ``AdfsAuthCodeBackend`` + or the ``AdfsAccessTokenBackend`` (and created in Django, if ``CREATE_NEW_USERS`` is enabled) and + after all claims and groups have been mapped. The signal is sent with the user object, the claims + dictionary, and the ADFS response as arguments for the signal handler. + +To use a signal in your application: + +.. code-block:: python + + from django.dispatch import receiver + from django_auth_adfs.signals import post_authenticate + + + @receiver(post_authenticate) + def handle_post_authenticate(sender, user, claims, adfs_response, **kwargs): + user.do_post_auth_steps(claims, adfs_response) + + From 7a0053e4e95766bc7831ab8e6e142b6958d22bd5 Mon Sep 17 00:00:00 2001 From: Andrew Weinstein Date: Sun, 20 Oct 2024 21:01:29 -0600 Subject: [PATCH 2/2] PR feedback --- docs/settings_ref.rst | 2 ++ docs/signals.rst | 22 ++++++++++++++-------- 2 files changed, 16 insertions(+), 8 deletions(-) diff --git a/docs/settings_ref.rst b/docs/settings_ref.rst index 8d1c011a..1a331224 100644 --- a/docs/settings_ref.rst +++ b/docs/settings_ref.rst @@ -173,6 +173,8 @@ ADFS server. Based on this information, certain configuration for this module is This setting determines the interval after which the configuration is reloaded. This allows to automatically follow the token signing certificate rollover on ADFS. +.. _create_new_users_setting: + CREATE_NEW_USERS ---------------- * **Default**: ``True`` diff --git a/docs/signals.rst b/docs/signals.rst index 44c7b534..cdb630ae 100644 --- a/docs/signals.rst +++ b/docs/signals.rst @@ -1,14 +1,20 @@ Django Signals ================ -**django-auth-adfs** uses Django `Signals ` -to allow the application to listen for and execute custom logic at certain points in the authentication -process. Currently, the following signals are supported: +**django-auth-adfs** uses Django `Signals ` to allow the +application to listen for and execute custom logic at certain points in the authentication process. Currently, the +following signals are supported: -* ``post_authenticate``: sent after a user has been authenticated through either the ``AdfsAuthCodeBackend`` - or the ``AdfsAccessTokenBackend`` (and created in Django, if ``CREATE_NEW_USERS`` is enabled) and - after all claims and groups have been mapped. The signal is sent with the user object, the claims - dictionary, and the ADFS response as arguments for the signal handler. +* ``post_authenticate``: sent after a user has been authenticated through any subclass of ``AdfsBaseBackend``. The + signal is sent after all other processing is done, e.g. mapping claims and groups and creating the user in Django (if + :ref:`the CREATE_NEW_USERS setting ` is enabled). In addition to the sender, the signal + includes the user object, the claims dictionary, and the ADFS response as arguments for the signal handler: + + * ``sender`` (``AdfsBaseBackend``): the backend instance from which the signal was triggered. + * ``user`` (Django user class): the user object that was authenticated. + * ``claims`` (``dict``): the decoded access token JWT, which contains all claims sent from the identity provider. + * ``adfs_response`` (``dict|None``): used in the ``AdfsAuthCodeBackend`` to provide the full response received from + the server when exchanging an authorization code for an access token. To use a signal in your application: @@ -19,7 +25,7 @@ To use a signal in your application: @receiver(post_authenticate) - def handle_post_authenticate(sender, user, claims, adfs_response, **kwargs): + def handle_post_authenticate(sender, user, claims, adfs_response=None, **kwargs): user.do_post_auth_steps(claims, adfs_response)