Configuration options
Configuration settings
Most important settings
A string of lists specifying which VOs are allowed to log into the website. |
|
Client id for the Helmholtz AAI |
|
Client secret for the Helmholtz AAI |
Two settings are necessary to use this package, this is the
HELMHOLTZ_CLIENT_ID
and the HELMHOLTZ_CLIENT_SECRET
that
you specified during the OAuth-Client registration (see Register your OAuth-Client at the Helmholtz AAI).
By default, the website allows all users to login and create an account via the
Helmholtz AAI. This if often not desired and you can modify this with the
HELMHOLTZ_ALLOWED_VOS
setting, e.g. something like:
HELMHOLTZ_ALLOWED_VOS = [
"urn:geant:helmholtz.de:group:hereon#login.helmholtz.de",
]
in your settings.py
.
Other settings
Further settings can be used to specify how to connect to the helmholtz AAI and how to interpret the userinfo of the Helmholtz AAI.
openid configuration url of the Helmholtz AAI |
|
Regular expressions for VOs that are allowed to login to the website. |
|
Keyword argument for the oauth client to connect with the helmholtz AAI. |
|
Flag to enable/disable user account creation via the Helmholtz AAI. |
|
Allow duplicated emails for users in the website |
|
Flag whether existing user accounts should be mapped |
|
Flag whether usernames should be updated from the Helmholtz AAI |
|
Username fields in the userinfo |
Customizing the login
If you are using the Helmholtz AAI, you likely want to combine it with the permission system of your Django project. You may want to set the is_staff attribute for users of a specific VO, or perform additional actions when a user logged in for the first time (e.g. send a welcome mail), enters or leaves a VO.
To perfectly adjust the django-helmholtz-aai framework to your projects need, you have two choices:
connect to the signals of the
signals
module, see Configuration via Signalssubclass the
HelmholtzAuthentificationView
view, see Customization via the HelmholtzAuthentificationView
The signals are the recommended way as they provide a more stable interface.
As the django-helmholtz-aai is very new, we cannot guarantee that there
won’t be breaking changes in the
HelmholtzAuthentificationView
.
Configuration via Signals
The signals
module defines various signal that are
fired on different events:
Signal that is fired when a user has been created via the Helmholtz AAI |
|
Signal that is fired when a user logs in via the Helmholtz AAI |
|
Signal that is fired when a user receives an update via the Helmholtz AAI |
|
Signal that is fired if a new Virtual Organization has been created |
|
Signal that is fired if a Helmholtz AAI user enteres a VO |
|
Signal that is fired if a Helmholtz AAI user left a VO |
The purpose of these signals should be pretty much self-explanatory.
Examples
Suppose you want users of a specific VO to become superusers. Then you can do
something like this using the aai_vo_entered
and
aai_vo_left
signals:
from django.dispatch import receiver
from django_helmholtz_aai import models, signals
@receiver(signals.aai_vo_entered)
def on_vo_enter(
sender,
vo: models.HelmholtzVirtualOrganization,
user: models.HelmholtzUser,
**kwargs,
):
vo_id = "urn:geant:helmholtz.de:group:hereon#login.helmholtz.de"
if vo.eduperson_entitlement == vo_id:
user.is_superuser = True
user.save()
@receiver(signals.aai_vo_left)
def on_vo_leave(
sender,
vo: models.HelmholtzVirtualOrganization,
user: models.HelmholtzUser,
**kwargs,
):
vo_id = "urn:geant:helmholtz.de:group:hereon#login.helmholtz.de"
if vo.eduperson_entitlement == vo_id:
user.is_superuser = False
user.save()
Let’s say you want to display a message in the frontend when a user logged in
for the first time. Here you can use the aai_user_created
signal:
from django.contrib import messages
from django_helmholtz_aai import models, signals
@receiver(signals.aai_user_created)
def created_user(
sender,
user: models.HelmholtzUser,
request,
**kwargs,
):
messages.add_message(
request, messages.success, f"Welcome on board {user}!"
)
Customization via the HelmholtzAuthentificationView
Warning
Please bear in mind that this python package is still very new and we
cannot guarantee that there won’t be breaking changes in the
HelmholtzAuthentificationView
class.
Another way to customize the login is via the
HelmholtzAuthentificationView
. Your
starting point should be the following two methods, one for checking the
permissions and one for performing the request:
|
Login the Helmholtz AAI user and update the data. |
Check if the user has permission to login. |
For a more fine-grained control of the authentification (such as user creation or update), you can make use of the following methods and reimplement to your needs.
|
Create a Django user for a Helmholtz AAI User. |
|
Login the Helmholtz AAI user to the Django Application. |
Synchronize the memberships in the virtual organizations. |
|
Update the user from the userinfo provided by the Helmholtz AAI. |
Example
Let’s say you want to approve users before you let them login to the website.
One possibility is, to create a custom model with reference to a user and
reimplement the
django_helmholtz_aai.views.HelmholtzAuthentificationView.login_user()
.
Your custom app that reimplements this view then might look like
models.py
from django.db import models from django_helmholtz_aai.models import HelmholtzUser class HelmholtzUserReview(models.Model): """A review of a helmholtz user""" class ReviewStatus(models.TextChoices): accepted = "accepted" rejected = "rejected" user = models.OneToOneField(HelmholtzUser, on_delete=models.CASCADE) review_status = models.CharField( choices=ReviewStatus.choices, blank=True, null=True )
views.py
from django.contrib import messages from django_helmholtz_aai.views import HelmholtzAuthentificationView from django_helmholtz_aai.models import HelmholtzUser from .models import HelmholtzUserReview class CustomHelmholtzAuthentificationView(HelmholtzAuthentificationView): def login_user(self, user: HelmholtzUser): review = HelmholtzUserReview.objects.get_or_create(user=user)[0] if ( review.review_status == HelmholtzUserReview.ReviewStatus.accepted ): super().login_user(user) elif ( review.review_status == HelmholtzUserReview.ReviewStatus.rejected ): messages.add_message( self.request, messages.error, f"Your account creation request has been rejected.", ) else: messages.add_message( self.request, messages.success, f"Your account creation request is currently under review.", )
urls.py
from django.urls import include, path from .views import CustomHelmholtzAuthentificationView urlpatterns = [ path( "helmholtz-aai/auth/", CustomHelmholtzAuthentificationView.as_view(), ), path("helmholtz-aai/", include("django_helmholtz_aai.urls")), ]