{"id":4988,"library":"mozilla-django-oidc","title":"Mozilla Django OIDC","description":"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.","status":"active","version":"5.0.2","language":"en","source_language":"en","source_url":"https://github.com/mozilla/mozilla-django-oidc","tags":["django","oidc","authentication","sso","security"],"install":[{"cmd":"pip install mozilla-django-oidc","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core framework integration. Requires Django >= 4.2.","package":"Django","optional":false},{"reason":"Handles JSON Web Token (JWT) encoding and decoding. Replaced 'josepy' in 5.0.0.","package":"PyJWT","optional":false},{"reason":"HTTP library for making requests to the OpenID Connect provider.","package":"requests","optional":false},{"reason":"Underpins cryptographic operations for JWT verification.","package":"cryptography","optional":false}],"imports":[{"note":"Used in AUTHENTICATION_BACKENDS setting.","symbol":"OIDCAuthenticationBackend","correct":"from mozilla_django_oidc.auth import OIDCAuthenticationBackend"},{"note":"Default view for initiating OIDC authentication.","symbol":"OIDCAuthenticationRequestView","correct":"from mozilla_django_oidc.views import OIDCAuthenticationRequestView"},{"note":"Typically included in `urlpatterns` via `path('oidc/', include(mozilla_django_oidc.urls))`.","symbol":"urls","correct":"from mozilla_django_oidc import urls"}],"quickstart":{"code":"# settings.py\nimport os\n\nINSTALLED_APPS = [\n    # ...\n    'django.contrib.auth',\n    'mozilla_django_oidc',\n    # ...\n]\n\nAUTHENTICATION_BACKENDS = (\n    'mozilla_django_oidc.auth.OIDCAuthenticationBackend',\n    'django.contrib.auth.backends.ModelBackend',\n)\n\n# OpenID Connect Provider (OP) settings - REQUIRED\nOIDC_OP_AUTHORIZATION_ENDPOINT = os.environ.get('OIDC_OP_AUTHORIZATION_ENDPOINT', 'https://your-op.com/auth')\nOIDC_OP_TOKEN_ENDPOINT = os.environ.get('OIDC_OP_TOKEN_ENDPOINT', 'https://your-op.com/token')\nOIDC_OP_USER_ENDPOINT = os.environ.get('OIDC_OP_USER_ENDPOINT', 'https://your-op.com/userinfo')\nOIDC_OP_JWKS_ENDPOINT = os.environ.get('OIDC_OP_JWKS_ENDPOINT', 'https://your-op.com/jwks')\n\n# Relying Party (RP) / Client settings - REQUIRED\nOIDC_RP_CLIENT_ID = os.environ.get('OIDC_RP_CLIENT_ID', 'your-client-id')\nOIDC_RP_CLIENT_SECRET = os.environ.get('OIDC_RP_CLIENT_SECRET', 'your-client-secret')\n\n# Optional settings for redirection after login/logout\nLOGIN_REDIRECT_URL = '/'\nLOGOUT_REDIRECT_URL = '/'\n\n# urls.py (in your project's root urls.py)\nfrom django.contrib import admin\nfrom django.urls import path, include\n\nurlpatterns = [\n    path('admin/', admin.site.urls),\n    path('oidc/', include('mozilla_django_oidc.urls')),\n    # Your other app URLs\n    path('', lambda request: HttpResponse(\"Welcome! <a href='/oidc/authenticate/'>Login</a> or <a href='/oidc/logout/'>Logout</a>\"), name='home'),\n]\n\n# In a simple template (e.g., base.html) add login/logout links:\n# {% if user.is_authenticated %}\n#   <p>Hello, {{ user.username }}!</p>\n#   <a href=\"{% url 'oidc_logout' %}\">Log Out</a>\n# {% else %}\n#   <a href=\"{% url 'oidc_authentication_init' %}\">Log In with OIDC</a>\n# {% endif %}\n","lang":"python","description":"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."},"warnings":[{"fix":"Review any custom JWT processing logic and update it to use `PyJWT` or `mozilla-django-oidc`'s updated internal mechanisms.","message":"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.","severity":"breaking","affected_versions":"5.0.0+"},{"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.","message":"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.","severity":"breaking","affected_versions":"5.0.0+"},{"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`.","message":"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.","severity":"breaking","affected_versions":"4.0.0+, 5.0.0+"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}