Mozilla Django OIDC

Warnings

• breaking Version 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.
• breaking Version 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.
• breaking Version 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`.
• gotcha The 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.
• gotcha By 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.

Install

• pip install mozilla-django-oidc Install latest version

Imports

• OIDCAuthenticationBackend

  from mozilla_django_oidc.auth import OIDCAuthenticationBackend

  Used in AUTHENTICATION_BACKENDS setting.
• OIDCAuthenticationRequestView

  from mozilla_django_oidc.views import OIDCAuthenticationRequestView

  Default view for initiating OIDC authentication.
• urls

  from mozilla_django_oidc import urls

  Typically included in `urlpatterns` via `path('oidc/', include(mozilla_django_oidc.urls))`.

Quickstart

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 %}