mozilla-django-oidc

mozilla-django-oidc is a lightweight authentication and access management library designed for integration with OpenID Connect (OIDC) enabled authentication services. It is built with several core design principles:

• Minimalism: Keeps the footprint as lightweight as possible.
• Minimal State: Stores as few authentication/authorization artifacts as possible.
• Extensibility: Allows custom functionality by overriding the authentication backend.
• OIDC Focus: Primarily supports the OIDC authorization code flow.
• Security: E2E tested and audited by Mozilla InfoSec.

To ensure users are still authorized with the OIDC provider (e.g., if their corporate account was disabled), use the mozilla_django_oidc.middleware.SessionRefresh middleware. This middleware checks if the user's ID token has expired and, if so, performs a silent re-authentication by redirecting to the provider's authentication endpoint.

Add the middleware to your MIDDLEWARE setting. Note that middleware involving sessions and authentication must come before this one.

The expiration check interval is controlled by settings.OIDC_RENEW_ID_TOKEN_EXPIRY_SECONDS, which defaults to 15 minutes.

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

Include the library's URLs in your project's urls.py file using the oidc/ prefix.

from django.urls import path, include

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

Install the library using pip:

$ pip install mozilla-django-oidc

To contribute to the project, follow these steps to set up a local development environment with all necessary dependencies for testing and linting:

1. Fork the repository on GitHub.
2. Clone your fork locally.
3. Create and activate a virtual environment.
4. Install the package in editable mode with development dependencies using pip install -e .[dev].
5. Create a new branch for your work.

Before submitting changes, ensure you run make lint and make test (or tox) to verify your changes pass linting and tests across supported Python versions.

$ git clone git@github.com:your_name_here/mozilla-django-oidc.git
$ cd mozilla-django-oidc/
$ python -m venv .venv
$ source .venv/bin/activate  # On Windows use `.venv\Scripts\activate`
$ pip install -e .[dev]
$ git checkout -b name-of-your-bugfix-or-feature

To decide whether an authentication attempt should be allowed based on specific claim values (e.g., checking if a user belongs to a specific group), subclass mozilla_django_oidc.auth.OIDCAuthenticationBackend and override the verify_claims method. This method must return True to allow authentication or False to reject it.

class MyOIDCAB(OIDCAuthenticationBackend):
    def verify_claims(self, claims):
        verified = super(MyOIDCAB, self).verify_claims(claims)
        is_admin = 'admin' in claims.get('group', [])
        return verified and is_admin

To perform additional bookkeeping (like populating profile data from claims) when a user is created or updated, subclass mozilla_django_oidc.auth.OIDCAuthenticationBackend and override create_user and/or update_user.

from mozilla_django_oidc.auth import OIDCAuthenticationBackend
from myapp.models import Profile

class MyOIDCAB(OIDCAuthenticationBackend):
    def create_user(self, claims):
        user = super(MyOIDCAB, self).create_user(claims)

        user.first_name = claims.get('given_name', '')
        user.last_name = claims.get('family_name', '')
        user.save()

        return user

    def update_user(self, user, claims):
        user.first_name = claims.get('given_name', '')
        user.last_name = claims.get('family_name', '')
        user.save()

        return user

To allow Django REST Framework to authenticate users using an OAuth access token provided in the Authorization header, use the mozilla_django_oidc.contrib.drf.OIDCAuthentication class.

Add this class to your REST_FRAMEWORK settings under DEFAULT_AUTHENTICATION_CLASSES. It is common to include rest_framework.authentication.SessionAuthentication alongside it.

Important Limitations:

• This integration only handles authenticating against an existing access token.
• It does not provide functionality to create or renew tokens.

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'mozilla_django_oidc.contrib.drf.OIDCAuthentication',
        'rest_framework.authentication.SessionAuthentication',
        # other authentication classes, if needed
    ],
}

When submitting a pull request, ensure the following requirements are met:

1. Include tests: All new functionality must be accompanied by tests.
2. Update documentation: If adding functionality, update the relevant docs. New functionality should be placed in a function with a docstring, and the feature should be added to the list in README.rst.
3. Python Compatibility: Ensure the PR works for Python 3.10+. Verify that tests pass for all supported Python versions via GitHub Actions.
4. Update History: Update HISTORY.rst with your changes under the appropriate categories: Backwards-incompatible changes, Features, or Bugs.

By default, the library only ends the Django session. To also end the session at the OIDC provider, implement a function and assign it to settings.OIDC_OP_LOGOUT_URL_METHOD. This function should return the URL where the user should be redirected to log out of the provider.

def provider_logout(request):
    # See your provider's documentation for details
    redirect_url = 'https://myprovider.com/logout'
    return redirect_url

# In settings.py:
# OIDC_OP_LOGOUT_URL_METHOD = 'myapp.auth_utils.provider_logout'