Upgrading
If you want to upgrade Doorkeeper to a new version, check out the upgrading guides and take a look at the CHANGELOG.
Per-application grant flow customization ([#1286]). Override
allow_grant_flow_for_client?on the Application model to control which grant flows each client can use.Batch token lookup ([#1270]).
reuse_access_tokennow finds matching tokens in batches (configurable viamatching_token_forlookup size). This improves performance for large token tables.Client credentials token revocation ([#1271]). 5.2 revokes the previous access token when a client requests new client-credentials tokens by default. Note: this default was reverted in 5.3. See the 5.3 section below.
client_via_uidremoved ([#1296]).Doorkeeper::Server#client_via_uidwas removed;client_idis now part of strong parameters.
Breaking changes in 6.0
Client authentication registry ([#1840]). Doorkeeper resolves client authentication through a registry of named strategies (
client_secret_basic,client_secret_post,none) instead of hard-coded extractors. Theclient_credentialsconfig option is deprecated in favour ofclient_authentication. Client credentials are no longer read from the query string, and public clients must not send a non-blankAuthorizationheader. See the migration guide for full details.Fallback secret upgrade race fix ([#1923]). When a fallback secret strategy is configured, the automatic upgrade on match now uses a conditional
update_all(Active Record) instead of#update, fixing a race where a concurrent#renew_secretcould be silently undone. Model callbacks and validations no longer run on this path. Applications without a fallback strategy are unaffected. See the migration guide for details.private_key_jwtaudience ([#1926]). The audiences accepted for aprivate_key_jwtclient assertion are built only from the server's own identity — theissueroption orRails.application.routes.default_url_options[:host]— and never from the request'sHostheader. A server that enablesprivate_key_jwtwithout configuring either now refuses every assertion withinvalid_clientand logs an error at boot. Set one of the two and authentication resumes; no client-side change is needed. See the migration guide for details.
Breaking changes in 5.3
Optional client credentials revocation ([#1318]). Token revocation for client credentials grants is now off by default (reversing the 5.2 default). Re-enable with
revoke_previous_client_credentials_tokenin the initializer if you relied on 5.2 behavior.Custom model classes ([#1345]). Doorkeeper models can now use custom classes via
application_class,access_token_class, etc. Extracted AR mixins are available inDoorkeeper::Orm::ActiveRecord::Mixins.CVE-2020-10187 backport ([#1371] in 5.3.2).
Doorkeeper::Application#as_jsonwas restricted to a minimal set of serialized attributes, fixing an information disclosure vulnerability. Custom serialization on/oauth/applications.jsonmust be reimplemented via#as_jsonoverrides.
Breaking changes in 5.4
Polymorphic resource owner ([#1355]). Access Tokens and Grants can now belong to polymorphic resource owners via
use_polymorphic_resource_owner. Doorkeeper passes resource owner instances (not just IDs) — review custom patches and extensions.authorize_resource_owner_for_client([#1354]). A new hook to control authorization on a per-application basis before granting access.CVE-2020-10187 fix (original) ([#1371]). The
#as_jsonserialization restriction was developed here and backported to 5.0–5.3.RFC 7009 revocation ([#1370]). Token revocation now requires
client_id(public clients) andclient_secret(private clients), per RFC 7009.active_record_optionsdeprecated ([#1358]). Replaced by direct config options; removed in 5.6.3.
Notable changes in 5.5–5.9
5.5
Custom grant flows ([#1418]). Register custom OAuth grant types via
grant_flowsin the initializer.Form-post response mode ([#1438]). Support for
response_mode=form_post.Client authentication for password grant ([#1420]). Resource Owner Password Grant now requires client authentication per RFC. Opt out with
skip_client_authentication_for_password_grant(discouraged).API-mode controllers ([#1473]).
ApplicationsControllerandAuthorizedApplicationsControllerare now available in API mode. Skip withskip_controllersif not needed.
5.6
Dynamic scopes ([#1739] in 5.8.0, continued in 5.6.x). Wildcard and pattern-matched scopes.
Custom token attributes ([#1602]). Store arbitrary data on access tokens and grants via
custom_access_token_attributes.matching_token_forAPI change ([#1542]). Now returns only active tokens (not just non-revoked). This affectsreuse_access_tokenbehavior.
5.7
force_pkce([#1705]). Require non-confidential clients to use PKCE when requesting tokens via authorization code.
5.8
pkce_code_challenge_methods([#1735]). Configure allowed PKCE challenge methods (e.g.S256,plain).Public application null secret ([#1727]). Public applications can have a
nilsecret value.
5.9
Read-replica support ([#1791]).
enable_multiple_database_rolesfor automatic role switching in multi-database setups.Idempotent revocation ([#1778]). Revoking an already-revoked token no longer raises an error.
i18n view punctuation extraction (5.9.1) ([#1784]). Breaking for apps with custom views: colons were removed from ERB templates and moved into i18n translation strings. If you override
authorizations/new,authorizations/show, orapplications/show, update your views and translations (or upgrade the doorkeeper-i18n gem).RFC 7009 public client fix (5.9.1) ([#1806]). Fixed a token revocation bypass for public clients.
Client auth rejection (5.9.5) ([#1901]). Clients sending credentials via more than one method are rejected with
invalid_request.
Migration checklist
Generate and run migrations.
Depending on the version gap, additional generators may be needed:
doorkeeper:confidential_applications,doorkeeper:pkce,doorkeeper:enable_polymorphic_resource_owner,doorkeeper:previous_refresh_token, etc.Review the initializer. Compare your
config/initializers/doorkeeper.rbagainst the latest template. Pay attention to removed or renamed options (e.g.enable_pkce_without_secret,active_record_options).Update custom views. If you override any Doorkeeper views, review them against the current templates — especially for the 5.9.1 i18n punctuation change (colons moved from ERB to locale strings).
Test token formats. After upgrading from 5.0 to 5.1+, verify that existing hex tokens still validate. If you customized token generation, confirm
default_generator_methodis set appropriately.Audit client applications. Ensure all applications have the
confidentialflag set correctly. Public clients (native/mobile apps, SPAs) should haveconfidential: false.Review grant flow and scope configuration. Check that
scopes_by_grant_type,grant_flows, and per-applicationallow_grant_flow_for_client?are configured as expected for your use cases.
Deprecation notes
active_record_optionswas deprecated in 5.4 and removed in 5.6.3.enable_pkce_without_secretwas removed in 5.0.Doorkeeper.configured?,Doorkeeper.database_installed?, andDoorkeeper.installed?were removed in 5.0.
Additional resources
Last updated