Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: add documentation for post_authenticate signal #351

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: add documentation for post_authenticate signal #351

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@ Contents
settings_ref
config_guides
middleware
signals
rest_framework
demo
troubleshooting
Expand Down
25 changes: 25 additions & 0 deletions docs/signals.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
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:

* ``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
Comment on lines +8 to +9
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm good with this being merged as is, but I think there's room for some improvement.

I haven't checked the code, but I'm pretty sure the base backend class is what triggers the signal. If that's true it's better to say "authenticated through any subclass of BaseBackend (use the actual name). This signal is sent after any processing is done such as mapping claims, groups and creating the user if CREATE_NEW_USERS is enabled."

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you are correct - i was looking at something else in the subclasses and just misremembered when i was writing this. i'll update it.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ideally, we'd put a ref on CREATE_NEW_USERS in settings_ref.rst and use the ref syntax here.

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):
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would there be a benefit to explaining what the signal arguments are outside the code block?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i was a little torn on adding more documentation here vs. adding another place that needs to be changed if the code changes. but i guess if there's going to be a doc for it, it might as well be descriptive.

user.do_post_auth_steps(claims, adfs_response)


Loading