Registry / auth-security / mozilla-django-oidc

mozilla-django-oidc

JSON →
library5.0.2pypypi✓ verified 22d ago

mozilla-django-oidc is a lightweight authentication and access management library for integrating Django applications with OpenID Connect enabled authentication services. It is actively maintained with frequent updates, currently at version 5.0.2, and typically releases new versions to support new Django and Python versions.

pip install mozilla-django-oidc
INSTALL
IMPORT
SIG · MOZILLA-DJANGO-OID
M
mozilla-django-oidc
auth-securitypythonv5.0.2
Install
5.0s avg
Import
Disk
87MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v5.0.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 86.9MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 5.0s · import 0.000s · 87MB
87MB installed
● package 87MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

OIDCAuthenticationBackend
from mozilla_django_oidc.auth import OIDCAuthenticationBackend
from mozilla_django_oidc.auth import OIDCAuthenticationBackend

This quickstart outlines the essential `settings.py` and `urls.py` configurations. You must add `mozilla_django_oidc` to `INSTALLED_APPS` and include its `OIDCAuthenticationBackend` in `AUTHENTICATION_BACKENDS`. Critical OIDC provider (OP) and relying party (RP) details (`OIDC_OP_*`, `OIDC_RP_CLIENT_ID`, `OIDC_RP_CLIENT_SECRET`) must be provided, ideally via environment variables for security. The library's URLs are included via `path('oidc/', include('mozilla_django_oidc.urls'))`. Basic login and logout links can then be added to your templates.

# settings.py import os INSTALLED_APPS = [ # ... 'django.contrib.auth', 'mozilla_django_oidc', # ... ] AUTHENTICATION_BACKENDS = ( 'mozilla_django_oidc.auth.OIDCAuthenticationBackend', 'django.contrib.auth.backends.ModelBackend', ) # OpenID Connect Provider (OP) settings - REQUIRED OIDC_OP_AUTHORIZATION_ENDPOINT = os.environ.get('OIDC_OP_AUTHORIZATION_ENDPOINT', 'https://your-op.com/auth') OIDC_OP_TOKEN_ENDPOINT = os.environ.get('OIDC_OP_TOKEN_ENDPOINT', 'https://your-op.com/token') OIDC_OP_USER_ENDPOINT = os.environ.get('OIDC_OP_USER_ENDPOINT', 'https://your-op.com/userinfo') OIDC_OP_JWKS_ENDPOINT = os.environ.get('OIDC_OP_JWKS_ENDPOINT', 'https://your-op.com/jwks') # Relying Party (RP) / Client settings - REQUIRED OIDC_RP_CLIENT_ID = os.environ.get('OIDC_RP_CLIENT_ID', 'your-client-id') OIDC_RP_CLIENT_SECRET = os.environ.get('OIDC_RP_CLIENT_SECRET', 'your-client-secret') # Optional settings for redirection after login/logout LOGIN_REDIRECT_URL = '/' LOGOUT_REDIRECT_URL = '/' # urls.py (in your project's root urls.py) from django.contrib import admin from django.urls import path, include urlpatterns = [ path('admin/', admin.site.urls), path('oidc/', include('mozilla_django_oidc.urls')), # Your other app URLs path('', lambda request: HttpResponse("Welcome! <a href='/oidc/authenticate/'>Login</a> or <a href='/oidc/logout/'>Logout</a>"), name='home'), ] # In a simple template (e.g., base.html) add login/logout links: # {% if user.is_authenticated %} # <p>Hello, {{ user.username }}!</p> # <a href="{% url 'oidc_logout' %}">Log Out</a> # {% else %} # <a href="{% url 'oidc_authentication_init' %}">Log In with OIDC</a> # {% endif %}
Debug
Known issues
breakingVersion 5.0.0 replaced the `josepy` library with `PyJWT` for JWT handling. If your application had custom code interacting with `josepy` internals, it will break.
fix
Review any custom JWT processing logic and update it to use `PyJWT` or `mozilla-django-oidc`'s updated internal mechanisms.
affects: 5.0.0+
breakingVersion 5.0.0 changed how `LOGOUT_REDIRECT_URL` is resolved to be compatible with `django.contrib.auth`. This change might affect logout redirection behavior, especially if `LOGOUT_REDIRECT_URL` was not explicitly set or relied on previous default behavior.
fix
Ensure `LOGOUT_REDIRECT_URL` is explicitly set in your `settings.py` to the desired post-logout destination. If not set, it might cause an error or unexpected redirects.
affects: 5.0.0+
breakingVersion 5.0.0 dropped support for Django 3.2, Python 3.8, and Python 3.9. Version 4.0.0 dropped support for Python 3.7 and Django 4.1.
fix
Upgrade your Django installation to at least 4.2 and your Python version to at least 3.10 to be compatible with current versions of `mozilla-django-oidc`.
affects: 4.0.0+, 5.0.0+
gotchaThe library requires several essential OIDC settings (e.g., `OIDC_OP_AUTHORIZATION_ENDPOINT`, `OIDC_RP_CLIENT_ID`, `OIDC_RP_CLIENT_SECRET`) to be explicitly defined in `settings.py`. These are not optional and do not have sensible defaults.
fix
Always define all required `OIDC_OP_*` and `OIDC_RP_CLIENT_*` settings. It is highly recommended to fetch sensitive values like `OIDC_RP_CLIENT_SECRET` from environment variables, not hardcode them.
affects: All
gotchaBy default, `mozilla-django-oidc` creates a Django user by hashing the email address for the username field. If you require a different username generation algorithm or want to use a specific claim (like `preferred_username` or `sub`), you must configure `OIDC_USERNAME_ALGO` or subclass `OIDCAuthenticationBackend` and override the `create_user` method.
fix
For custom username generation, set `OIDC_USERNAME_ALGO` to a Python dotted path to your custom function, or override `OIDCAuthenticationBackend.create_user` or `filter_users_by_claims` for more complex scenarios.
affects: All
Upgrade
Version history
5.0.2latest on PyPI · released Dec 19, 2025
Audit
Dependencies
DjangorequiredCore framework integration. Requires Django >= 4.2.
PyJWTrequiredHandles JSON Web Token (JWT) encoding and decoding. Replaced 'josepy' in 5.0.0.
requestsrequiredHTTP library for making requests to the OpenID Connect provider.
cryptographyrequiredUnderpins cryptographic operations for JWT verification.
Agent activity
21 hits · last 30 days
node
18
OpenAI (training)
1
Resources
mozilla-django-oidc — pip install mozilla-django-oidc · libregistry