Skip to main content

A database-backed configuration for mozilla-django-oidc

Project description

1 Welcome to mozilla_django_oidc_db’s documentation!

Version:

0.14.1

Source:

https://github.com/maykinmedia/mozilla-django-oidc-db

Keywords:

OIDC, django, database, authentication

PythonVersion:

3.7

build-status Coverage status black

python-versions django-versions pypi-version

Database-backed settings for mozilla-django-oidc, with modified unique identifiers

2 Features

  • Thin layer on top of mozilla-django-oidc

  • Allows configuration of OpenID Connect variables via django-solo

  • Overrides mozilla-django-oidc default behaviour, using the sub claim instead of the email claim as unique identifier for users

mozilla-django-oidc-db provides a database singleton for several configuration variables required for mozilla-django-oidc, moving them from deploy-time to run-time. This enables modification of the configuration, without having to restart the application.

Additionally, mozilla-django-oidc-db by default uses the sub (subject) claim instead of the email claim as the unique identifier for users in the RP (Relying Party) application. Using email as the unique identifier is not recommended, as mentioned in the OpenID Connect specification.

3 Installation

3.1 Requirements

  • Python 3.7 or above

  • setuptools 30.4.0 or above

  • Django 3.2 or newer

  • A database supporting models.JSONField

  • If you’re using Django 4.1 or newer, you need at least mozilla-django-oidc 3.0. 2.0 is still supported with Django 3.2.

3.2 Install

pip install mozilla-django-oidc-db

This will also install the following packages:

  • mozilla-django-oidc

  • django-solo

  • django-jsonform

3.3 Django settings

Make sure the following libraries are added to your INSTALLED_APPS:

INSTALLED_APPS = [
    ...
    "django_jsonform",
    "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 Usage

Now OpenID Connect can be enabled/disabled via the admin (disabled by default) and the following settings for OpenID Connect can be configured in the admin:

  • oidc_rp_client_id

  • oidc_rp_client_secret

  • oidc_rp_sign_algo

  • oidc_rp_scopes_list

  • oidc_op_discovery_endpoint

  • oidc_op_jwks_endpoint

  • oidc_op_authorization_endpoint

  • oidc_op_token_endpoint

  • oidc_op_user_endpoint

  • oidc_rp_idp_sign_key

If the oidc_op_discovery_endpoint is supplied, the other endpoints will be derived from this discovery endpoint.

In case no value is provided for one of these variables, the default from mozilla-django-oidc will be used (if there is one). A detailed description of all settings can be found in the mozilla-django-oidc settings documentation

For more detailed documentation, refer to the mozilla-django-oidc documentation. In this documentation the origin of the admin configurable settings is also explained.

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mozilla-django-oidc-db-0.14.1.tar.gz (31.8 kB view details)

Uploaded Source

Built Distribution

mozilla_django_oidc_db-0.14.1-py3-none-any.whl (40.8 kB view details)

Uploaded Python 3

File details

Details for the file mozilla-django-oidc-db-0.14.1.tar.gz.

File metadata

File hashes

Hashes for mozilla-django-oidc-db-0.14.1.tar.gz
Algorithm Hash digest
SHA256 7a2ff7354af98778d4819cd428758cdc23d1e3f6b29f101638da7a7ecac9e205
MD5 55a8cd23d44c8d22f5bcf51607bbc567
BLAKE2b-256 ad089c78392ea0d28a18e98d902825cffd36b51b748e0dab1fd68d9a14b40f5c

See more details on using hashes here.

File details

Details for the file mozilla_django_oidc_db-0.14.1-py3-none-any.whl.

File metadata

File hashes

Hashes for mozilla_django_oidc_db-0.14.1-py3-none-any.whl
Algorithm Hash digest
SHA256 563edbb39240bf1e8b4e3dfe2e85267530d4151715b943a2179a8ec53570cab8
MD5 4a4fb3cf79fe1fe98e8b5c10cf1b5b31
BLAKE2b-256 4e2e32edb8097579ea62b1a414aa03bad74454628a671a4ab2bd89cedf9d4e6a

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page