mozilla-django-oidc-db 0.12.0

3.1 Requirements

• Python 3.7 or above

• setuptools 30.4.0 or above

• Django 3.2 or newer

• A database supporting models.JSONField

3.2 Install

pip install mozilla-django-oidc-db

This will also install the following packages:

• mozilla-django-oidc

• django-solo

• django-better-admin-arrayfield

3.3 Django settings

Make sure the following libraries are added to your INSTALLED_APPS:

INSTALLED_APPS = [
    ...
    "django_better_admin_arrayfield",
    "solo",
    "mozilla_django_oidc",
    "mozilla_django_oidc_db",
    ...
]

Add mozilla_django_oidc_db.backends.OIDCAuthenticationBackend to the AUTHENTICATION_BACKENDS, this backend replaces mozilla_django_oidc.auth.OIDCAuthenticationBackend:

AUTHENTICATION_BACKENDS = [
    ...
    "mozilla_django_oidc_db.backends.OIDCAuthenticationBackend",
    ...
]

Ensure that LOGIN_REDIRECT_URL and LOGOUT_REDIRECT_URL are configured. For example:

LOGIN_REDIRECT_URL = reverse_lazy("admin:index")
LOGOUT_REDIRECT_URL = reverse_lazy("admin:index")

To enable validation of ID tokens by renewing them, add mozilla_django_oidc_db.middleware.SessionRefresh to the middleware, this middleware replaces mozilla_django_oidc.middleware.SessionRefresh:

MIDDLEWARE = [
    # middleware involving session and authentication must come first
    ...
    "mozilla_django_oidc_db.middleware.SessionRefresh",
    ...
]

Furthermore, ensure the following settings are configured:

OIDC_AUTHENTICATE_CLASS = "mozilla_django_oidc_db.views.OIDCAuthenticationRequestView"
OIDC_CALLBACK_CLASS = "mozilla_django_oidc_db.views.OIDCCallbackView"
MOZILLA_DJANGO_OIDC_DB_CACHE = "oidc"
MOZILLA_DJANGO_OIDC_DB_CACHE_TIMEOUT = 1

In order to properly catch admin login errors, add the following to urlpatterns:

from mozilla_django_oidc_db.views import AdminLoginFailure

urlpatterns = [
    ...
    path("admin/login/failure/", AdminLoginFailure.as_view(), name="admin-oidc-error"),
    ...
]

MOZILLA_DJANGO_OIDC_DB_CACHE is used to cache the configuration that is stored in the database, to prevent a lot of database lookups. Ensure this cache is configured in CACHES (using the backend of choice):

CACHES = {
    "default": {"BACKEND": "django.core.cache.backends.locmem.LocMemCache"},
    ...
    "oidc": {"BACKEND": "django.core.cache.backends.locmem.LocMemCache"},
}

Add the urlpatterns:

urlpatterns = [
    ...
    path("oidc/", include("mozilla_django_oidc.urls")),
    ...
]

Add the login link to your templates:

{% get_solo 'mozilla_django_oidc_db.OpenIDConnectConfig' as oidc_config %}
{% if oidc_config.enabled %}
<div class="submit-row">
    <a href="{% url 'oidc_authentication_init' %}">{% trans "Login with OIDC" %}</a>
</div>
{% endif %}

4.1 User profile

In order to set certain attributes on the User object, a claim_mapping can be specified via the admin. This maps the names of claims returned by the OIDC provider to fields on the User model, and whenever a User is created/updated, these fields will be set to the values of these claims.

4.2 Assigning users to groups

When users are created/updated, they can be automatically assigned to Groups by checking the Synchronize groups option in the admin and setting the appropriate value for Groups claim, which is the name of the claim that contains the groups the user is assigned to by the OIDC provider.

Additionally, a groups glob pattern can be supplied to only sync groups with specific names (default *, to match all groups).

NOTE: The names of the groups in the environment of the OIDC provider must match exactly with the names of the Groups in Django for this to work.

4.3 Custom username claim

The name of the claim that is used for the User.username property can be configured via the admin. By default, the username is derived from the sub claim that is returned by the OIDC provider.

If the desired claim is nested in one or more objects, its path can be specified with dots, e.g.:

{
    "some": {
        "nested": {
            "claim": "foo"
        }
    }
}

Can be retrieved by setting the username claim to some.nested.claim

NOTE: the username claim does not support claims that have dots in their name, it cannot be configured to retrieve the following claim for instance:

{
    "some.dotted.claim": "foo"
}

4.4 User information claims source

There are currently two methods to extract information about the authenticated user, controlled by the User information claims extracted from option.

• Userinfo endpoint, this is the default method (this is also the default behavior in mozilla-django-oidc)

• ID token, to extract the claims from the ID token. This could be preferable in the case where the authentication server passes sensitive claims (that should not be stored in the authentication server itself) via the ID token

4.5 Claim obfuscation

By default, the received claims will be logged when verifying them during the authentication process. In order to not log information from sensitive claims (identifiers, etc.), claims can be obfuscated by setting OIDCAuthenticationBackend.sensitive_claim_names or overriding OIDCAuthenticationBackend.get_sensitive_claim_names. By default, the configured OIDCAuthenticationBackend.config_identifier_field will be obfuscated.

4.6 Customizing the configuration

The database-stored configuration class can easily be extended by inheriting from the OpenIDConnectConfigBase class and then setting the OIDCAuthenticationRequestView.config_class and OIDCAuthenticationBackend.config_class to be this new class.