PR feedback

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``

docs/signals.rst

@@ -1,14 +1,20 @@
 Django Signals
 ================
 
-**django-auth-adfs** uses Django `Signals <https://docs.djangoproject.com/en/stable/topics/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 <https://docs.djangoproject.com/en/stable/topics/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 <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)