Installation
To install the django-helmholtz-aai package for your Django project, you need to follow three steps:
Installation from PyPi
The recommended way to install this package is via pip and PyPi via:
pip install django-helmholtz-aai
Or install it directly from the source code repository on Gitlab via:
pip install git+https://gitlab.hzdr.de/hcdc/django/django-helmholtz-aai.git
The latter should however only be done if you want to access the development versions.
Register your OAuth-Client at the Helmholtz AAI
To install this app in your Django application, you first need to register an OAuth client for the Helmholtz AAI. In short, this works the following way
head over to https://login.helmholtz.de
make sure that you are logged out at the Helmholtz AAI
click No Acccount? Sign up on the top-right on , and then by
click on Oauth2/OIDC client Registration
register your client. For more information on the necessary fields, see [client-registration] in the Helmholtz AAI docs.
Note
Make sure that you enter the correct return URL which should be something like
https://<link-to-your-django-website>/helmholtz-aai/auth/
.The
/helmholtz-aai/
part is determined by the settings in your URL configuration down below. But you can also change this URL or add more once your client has been approved at https://login.helmholtz.de/oauthhome/
Install the Django App for your project
To use the django-helmholtz-aai package in your Django project, you need to add the app to your INSTALLED_APPS, configure your urls.py, run the migration, add a login button in your templates. Here are the step-by-step instructions:
Add the django_helmholtz_aai app to your INSTALLED_APPS
in your projects urlconf (see
ROOT_URLCONF
), add includedjango_helmholtz_aai.urls
via:from django.urls import include, path urlpatterns += [ path("helmholtz-aai/", include("django_helmholtz_aai.urls")), ]
Note that the
helmholtz-aai/
-part has to match what you entered when you registered your client (see above).Run
python manage.py migrate
to add theHelmholtzUser
andHelmholtzVirtualOrganization
models to your databaseAdd the link to the login view in one of your templates (e.g. in the login.html template from your
LOGIN_URL
), e.g. via{% load helmholtz_aai %} <a href="{% helmholtz_login_url %}"> login via Helmholtz AAI </a>
Note
To tell the user why he or should could not login, we are also using djangos
messaging
framework. Seedjango.contrib.messages
. To display these messages, you should add something in your django template, e.g. something like{% if messages %} <ul class="messages"> {% for message in messages %} <li{% if message.tags %} class="{{ message.tags }}"{% endif %}> {{ message }} </li> {% endfor %} </ul> {% endif %}
Make sure to set the
HELMHOLTZ_CLIENT_ID
andHELMHOLTZ_CLIENT_SECRET
settings in your settings.py with the username and password you specified during the client registration.
That’s it! For further adaption to you Django project, please head over to the
Configuration options. You can also have a look into the testproject
in the source code repository for a possible implementation.