Installation

To install the django-helmholtz-aai package for your Django project, you need to follow three steps:

  1. Install the package

  2. Register an OAuth-client

  3. Add the app to your Django project

Installation from PyPi

The recommended way to install this package is via pip and PyPi via:

pip install django-helmholtz-aai

or, if you are using pipenv, via:

pipenv install django-helmholtz-aai

Or install it directly from the source code repository on Gitlab via:

pip install git+https://codebase.helmholtz.cloud/hcdc/django/django-helmholtz-aai.git

The latter should however only be done if you want to access the development versions (see Installation for development).

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

  1. head over to https://login.helmholtz.de

  2. make sure that you are logged out at the Helmholtz AAI

  3. click No Acccount? Sign up on the top-right on , and then by

  4. click on Oauth2/OIDC client Registration

  5. 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:

  1. Add the django_helmholtz_aai app to your INSTALLED_APPS

  2. in your projects urlconf (see ROOT_URLCONF), add include django_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).

  3. Run python manage.py migrate to add models to your database

  4. Add 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. See django.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 %}

  5. Make sure to set the HELMHOLTZ_CLIENT_ID and HELMHOLTZ_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.

Installation for development

Please head over to our contributing guide for installation instruction for development.

References