Django OAuth Toolkit

3.2.0 · active · verified Thu Apr 09

Django OAuth Toolkit (DOT) is a Python library that provides OAuth2 capabilities to Django projects, offering out-of-the-box endpoints, data, and logic for robust authorization. It leverages OAuthLib to ensure RFC-compliance and is currently at version 3.2.0. The project is actively maintained with regular releases, supporting recent Django and Python versions.

Warnings

breaking Upgrading to version 3.0.0 or later requires running `manage.py migrate` due to significant changes in the `AbstractAccessToken` model. Custom swappable models based on `AbstractAccessToken` will also need to be updated and re-migrated.
Fix: Run `python manage.py migrate` after upgrading. If using custom swappable models, ensure they are compatible with the new base model and create/apply migrations for them (e.g., `python manage.py makemigrations your_app_name`). Also note minimum Django version is 4.2+ for 3.x.
breaking Beginning with version 2.0.0, client secrets are hashed upon save. If you need the cleartext secret (e.g., for testing or specific OIDC configurations), you must copy it *before* saving an application in the Django admin. Also, `PKCE_REQUIRED` is now `True` by default, leading to 'invalid_client' errors for clients not using PKCE.
Fix: When creating/editing an application, copy the client secret before saving if you need its unhashed value. For clients not supporting PKCE, set `OAUTH2_PROVIDER = {'PKCE_REQUIRED': False}` in your Django settings to revert to the pre-2.x behavior. It is recommended to implement PKCE where possible for enhanced security.
gotcha The project transitioned from the `jazzband` GitHub organization to `django-oauth` starting with version 3.1.0. While the PyPI package name (`django-oauth-toolkit`) remains the same, this indicates a change in project governance and potentially development practices.
Fix: No direct code change is typically required for existing installations. Be aware of the new organization when seeking support, contributing, or referencing project repositories.
gotcha If you plan to use a custom `Application` model (by setting `OAUTH2_PROVIDER_APPLICATION_MODEL` in settings), you *must* define and run the migration for your custom model *before* running the initial `oauth2_provider` migrations. Failing to do so will result in system check errors.
Fix: Ensure your custom application model is defined and its migrations are created and applied (potentially with a `run_before` dependency on `oauth2_provider`'s initial migration) before running `python manage.py migrate` for `oauth2_provider`.

Install

pip install django-oauth-toolkit Install stable version

Imports

urls
```
from oauth2_provider import urls as oauth2_urls
```
Used to include Django OAuth Toolkit's URL patterns in your project's urls.py.
views
```
from oauth2_provider import views as oauth2_views
```
Required when overriding or directly referencing built-in views like AuthorizationView or TokenView.
AbstractApplication
```
from oauth2_provider.models import AbstractApplication
```
Use this to extend the default Application model with custom fields.
OAuth2TokenMiddleware
```
from oauth2_provider.middleware import OAuth2TokenMiddleware
```
Essential for token-based authentication in Django's middleware stack.
OAuth2Backend
```
from oauth2_provider.backends import OAuth2Backend
```
Enables OAuth2 authentication for Django's authentication backends.

Quickstart

To quickly set up Django OAuth Toolkit, first install it along with `django-cors-headers` (if needed for cross-origin requests). Add `oauth2_provider` and `corsheaders` to `INSTALLED_APPS`. Configure `MIDDLEWARE` to include `OAuth2TokenMiddleware` and `CorsMiddleware`. Add `OAuth2Backend` to `AUTHENTICATION_BACKENDS`. Finally, include `oauth2_provider` URLs in your project's `urls.py`. Remember to run `python manage.py makemigrations` and `python manage.py migrate` to apply database changes. After migration, you can register OAuth2 applications via the Django admin at `/o/applications/`.

import os

# settings.py
INSTALLED_APPS = [
    # ... other apps
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'oauth2_provider',
    'corsheaders', # If using django-cors-headers
]

MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'corsheaders.middleware.CorsMiddleware', # If using django-cors-headers
    'django.middleware.common.CommonMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'oauth2_provider.middleware.OAuth2TokenMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    'django.middleware.clickjacking.XFrameOptionsMiddleware',
]

AUTHENTICATION_BACKENDS = [
    'oauth2_provider.backends.OAuth2Backend',
    'django.contrib.auth.backends.ModelBackend', # Required for Django admin login
]

# urls.py
from django.contrib import admin
from django.urls import include, path
from oauth2_provider import urls as oauth2_urls

urlpatterns = [
    path('admin/', admin.site.urls),
    path('o/', include(oauth2_urls)),
    # Your other app URLs
]

# Configure CORS if needed (e.g., for local development or specific clients)
CORS_ORIGIN_ALLOW_ALL = True # WARNING: Set to specific origins in production

view raw JSON →