App settings

This module defines the settings options for the django_helmholtz_aai app.

Data:

HELMHOLTZ_AAI_CONF_URL	openid configuration url of the Helmholtz AAI
HELMHOLTZ_ALLOWED_VOS	A string of lists specifying which VOs are allowed to log into the website.
HELMHOLTZ_ALLOWED_VOS_REGEXP	Regular expressions for VOs that are allowed to login to the website.
HELMHOLTZ_CLIENT_ID	Client id for the Helmholtz AAI
HELMHOLTZ_CLIENT_KWS	Keyword argument for the oauth client to connect with the helmholtz AAI.
HELMHOLTZ_CLIENT_SECRET	Client secret for the Helmholtz AAI
HELMHOLTZ_CREATE_USERS	Flag to enable/disable user account creation via the Helmholtz AAI.
HELMHOLTZ_EMAIL_DUPLICATES_ALLOWED	Allow duplicated emails for users in the website
HELMHOLTZ_MAP_ACCOUNTS	Flag whether existing user accounts should be mapped
HELMHOLTZ_UPDATE_USERNAME	Flag whether usernames should be updated from the Helmholtz AAI
HELMHOLTZ_USERNAME_FIELDS	Username fields in the userinfo
HELMHOLTZ_USER_BACKEND	The backend that is used to login the user.
ROOT_URL	Root url for the django application

django_helmholtz_aai.app_settings.HELMHOLTZ_AAI_CONF_URL = 'https://login.helmholtz.de/oauth2/.well-known/openid-configuration'

openid configuration url of the Helmholtz AAI

Can also be overwritten using the HELMHOLTZ_CLIENT_KWS setting.

django_helmholtz_aai.app_settings.HELMHOLTZ_ALLOWED_VOS: list[str] = []

A string of lists specifying which VOs are allowed to log into the website.

By default, this is an empty list meaning that each and every user is allowed to login via the Helmholtz AAI. Each string in this list will be interpreted as a regular expression and added to HELMHOLTZ_ALLOWED_VOS_REGEXP

Examples

Assume you only want to allow people from the Hereon VO to login to the website. Then you can add the following to your settings.py:

HELMHOLTZ_ALLOWED_VOS = [
    "urn:geant:helmholtz.de:group:hereon#login.helmholtz.de",
]

or use a regex, e.g. something like:

HELMHOLTZ_ALLOWED_VOS = [
    r".*helmholtz.de:group:hereon#login.helmholtz.de",
]

[]

django_helmholtz_aai.app_settings.HELMHOLTZ_ALLOWED_VOS_REGEXP: list[re.Pattern] = []

Regular expressions for VOs that are allowed to login to the website.

This attribute is created from the HELMHOLTZ_ALLOWED_VOS setting.

[]

django_helmholtz_aai.app_settings.HELMHOLTZ_CLIENT_ID: str = None

Client id for the Helmholtz AAI

This is the username you use to login at https://login.helmholtz.de/oauthhome/, see [client-registration] for how to create a client

See also

HELMHOLTZ_CLIENT_SECRET

django_helmholtz_aai.app_settings.HELMHOLTZ_CLIENT_KWS = {'client_id': None, 'client_kwargs': {'scope': 'profile email eduperson_unique_id'}, 'client_secret': None, 'server_metadata_url': 'https://login.helmholtz.de/oauth2/.well-known/openid-configuration'}

Keyword argument for the oauth client to connect with the helmholtz AAI.

Can also be overwritten using the HELMHOLTZ_CLIENT_KWS setting.

{
    'client_id': None,
    'client_kwargs': {'scope': 'profile email eduperson_unique_id'},
    'client_secret': None,
    'server_metadata_url': 'https://login.helmholtz.de/oauth2/.well-known/openid-configuration',
}

django_helmholtz_aai.app_settings.HELMHOLTZ_CLIENT_SECRET: str = None

Client secret for the Helmholtz AAI

This is the password you use to login at https://login.helmholtz.de/oauthhome/, see[client-registration]_ for how to create a client

See also

HELMHOLTZ_CLIENT_ID

django_helmholtz_aai.app_settings.HELMHOLTZ_CREATE_USERS: bool = True

Flag to enable/disable user account creation via the Helmholtz AAI.

Use this flag if you want the Helmholtz AAI to create users when they login for the first time. This is enabled by default.

If you disable this setting, you should enable the HELMHOLTZ_MAP_ACCOUNTS, otherwise nobody will be allowed to login via the Helmholtz AAI.

django_helmholtz_aai.app_settings.HELMHOLTZ_EMAIL_DUPLICATES_ALLOWED: bool = False

Allow duplicated emails for users in the website

This setting controls if a user can register with multiple accounts from the Helmholtz AAI. An email is not unique in the AAI, but this might be desired in the Django application. This option prevents a user to create an account if the email has already been taken by some other user from the Helmholtz AAI

django_helmholtz_aai.app_settings.HELMHOLTZ_MAP_ACCOUNTS: bool = False

Flag whether existing user accounts should be mapped

Use this flag, if you want to map existing user accounts by their email address.

Examples

Suppose you just install django-helmholtz-aai to your already existing Django project and there exists already a user with the mail user@example.com. If this user now logs into your project, it would create a new HelmholtzUser which is probably not desired. To overcome this, you can set the HELMHOLTZ_MAP_ACCOUNTS configuration variable to True and the HelmholtzUser will be mapped to the already existing User

django_helmholtz_aai.app_settings.HELMHOLTZ_UPDATE_USERNAME: bool = True

Flag whether usernames should be updated from the Helmholtz AAI

Use this setting to control, whether the usernames are updated automatically on every login. If this is true, we will check the fields specified in the HELMHOLTZ_USERNAME_FIELDS setting variable on every login and update the username accordingly. If the user, for instance, changes his or her preferred_username on https://login.helmholtz.de/, we will update the username of the django user as well (if preferred_username is in the HELMHOLTZ_USERNAME_FIELDS).

django_helmholtz_aai.app_settings.HELMHOLTZ_USERNAME_FIELDS: list[str] = ['preferred_username', 'eduperson_unique_id']

Username fields in the userinfo

This setting determines how to get the username. By default, we use the preferred_username that the user can configure at https://login.helmholtz.de/oauthhome. If this is already taken, we use the unique eduperson_unique_id from the Helmholtz AAI. You can add more variables to this list but you should always include the eduperson_unique_id to make sure you do not end up with duplicated usernames.

Examples

You can use the email instead of the preferred_username via:

HELMHOLTZ_USERNAME_FIELDS = ["email", "eduperson_unique_id"]

['preferred_username', 'eduperson_unique_id']

django_helmholtz_aai.app_settings.HELMHOLTZ_USER_BACKEND: str = 'django.contrib.auth.backends.ModelBackend'

The backend that is used to login the user. By default, we use the Django default, i.e. django.contrib.auth.backends.ModelBackend

django_helmholtz_aai.app_settings.ROOT_URL: str | None = None

Root url for the django application

The login requires a redirect url that is derived from the view with the name "django_helmholtz_aai:auth" and the protocoll and host name of your application. In case your application is behind a reverse proxy that does not forward correct host or protocoll, you can use this setting to set the URL manually.

Examples

If this app is included via path("helmholtz-aai/", include("django_helmholtz_aai.urls")) in your url-config and available at https://example.com/helmholtz-aai/, then the ROOT_URL in your settings.py should be https://example.com