PyPI · #1822 most downloaded on PyPI

django-oauth-toolkit

3.4.14.8M downloads/modjango-oauth/django-oauth-toolkit ↗New releases in your daily digest, changelog included.

OAuth 2.0 authorization server for Django

Last release 1 months ago
21 Aug 2026
Release timing varies
gaps range from 4 weeks to 13 months
Nearly every release is documented
notes for 50 of 51 stable releases
1 version withdrawn
withdrawn after publishing
13 years old
52 releases · first in 2013

Release timeline

52 releases since 2013

2013201520172019

Releases

3.4.121 Aug 20263 sources agree
This release is dominated by security hardening of redirect URI matching, token revocation and refresh token handling . Several entries below change b
This release is dominated by security hardening of redirect URI matching, token revocation and
refresh token handling. Several entries below change behavior that was previously accepted, and
they are spread across Fixed and Security: the "Upgrading to 3.4.1" section of the
Upgrading guide collects everything you need to act on in one place, so start there. Of particular
note: redirect URIs are now matched exactly per
RFC 9700 §2.1, so a request may no
longer carry query parameters, path parameters, credentials or a fragment that the registered URI
does not have; REFRESH_TOKEN_EXPIRE_SECONDS, where set, is now enforced when a refresh token is
presented rather than only by the cleartokens sweep; and the built-in templates now link a
stylesheet shipped with the package instead of a CDN, so run collectstatic or the pages render
unstyled.

Added

#681 Redirect URI mismatches are now diagnosed on the oauth2_provider logger at DEBUG,
reporting the requested URI, every registered candidate it was compared against, and which
component of each one differed (scheme, hostname, port, path, query). The same detail is
emitted for post_logout_redirect_uri and for the token endpoint's comparison against the
URI recorded on the grant. The error response is unchanged: the registered URIs are never
disclosed to the requester, only to the server's log. See "Debugging redirect URI
mismatches" in the documentation. Note that AbstractApplication.redirect_uri_allowed()
and post_logout_redirect_uri_allowed() now call the new check_redirect_to_uri_allowed()
(same verdict, plus the mismatch reasons) instead of redirect_to_uri_allowed(), so code
that wrapped or patched the latter to influence those methods must target the former.

#634 A system check (oauth2_provider.W011) that warns when the AccessToken and
RefreshToken models are swapped into different apps, and a new
"Extending the token models" documentation section explaining how to swap the
interrelated token models together.

#1623 Documentation ("Content Security Policy and the authorization form") on completing
the authorization-code flow under a strict form-action Content Security Policy, which
Chromium enforces against the post-authorization redirect to the client's redirect_uri.

#410 Documentation ("Resource scope syntax") clarifying that TokenHasResourceScope
checks each required_scopes entry suffixed with the READ_SCOPE/WRITE_SCOPE setting
value (defaults read/write, e.g. music:read, music:write), so a bare music scope
is rejected; with the default settings-based scopes backend the suffixed scopes must be
declared in SCOPES.

#1157 An "Upgrading" documentation page collecting the breaking changes and upgrade steps for
every release that needs them — 2.0, 3.0 and this release — linked from the documentation index,
so upgrade guidance is discoverable outside the CHANGELOG. A release that asks nothing of you has
no section there, so a gap between two versions is an answer rather than an omission.

#452 Documentation ("Custom scopes backend") explaining how to replace the default
settings-driven scopes backend via SCOPES_BACKEND_CLASS, including a worked model-based
example that stores scopes in the database.

#1045 Tutorial ("Managing applications and tokens in the Django admin") walking through the
admin site for applications and issued tokens, including client-secret hashing, credential
masking, and that tokens cannot be created by hand.

#403 Translatable (gettext_lazy) verbose_name labels on every field of the
Application, Grant, AccessToken, RefreshToken, IDToken and DeviceGrant models, so
the Django admin and the authorization UI can be localized. Migration
oauth2_provider.0021_translatable_field_labels records the label changes; it makes no
database schema changes.

Deprecated

#1773 JSONOAuthLibCore (OAUTH2_PROVIDER["OAUTH2_BACKEND_CLASS"] set to
oauth2_provider.oauth2_backends.JSONOAuthLibCore) is deprecated and now emits a
DeprecationWarning. It makes the OAuth token, introspection, and
revocation endpoints read application/json bodies, but those endpoints are defined to
use application/x-www-form-urlencoded (RFC 6749, RFC 7662, RFC 7009); the JSON mode is
non-standard and breaks interoperability with spec-compliant clients. It is scheduled for
removal in 4.0.

Changed

#1343 Application.clean() now reports its validation errors per field instead of as
non-field errors, and reports all of them at once instead of stopping at the first
problem. The application forms (the built-in registration/edit views and the Django
admin) render each message next to the offending input — a rejected redirect URI on
redirect_uris, a non-https CORS origin on allowed_origins, an unusable algorithm on
algorithm, and the HS256 client-secret conflicts on client_secret /
hash_client_secret. ValidationError.message_dict is keyed by those field names, so
callers of Application.full_clean() (including dynamic client registration and CIMD)
now surface the field name alongside the message. A custom ModelForm that omits one of
those fields still gets the message as a non-field error, provided it subclasses
oauth2_provider.forms.ApplicationForm.

#730 The templates shipped with the toolkit no longer load Bootstrap 2.3.2 from a
third-party CDN. oauth2_provider/base.html now links a small stylesheet distributed
with the package (static/oauth2_provider/css/oauth2_provider.css), which also absorbs
the inline <style> block that template carried. The built-in pages therefore render in
air-gapped installs and under a strict Content Security Policy such as
default-src 'self', which blocks a foreign style host and an inline style block alike,
and the authorization page no longer makes an unpinned (no Subresource Integrity)
third-party request while the user is making a consent decision. The stylesheet is served
through staticfiles, so run collectstatic for the pages to be styled. The Bootstrap 2
class names used by the templates are unchanged, and the css block of base.html is
still the supported way to substitute your own styles.

The AccessToken and RefreshToken admins now invalidate tokens through a "Revoke selected"
action instead of raw delete (delete is disabled on those two admins). A raw delete of an access
token left its bound refresh token behind (RefreshToken.access_token is SET_NULL) — an orphan
that could still mint new access tokens — and a raw delete of a refresh token discarded the
revoked tombstone that REFRESH_TOKEN_REUSE_PROTECTION relies on. The revoke action invalidates
the whole token family consistently; expired rows are still pruned by cleartokens. Grant and
IDToken admins keep the default delete. The access-token revoke logic is now a single shared
oauth2_provider.models.revoke_access_token() helper used by the admin action, the /revoke/
endpoint, and AuthorizedTokenDeleteView.

#522 The cleartokens management command now prints a warning to stderr when
REFRESH_TOKEN_EXPIRE_SECONDS is unset (or 0), explaining that only revoked and
orphaned refresh tokens are removed and that expired access/ID tokens still bound to a
refresh token are retained until that refresh token is gone. The management-command docs
were clarified to match.

#746 Revoking an access token (via the RFC 7009 /revoke/ endpoint) now also revokes
the refresh token bound to it, matching the admin "delete access token" view and
RFC 7009 §2.1. Previously the refresh token survived and could immediately mint a new
access token, defeating the revocation and leaving the refresh token an active "orphan"
(its access_token foreign key is SET_NULL). Whether a refresh token may survive
access-token revocation will become a configurable policy in 4.0.

#1715 Security guidance in the settings reference: recommend a finite
REFRESH_TOKEN_EXPIRE_SECONDS as defense-in-depth (rotation remains the primary
mitigation), and document why OIDC_RP_INITIATED_LOGOUT_ACCEPT_EXPIRED_TOKENS defaults
to True (the id_token_hint is a previously issued token per OIDC RP-Initiated Logout)
and how to harden it.

Fixed

The system check that verifies the AccessToken, IDToken, and RefreshToken models are
routed to a single database is now registered under the models tag instead of database.
Django 6.1 stopped running database-tagged checks unless a database alias is passed
explicitly (manage.py check --database default), because such checks may do more than
static analysis; this one only asks the configured routers where the token models would be
written and never opens a connection, so under the old tag a plain manage.py check would
have silently stopped reporting a cross-database token configuration on Django 6.1.

#1809 REFRESH_TOKEN_REUSE_PROTECTION now revokes a compromised token family as a set
instead of one row at a time. A rotating client keeps every refresh token it has ever been
issued in the same family, so the old per-row loop cost one SELECT ... FOR UPDATE round
trip per token in the family, paid again on every replay of the stale token: a client stuck
on a retry timer could hold a worker and a database connection for tens of seconds per
request. The sweep now runs in a fixed number of queries whatever the size of the family,
through the new AbstractRefreshToken.revoke_family(), and token_family is indexed
(migration 0022_refreshtoken_token_family_index) so it no longer scans the whole refresh
token table. What gets revoked is unchanged: every live member of the family, and the
family's access tokens. If you swap in your own refresh token model, run makemigrations to
pick up the index, and if you override revoke() override revoke_family() to match.
Where a family holds two live tokens sharing a checksum -- which RefreshToken's
(token_checksum, revoked) uniqueness permits but the bulk write cannot express (#1816) --
the sweep falls back to revoking row by row, so reuse detection still returns
invalid_grant rather than raising.

#1796 Redirect URIs using an RFC 8252 §7.1 private-use URI scheme can now be registered.
Such a scheme has no naming authority, so only a single slash follows it
(com.example.app:/oauth2redirect), but Application.clean() reassembled every URI with
:// before validating and rejected the result with "Enter a valid URL." — leaving native
apps no way to register the form the RFC prescribes and their clients actually send. The
double-slash variant was not a workaround: the two spellings parse to different hostnames
and produce redirect_uri_mismatch against each other. Schemes that require an authority
(http, https, ws, wss, ftp) must still include a host, and the redundant
com.example.app:///oauth2redirect and rootless com.example.app:oauth2redirect spellings
are rejected so that each callback has one canonical registration (RFC 9700 §2.1).
Upgrade note: the rootless spelling was previously accepted, but the same reassembly
rewrote it to com.example.app://oauth2redirect — registering oauth2redirect as a
hostname, which no client matches. It is now rejected at registration instead of being
silently reinterpreted; re-register any such URI in the single-slash form.

#1796 redirect_to_uri_allowed() no longer raises AttributeError when
ALLOW_URI_WILDCARDS is enabled and a redirect URI has no hostname, as is the case for
private-use URI scheme redirects.

#746 REFRESH_TOKEN_EXPIRE_SECONDS is now enforced when a refresh token is presented,
not only by the cleartokens (clear_expired) cleanup job. Previously a refresh token
past its configured lifetime kept working until a cleanup sweep happened to remove it —
or forever, if cleartokens was never scheduled. Expiry is idle-based: a refresh token
is rejected REFRESH_TOKEN_EXPIRE_SECONDS after its access token expires (the deadline
slides forward on every refresh), so actively-used tokens are unaffected. The default
(REFRESH_TOKEN_EXPIRE_SECONDS = None) still never expires refresh tokens. Upgrade
note: deployments that set REFRESH_TOKEN_EXPIRE_SECONDS may see idle refresh tokens
that are already past their lifetime rejected on upgrade, forcing those clients to
re-authenticate.

#746 clear_expired() now reclaims "orphaned" refresh tokens — non-revoked refresh
tokens whose access token was deleted out of band, leaving access_token NULL. The
previous access_token__expires__lt join could never match a NULL access token, so
such rows could remain in the database indefinitely.

#1687 Reusing a refresh token within REFRESH_TOKEN_GRACE_PERIOD_SECONDS no longer
raises AttributeError: 'NoneType' object has no attribute 'token' (HTTP 500) when the
access token previously minted from that refresh token still exists but its own refresh
token has since been removed — e.g. by clear_expired or a concurrent rotation.
_save_bearer_token now re-issues a refresh token bound to the surviving access token
instead of dereferencing the missing one (creating a fresh access token there would
violate the one-to-one AccessToken.source_refresh_token relation).

#958 Return a spec-compliant 400 instead of raising an uncaught AssertionError
(HTTP 500) when an application without any registered redirect_uris (e.g. a
client_credentials application) is driven through a flow that needs a default
redirect URI. Application.default_redirect_uri now raises
oauthlib's MissingRedirectURIError, consistent with the multiple-URI case.

#1260 OAuth2Validator.validate_bearer_token now rejects a token whose
application is not usable (Application.is_usable() returns False) with an
invalid_token error, mirroring the check the issuance path already performs
in _load_application. The default is_usable() returns True, so this only
affects swapped Application models that override it.

#1169 The DRF TokenHasScope and TokenMatchesOASRequirements permissions now
deny (return False) and log a warning, instead of raising an AssertionError
(HTTP 500), when request.auth is not an OAuth2 access token. This lets them be
composed with other permission classes (e.g. OR-ed) without a non-OAuth2 token
turning into a server error.

Security

#1819 The device authorization flow's confirmation and status views now act only on a device
grant that belongs to the signed-in user. DeviceUserCodeView claims a pending grant for the
user who enters the user_code, but DeviceConfirmView and DeviceGrantStatusView looked the
grant up by client_id and user_code alone. Any other authenticated user who learned that
short, human-readable code — it is displayed on the device's screen for a person to read and
type — could therefore approve the pending authorization, handing the device tokens bound to
the account of the user who entered it, or deny it, or read its status page. RFC 8628 §3.3 has
the user who is being asked to authorize the device grant that authorization. Both views now
filter on user=request.user and return 404 to anyone else; a grant that has not yet been
claimed through the user-code step likewise can no longer be confirmed by navigating straight
to the confirmation URL.

#1816 A refresh token that was deliberately revoked is no longer honored inside
REFRESH_TOKEN_GRACE_PERIOD_SECONDS. The grace window exists to shield the token a
client retries when it did not receive the rotated response, but revoked records both
that supersession and a deliberate revocation (the RFC 7009 /revoke/ endpoint,
AuthorizedTokenDeleteView, the admin, RP-initiated logout, revoking the bound access
token), and validation could not tell them apart. A revoked token was therefore usable
for the length of the window, contrary to
RFC 7009 §2.1 ("the
invalidation takes place immediately, and the token cannot be used again after the
revocation"). With ROTATE_REFRESH_TOKEN = False it was additionally re-issued as a new
live row carrying the same token value, bringing the repudiated credential back to life
in the database. The two are now distinguished by whether the token was ever consumed to
mint a successor access token. A genuine rotation retry inside the window is unaffected,
and deployments on the default REFRESH_TOKEN_GRACE_PERIOD_SECONDS = 0 were never
exposed.

This generalizes a test that previously applied only when
REFRESH_TOKEN_REUSE_PROTECTION was enabled, so it is also a behavior change with reuse
protection off: a superseded token whose successor access token has since been deleted is
now rejected inside the window rather than accepted.

Redirect URIs are now matched exactly, as
RFC 9700 §2.1 requires
("authorization servers MUST utilize exact string matching except for port numbers in
localhost redirection URIs of native apps") and OpenID Connect Core §3.1.2.1 restates
via RFC 3986 §6.2.1 Simple String Comparison. Four deviations are closed, each of which
let a request differ from the registered URI while still matching it:

A request could carry query parameters that were never registered — the check
tested that the registered query was a subset of the requested one. An attacker
could append parameters to an otherwise-legitimate redirect_uri and have the
authorization server reflect them into the client's callback alongside the
authorization code, the redirect-URI manipulation class described in
RFC 9700 §4.1.

A request could carry path parameters (https://example.com/cb;evil=1). urlparse()
peels ;params off the last path segment into a separate attribute, and only .path
was compared, so these smuggled data to the callback the same way extra query
parameters did. Matching now uses urlsplit(), which leaves them in the path.

A request could carry credentials (https://evil@example.com/cb). Only .hostname
was compared, so userinfo rode along unnoticed. Credentials are not part of a
registered callback and are now rejected on either side.

A request could carry a fragment, which urlparse() split off before comparison,
so https://example.com/cb#x matched a registered https://example.com/cb.
RFC 6749 §3.1.2 states
the endpoint URI MUST NOT include a fragment component. A bare trailing # is an
empty fragment component and is rejected too; a percent-encoded %23 is not a
fragment delimiter and is unaffected.

Registration is tightened to match: AllowedURIValidator tested the parsed fragment,
which is empty both for a URI with no fragment and for one ending in a bare #, so
https://example.com/cb# was accepted at save time. With matching now denying any #,
such a registration would be stored and then never authorize anything; it is rejected
up front instead. Registering a URI ending in # now raises a ValidationError where
it previously succeeded.

Case-insensitive scheme/host comparison (RFC 3986 §6.2.2.1 normalization) and the
RFC 8252 §7.3 loopback any-port exemption are unchanged; ALLOW_URI_WILDCARDS still
opts out of exact host matching and remains flagged by oauth2_provider.W009/E004.

Upgrade note: clients that pass per-request data through the redirect_uri query
string will now be rejected — every query parameter must be registered, and in the same
order. Register the full URI including its query, or move per-request data into the
state parameter, which is what it is for. Applications whose registered
redirect_uris already carry no query component are unaffected.

#1510 Revoking an access token from the authorized-tokens page
(AuthorizedTokenDeleteView) now also revokes the refresh token issued
alongside it. Previously only the access token was deleted, leaving the
refresh token usable to mint a fresh access token and defeating the
revocation (a regression from 2.3.0). Per
RFC 7009 §2.1 an
access token revocation may also revoke the respective refresh token; for a
user-initiated revocation that is now the behavior.

#1617 With REFRESH_TOKEN_REUSE_PROTECTION enabled, REFRESH_TOKEN_GRACE_PERIOD_SECONDS
no longer extends the validity of a refresh token that is several generations old in
the rotation chain. The grace period now only shields the immediately preceding
refresh token (the token a client retries when it did not receive the rotated
response); replaying an older, already-rotated-past token within the grace window is
rejected and revokes the whole token family, instead of being honored (and, without a
requested scope, minting a fresh token pair).

#727 The token revocation endpoint (/o/revoke_token/) now only revokes tokens that
were issued to the authenticated client. Previously it revoked any token matching the
submitted value regardless of which application issued it, so a client could revoke
another client's tokens. Per
RFC 7009 §2.1 the server
verifies the token was issued to the client making the request; a token belonging to a
different client is now left untouched and the endpoint still returns 200 (RFC 7009
§2.2) without disclosing whether the token exists.

#1799 RFC 7592 registration access tokens now honour COMPLIANT_BCP_RFC9700_TOKEN_STORAGE. The
dynamic client registration views assigned the token straight onto the model instead of routing it
through the storage path that honours the setting, so a deployment that had opted into hashed-at-rest
storage still had this one token persisted in cleartext. The registration response and the management
endpoint continue to return the token to its owner; only what is written to the database changes.

One column per quarter.

3.4.024 Jul 2026Security3 sources agree

It also carries a batch of security fixes : an unauthenticated open redirect from the authorization endpoint ( prompt=none ), HS256 ID tokens being si…

The headline of this release is first-class support for the Model Context Protocol (MCP)
authorization server role.
MCP's authorization spec is built on a stack of modern OAuth RFCs,
and this cycle landed the whole stack: Authorization Server Metadata (RFC 8414) and Protected
Resource Metadata (RFC 9728) for discovery, Dynamic Client Registration (RFC 7591 / RFC 7592) and
OAuth Client ID Metadata Documents (CIMD) so clients can register themselves, Resource Indicators
(RFC 8707) for audience-bound access tokens, and the OAuth 2.0 Security Best Current Practice
(RFC 9700) together with the RFC 9207 iss parameter. The RFC 9700 compliance gates double as a
configurable OAuth 2.1 security posture — they can reject the implicit and password grants and
enforce S256-only PKCE (legacy behavior by default in 3.4, scheduled to flip to compliant in 4.0).
The new ALLOW_LOCALHOST_LOOPBACK setting smooths the ephemeral-port loopback callback used by
native clients such as Claude Code, MCP Inspector, and mcp-remote.

Beyond MCP, the release adds a Django Ninja integration alongside the existing DRF support and
support for RP-Initiated Registration, lifts the 255-character cap on refresh tokens (mirroring the
access-token checksum scheme), makes cleartokens reclaim revoked refresh tokens sooner, and
harmonizes Bearer Authorization header parsing across the middleware.

It also carries a batch of security fixes: an unauthenticated open redirect from the
authorization endpoint (prompt=none), HS256 ID tokens being signed with the hashed client
secret, cleartext tokens and codes exposed in the Django admin, client secrets written to debug
logs, and predictable device-flow user_code generation. Longstanding operational bugs are fixed
too, including a multi-database migrate deadlock (#1591) and duplicate unique indexes that broke
fresh installs on Oracle and strict MySQL (#1656).

Before upgrading, read the breaking-changes section below: most items are makemigrations
steps for swapped models, but applications using the HS256 signing algorithm now require
hash_client_secret=False.

WARNING - POTENTIAL BREAKING CHANGES

Applications using the HS256 signing algorithm must now be configured with
hash_client_secret=False. Previously such applications signed ID tokens with the hashed client
secret, producing tokens that relying parties could not verify. Application.clean() now raises a
ValidationError for HS256 + hash_client_secret=True, and Application.jwk_key raises
ImproperlyConfigured at signing time if the secret is hashed. To migrate an affected
application, recreate it (or reset its secret) with hash_client_secret=False so the plaintext
secret is stored and can be used as the shared HMAC key.
Changes to the AbstractRefreshToken model require doing a manage.py migrate after upgrading.
If you use a swapped refresh token model (OAUTH2_PROVIDER_REFRESH_TOKEN_MODEL) you will need to
update your custom model with manage.py makemigrations. If your table already contains refresh
tokens you must also backfill token_checksum with a data migration — adapt the batched backfill
loop from forwards_func in
oauth2_provider/migrations/0015_refreshtoken_token_checksum.py (dropping its swapped-model
guard, the early return, and resolving your own model instead) and keep the same operation order:
add nullable checksum → drop the old ("token", "revoked") unique constraint → widen token to
TextField → backfill → make checksum non-nullable → add the ("token_checksum", "revoked")
unique constraint.
If you use a swapped application model (OAUTH2_PROVIDER_APPLICATION_MODEL), run
manage.py makemigrations after upgrading: AbstractApplication gained a
registration_source CharField (choices manual/dcr/cimd, default manual) to mark
how an application was registered — for example via Dynamic Client Registration (#670). This
replaces the never-released dcr_created BooleanField. Installs using the built-in Application
model just need manage.py migrate (migration 0019).
If you use a swapped application model (OAUTH2_PROVIDER_APPLICATION_MODEL), run
manage.py makemigrations after upgrading: for CIMD (#1742) AbstractApplication gained a
nullable cimd_expires_at DateTimeField, and client_id widened from max_length=100 to
255 so a metadata-document URL fits. Installs using the built-in Application model just need
manage.py migrate (migration 0020).
If you use a swapped device grant model (OAUTH2_PROVIDER_DEVICE_GRANT_MODEL), run
manage.py makemigrations after upgrading: the redundant field-level unique=True was removed
from AbstractDeviceGrant.device_code (#1656), and AbstractDeviceGrant.scope changed from
CharField(max_length=64, null=True) to a non-nullable TextField(blank=True) (#1693). When
prompted for a default for existing NULL scope rows, provide the one-off default "" —
matching oauth2_provider/migrations/0016_alter_devicegrant_scope.py. Uniqueness remains enforced by the
<app_label>_<class>_unique_device_code constraint. If you are doing a fresh install on
Oracle (or a MySQL backend that raises warnings as errors), you must also regenerate — or
hand-edit — your existing CreateModel migration for the swapped model, since it still declares
both uniqueness rules and will fail the same way migration 0013 did.
If you use a swapped access token model (OAUTH2_PROVIDER_ACCESS_TOKEN_MODEL) and have not
yet applied the 0012_add_token_checksum migration (i.e. you are upgrading from a version
below 3.0), its token_checksum backfill now deterministically skips the swapped model — the
schema operations in that migration never applied to swapped models, and the old backfill only
worked when the ordering of your app's migrations happened to allow it. migrate logs a warning
when the backfill is skipped and your table contains access tokens. Until token_checksum is
backfilled those tokens will not validate; no data is lost, and tokens work again as soon as the
checksum is populated. To backfill, add a data migration to your app (ordered after your
migration that adds token_checksum): adapt the batched backfill loop from forwards_func in
oauth2_provider/migrations/0012_add_token_checksum.py, dropping its swapped-model guard (the
early return) and resolving your own model instead. You can check for affected rows with
YourAccessToken.objects.filter(token_checksum__isnull=True).exists(). Installs that already
applied 0012 (any 3.x deployment) are unaffected.

Added

#1373 Integration and docs for Django Ninja authentication
#1546 Support for RP-Initiated Registration
#1099 Add RFC 8414 OAuth 2.0 Authorization Server Metadata endpoint (/.well-known/oauth-authorization-server)
#1743 Add RFC 9728 OAuth 2.0 Protected Resource Metadata endpoint (/.well-known/oauth-protected-resource), plus opt-in
mixins/decorators (ProtectedResourceMetadataMixin, protected_resource_metadata) and a DRF authenticator
(OAuth2ProtectedResourceAuthentication) that advertise it via the resource_metadata WWW-Authenticate challenge parameter
#1635 Dynamic help text on the application client_secret field, warning users to copy the
secret on creation and explaining it is hashed and unrecoverable when editing. The help text is
shared by both the Django admin application form and the front-end register/edit views: the
ApplicationAdmin uses ApplicationForm, and a shared oauth2_provider/js/application_form.js
updates the text live as the hash_client_secret checkbox is toggled on either surface. The
form also warns immediately when the HS256 algorithm is selected while the client secret is —
or will be — hashed, instead of only surfacing the error on save. (#1697, #1740)
#670 Dynamic Client Registration Protocol (RFC 7591 / RFC 7592) — DynamicClientRegistrationView and
DynamicClientRegistrationManagementView with configurable permission classes and registration access
tokens. Dynamically registered applications are flagged with AbstractApplication.registration_source
set to "dcr" and can be filtered in the Django admin.
#1739 ALLOW_LOCALHOST_LOOPBACK setting to extend the RFC 8252 §7.3 any-port loopback exemption to http://localhost redirect URIs (opt-in, default False)
#1742 Support for OAuth Client ID Metadata Documents (CIMD,
draft-ietf-oauth-client-id-metadata-document). A client may present an https URL as its
client_id; when CIMD_ENABLED is on the server fetches, validates and persists the metadata
document as a public application (SSRF-hardened fetch, failure backoff and an in-flight fetch cap).
Applications resolved this way carry AbstractApplication.registration_source set to "cimd".
Registration can be gated with CIMD_REGISTRATION_PERMISSION_CLASSES (default allow-all;
HostAllowlistCIMDPermission restricts it to CIMD_ALLOWED_HOSTS), and the
clearcimdapplications management command prunes expired CIMD applications that hold no live
tokens. See docs/cimd.rst.
#1751 Advertise the Dynamic Client Registration endpoint as registration_endpoint in the RFC 8414
authorization server metadata document when DCR_ENABLED is on
#1626 RFC 8707 "Resource Indicators" support
- clients can optionally specify resource parameter during authorization or access token requests
- Resource binding stored in Grant, AccessToken and RefreshToken models
- Token introspection endpoint returns aud claim for tokens with resource indicators
#1749 RFC 9700 (OAuth 2.0 Security Best Current Practice) compliance
gates, each controlled by a COMPLIANT_BCP_RFC9700_<topic> setting that defaults to False (current behavior,
warns when the discouraged behavior is used) and is scheduled to default to True in 4.0 (enforces the
compliant behavior): COMPLIANT_BCP_RFC9700_IMPLICIT_GRANT (§2.1.2),
COMPLIANT_BCP_RFC9700_PASSWORD_GRANT (§2.4), COMPLIANT_BCP_RFC9700_PKCE_METHOD (§2.1.1),
COMPLIANT_BCP_RFC9700_ACCESS_TOKEN_TRANSPORT (§4.3.2), COMPLIANT_BCP_RFC9700_AUTHZ_RESPONSE_ISS (§4.4),
and COMPLIANT_BCP_RFC9700_TOKEN_STORAGE (§4). Enforced behaviors are also removed from the RFC 8414
authorization-server metadata and the OIDC discovery document, so both stay consistent with what the
server accepts.
#1749 RFC 9207 iss authorization-response parameter and the
authorization_response_iss_parameter_supported metadata field (mix-up defense), gated by
COMPLIANT_BCP_RFC9700_AUTHZ_RESPONSE_ISS.
#1749 Config-validation gates for the RFC 9700 recommendations expressed through existing settings (the settings stay
canonical; the gate only sets validation severity — insecure value → check Warning while the gate is False,
check Error once it is True): COMPLIANT_BCP_RFC9700_REFRESH_TOKEN
(REFRESH_TOKEN_REUSE_PROTECTION, §4.14.2), COMPLIANT_BCP_RFC9700_REDIRECT_URI_SCHEME
(ALLOWED_REDIRECT_URI_SCHEMES, §2.1), COMPLIANT_BCP_RFC9700_REDIRECT_URI_MATCHING
(ALLOW_URI_WILDCARDS, §4.1.1), and COMPLIANT_BCP_RFC9700_PKCE_REQUIRED (PKCE_REQUIRED, §2.1.1).
#1749 A --deploy security system check that flags every RFC 9700 recommendation currently on a non-compliant value
(warnings oauth2_provider.W001–W010, errors oauth2_provider.E002–E005 when the corresponding
config-validation gate is enabled), plus an error (oauth2_provider.E001) for the incompatible combination of
hashed token storage and a non-zero REFRESH_TOKEN_GRACE_PERIOD_SECONDS.
#1749 New docs/security.rst page mapping each RFC 9700 recommendation to the corresponding setting. The demo IdP
exposes every gate as an OAUTH2_PROVIDER_COMPLIANT_BCP_RFC9700_* environment variable so the Docker image and the
e2e suite can exercise both gate positions.
#1660 Extract the HttpRequest creation in OAuth2Validator.validate_user into an overridable
build_http_request method, so subclasses can pass extra attributes through to their authentication backends.

Changed

#1732 Bearer Authorization header parsing is now harmonized across the codebase via a shared
oauth2_provider.utils.parse_bearer_token helper implementing RFC 7235 / RFC 6750 semantics.
As a result, OAuth2TokenMiddleware and OAuth2ExtraTokenMiddleware now accept the scheme
case-insensitively (e.g. a lowercase bearer header, which is RFC-correct, is no longer
ignored) and no longer mis-parse non-Bearer schemes that merely start with Bearer
(e.g. BearerX token was previously treated as a Bearer token and is now rejected).
#1688 cleartokens now removes revoked refresh tokens once REFRESH_TOKEN_GRACE_PERIOD_SECONDS
has passed, instead of keeping them until REFRESH_TOKEN_EXPIRE_SECONDS. When
REFRESH_TOKEN_REUSE_PROTECTION is enabled, revoked tokens are still kept until they expire so
that token reuse can be detected.
#1601 RefreshToken.token is now a TextField and lookups use a new SHA-256 token_checksum
field, removing the 255 character limit so long refresh tokens (e.g. Microsoft's JWT refresh
tokens) are supported. This mirrors the AccessToken.token_checksum approach introduced in 3.0.0
(#1447). The revocation endpoint also looks up access tokens by checksum now, restoring an indexed
lookup there.
#1652 The 0012_add_token_checksum backfill now computes checksums in batched bulk_update
calls (1000 rows per statement) instead of saving each access token individually, sharply
reducing how long the migration locks the access token table on large installations. Running
cleartokens before upgrading is still the best preparation for tables with many expired
tokens. See the warning above if you use a swapped access token model.

Deprecated

#1749 Using the OAuth 2.0 implicit grant, the resource owner password credentials grant, the PKCE plain
code_challenge_method, or an access token in the URI query string now emits a DeprecationWarning, per
RFC 9700. Each is gated by the corresponding
COMPLIANT_BCP_RFC9700_* setting, whose default is scheduled to flip to True (enforcing rejection) in 4.0.
#1700 Deprecate the AUTHENTICATION_SERVER_EXP_TIME_ZONE setting. Token introspection exp values are
Unix timestamps and are always interpreted as UTC per RFC 7662/RFC 7519. The setting still works
for backwards compatibility but now emits a DeprecationWarning and will be removed in a future
release.

Fixed

#1619 Accept wildcard redirect_uris whose hostname uses the double-dash form required for
Netlify deploy-preview URLs (https://*--sitename.netlify.app). The validator previously stripped
only a single leading hyphen after removing the *, leaving a hostname that began with - and was
rejected by URIValidator; it now strips up to two leading hyphens while rejecting longer runs.
#694 ReadWriteScopedResourceMixin.__new__() no longer forwards positional/keyword arguments to
object.__new__(), which raised TypeError: object.__new__() takes exactly one argument when
instantiating any view mixing this in with any argument at all — notably breaking Django REST
Framework's cls(**initkwargs) view instantiation.
#1006 A client_id or username containing a NUL (\x00) byte no longer causes a 500 error
on database backends (e.g. PostgreSQL) that raise ValueError instead of executing the query;
such values are now correctly treated as not matching any client/user.
#1738 Fix the rw_protected_resource decorator accumulating the read/write scope on a shared list
across requests. The required-scope list was built once at decoration time and appended to on
every request, so after a write (POST) request the write scope stayed in the list and a
subsequent read (GET) request with a read-only token was wrongly rejected. The behaviour was
request-order dependent, not thread-safe, and also mutated a caller-supplied scopes list. The
read/write scope is now added to a fresh per-request list.
#1693 AbstractDeviceGrant.scope is now a TextField(blank=True) like the other grant and token
models, instead of CharField(max_length=64, null=True). 64 characters is well below the limits
common in the broader OAuth ecosystem (Okta allows 1024, Google 2048), so longer scope strings
no longer fail or get truncated in the device authorization flow. Existing rows with a NULL
scope are backfilled to an empty string by migration 0016.
#1593 Use pk instead of id in clear_expired() and RefreshToken.revoke() so token models with a custom primary key field are supported.
#1594 Fix introspection token expiry handling to consistently use UTC and avoid the deprecated
datetime.utcfromtimestamp.
#1696 Fix auth_time in oauth2 validator when user has never logged in.
#1603 Honor user-overridden OIDC_SERVER_CLASS when OIDC_ENABLED is True and OAUTH2_SERVER_CLASS is not explicitly set; previously only the default was used in this fallback path.
#1591 Fix migrate hanging on 0012_add_token_checksum when a database router or
multi-database configuration is in use. The RunPython data migrations in 0006 and 0012 now
pin their queries to schema_editor.connection.alias, so the backfill runs on the connection
performing the migration instead of being routed to a second connection that deadlocks against
the migration transaction's own locks. This also makes both migrations backfill the correct
database when migrating a non-default alias (migrate --database=...). Thanks to Igor Petrik for
the diagnosis and fix.
#1656 Remove the redundant unique=True on DeviceGrant.device_code, which duplicated the
unique_device_code UniqueConstraint and created two identical unique indexes on the same
column. Fresh installs failed on Oracle (ORA-02261) and on MySQL backends that raise database
warnings as errors (ER_DUP_INDEX, 1831). Migration 0013 is fixed in place because the
duplicate was created inside CREATE TABLE, so a follow-up migration could never fix fresh
installs. Databases that already applied the old 0013 keep one harmless extra unique index;
it can optionally be dropped by hand. Thanks to Febin Micheal Antony (#1659) and
moscowmule2240 (#1718) for the fixes.

Security

#1734 Generate device-flow user_code values with the cryptographically secure secrets module
instead of the predictable random module (Mersenne Twister). The user_code is a device
authorization credential and must be unguessable per
RFC 8628 sections 5.1 and 5.2.
#1735 Stop writing client secrets to the logs. On a failed client authentication, the OAuth2Validator
logged the submitted client_secret (and, for Basic auth, the base64 client_id:client_secret
credential string) at DEBUG level. These messages now log at most the client_id (when it is
available; the base64/unicode decode-failure paths log a generic message with no credential), so
password-equivalent client secrets and raw credential strings no longer leak into log files or
aggregators.
#1736 Stop exposing cleartext access tokens, refresh tokens, and authorization codes in the Django
admin. The default AccessTokenAdmin, RefreshTokenAdmin, and GrantAdmin classes listed the
raw token/code in list_display and included them in search_fields. Because these values
are stored in cleartext, any staff user with view access saw replayable credentials, and
searching placed them in the ?q= query string (captured by access logs and browser history).
The columns are now masked (last characters only) and are no longer searchable (search is
available by application and user instead). The raw token/code field is also excluded from
the admin change/view form, which showed the editable cleartext field to any staff user with view
access; a masked read-only value is shown instead. Adding tokens/codes through the admin is now
disabled (has_add_permission returns False on the AccessToken, RefreshToken, Grant, and
IDToken admins) — these are issued by the OAuth flows and are not meant to be hand-created, and
the add form would otherwise present an editable cleartext field. Relatedly, the AccessToken,
RefreshToken, and Grant model __str__ methods no longer return the raw token/code (which the
admin renders in a row's change-page title and breadcrumbs, and which also appears in repr() and
logs); they now return a "<Model> #<pk>" identifier.
#1737 Fix HS256-signed ID tokens being signed with the hashed client secret. When an application
used the HS256 algorithm with hash_client_secret=True (the default), the ID token was signed
with the stored password-hash string as the HMAC key instead of the shared client secret, so a
relying party holding the real (plaintext) secret could never verify the signature — and a
password hash was misused as a MAC key. HS256 now requires hash_client_secret=False:
Application.clean() rejects the combination, and jwk_key raises ImproperlyConfigured
rather than emit an unverifiable token. HS256 with an empty client secret is likewise rejected
(an empty HMAC key would make ID tokens trivially forgeable). See the breaking-changes note above.
#1719 Fix an unauthenticated open redirect from the authorization endpoint. A prompt=none request from
an unauthenticated user was redirected to the supplied redirect_uri with a login_required error
before the client and redirect_uri were validated, allowing an attacker to redirect a victim's
browser to an arbitrary origin. The request is now validated against a registered client before any
redirect, per OpenID Connect Core 1.0 section 3.1.2.6.
Reported by Brian Lee (SSLab, Georgia Tech).

django-oauth-toolkit

Release timeline

Releases

Added

Deprecated

Changed

Fixed

Security

WARNING - POTENTIAL BREAKING CHANGES

Added

Changed

Deprecated

Fixed

Security

[3.3.0] - 2025-05-21

Added

Removed

Fixed

[3.2.0] - 2025-11-13

Added

Fixed

Added

Changed

Deprecated

Removed

Fixed

Security

Release 3.0.0

WARNING - POTENTIAL BREAKING CHANGES

Added

Changed

Removed

Fixed

Security

[2.4.0] - 2024-05-13

WARNING

Added

Fixed

Removed

[2.3.0] 2023-05-31

WARNING

Added

Changed

[2.2.0] 2022-10-18

WARNING

Added

Changed

Fixed

WARNING

Added

Changed

Fixed

What's Changed

New Contributors

Added

Changed

Fixed

Removed

Removed

[1.7.0] 2022-01-23

Added

Fixed

[1.6.3] 2022-01-11

Fixed

Added

[1.6.2] 2022-01-06

Fixed

Changed

Fixed

Added

Changed

Removed

Fixed

Added

Changed

Changed

Removed

Added

Fixed

Added