doorkeeper 5.9.9 → 6.0.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c4d0c4d775062d003452c97290c5fb4308812e17590946b9f8db9922e40f9d7
-  data.tar.gz: 7af434e11413a59e94cf12edd6ddcb088940110fabbd1174f0bacb2869a254da
+  metadata.gz: 454edd4f496ec3750a0be3da7db728302d93b355c075d6aded28792c8a53b9a8
+  data.tar.gz: 8be2862ad184cb71e36a5b9d2747bfc5186fe8bf9c539b6d61fbe92d05a57e5c
 SHA512:
-  metadata.gz: 1029aa2d0ff981b3d114f656f5b8d17308a946edd9466e7fe93d93fa5b6d1ba3c6873ba6cf628eab86ccb2f50b14507f272d61a0af829f2184963908941bb91c
-  data.tar.gz: 5b474f0a07ba2785acdbadca5d874a0b9e50955bebd0318499f84710cb06b0d1e8d58419ac4b889045e504011ddc88398ffea0c345434df291f0b43cf60fb3d2
+  metadata.gz: 3cb1367a63c3404a1dc79dd910265e5c189da7e8745b40c48f46e06d9b326f7a215760747c0273e28a51a26ff8e6447c376faf6a169d9f93cec84aac97191022
+  data.tar.gz: 3a3dc94969468b7ff5ef364876d068bf8fde231fcaeaa5ea6e43c207f7aafb236f02b5264b32678ad100788a1deb99caee79a3701cca1b4f79fd3a7f487865f1

data/CHANGELOG.md

@@ -5,29 +5,49 @@ upgrade guides.
 
 User-visible changes worth mentioning.
 
-## 5.9.9
-
-- Fix: `AuthorizedApplicationsController` now answers `401 Unauthorized` instead of running with a `nil` resource owner, which listed and revoked every token that has no resource owner — the ones the client credentials flow issues. Affected host applications are those whose `resource_owner_authenticator` answers `nil` without halting the request itself; the generated initializer's example redirects and is not affected.
-- Fix: `AuthorizationsController#destroy` now validates the client and redirect URI before producing the deny response, and renders — never redirects — when validation fails. Previously the deny path performed no OAuth-layer validation at all, allowing an open redirect to an attacker-controlled origin with the OAuth `state` attached. Also reject unregistered `response_type` values on the authorization endpoint rather than resolving them through the `constantize` fallback.
-- Fix: refuse redirect URIs with a script scheme (`javascript`, `vbscript`, `data`) both when an application is registered and at authorization time, regardless of `forbid_redirect_uri`. Such a URI is never a legitimate redirection endpoint, and with `response_mode=form_post` it became the action of the auto-submitting form the authorization server renders on its own origin. Already stored records with such a URI are now refused with `invalid_redirect_uri` before the consent screen is shown.
-
-## 5.9.8
-
-- [#1938] Fix: a request body ActionDispatch cannot parse (malformed JSON under a JSON content type, say) no longer raises `ActionDispatch::Http::Parameters::ParseError` out of `Doorkeeper::OAuth::Token.from_request` and `doorkeeper_token`. Since 5.9.7 the RFC 6750 §2 multi-method check read the body on every request, so such a request raised even when it carried a valid Bearer header. The body is now treated as carrying no token, the same way ActionDispatch's own `#filtered_parameters` treats that error.
-
-## 5.9.7
-
-- Refuse requests that transmit an access token by more than one method (RFC 6750 §2), instead of silently authorizing with the first configured `access_token_methods` entry that matched and discarding the other tokens. Such a request now fails closed as carrying no usable token (401 `invalid_token`); no calling contract changes. The form-encoded body (§2.2) and the URI query (§2.3) count as two methods even though Rails and Rack merge them into a single `params` hash. The same token repeated across two methods is refused too — §2 forbids the second method, not a disagreement between the two — and a custom callable extractor in `access_token_methods` keeps the historical first-wins behavior and is never invoked more than once. (The strict `invalid_request` (400) answer §3.1 prescribes ships with Doorkeeper 6.0.)
-- [#1925] Internal: pin the development dependency on `json` below 3.0. json 3 removed the positional options Hash from `JSON.parse` and the `quirks_mode` option from `JSON.generate`, both of which Active Support still uses, so the suite could not run on any supported Rails version.
-
-## 5.9.6
-
-- Reject requests that present more than one client identity (e.g. an `Authorization: Basic` header for one client and a `client_id` parameter naming another) with an `invalid_request` error, instead of authenticating the first extracted identity and silently discarding the other one. A `client_id` sent alongside another authentication method keeps working when it identifies the same client (RFC 7521 §4.2). Like the RFC 6749 §2.3 check released in 5.9.5, this validation does not apply when `client_credentials` is configured with a callable extractor, since the credentials the remaining extractors would return are never evaluated — the `client_credentials` option documents that now.
-
-## 5.9.5
-
-- Reject requests that authenticate the client with more than one method (RFC 6749 §2.3) with an `invalid_request` error, instead of silently authenticating with the first method that matched and discarding the other credentials.
+## main
+
+- Please add here
+
+## 6.0.0.beta1
+
+**Please make sure** you read the [Upgrade guides](https://github.com/doorkeeper-gem/doorkeeper/wiki/Migration-from-old-versions)
+and changelog below before the update since this version includes breaking changes.
+
+- [#1816] Fix: redirect `unauthorized_client` errors per RFC 6749 Section 4.1.2.1; validate redirect_uri before `client_supports_grant_flow` to prevent open redirect
+- [#1867] Fix: use `access_denied` instead of `invalid_client` for `resource_owner_authorize_for_client` validation per RFC 6749 Section 4.1.2.1. `invalid_client` is a token endpoint error (Section 5.2), not an authorization endpoint error.
+- [#1838] Add OAuth 2.0 Authorization Server Metadata endpoint (RFC 8414) served at `/.well-known/oauth-authorization-server`. The response is built from your Doorkeeper configuration and advertises the authorization, token, revocation and (when token introspection is enabled) introspection endpoints, supported scopes, response/grant types and PKCE code challenge methods. Two new config options are available: `issuer` (defaults to the request base URL) and `custom_metadata` (a Hash merged into the response, e.g. to advertise an OIDC `userinfo_endpoint`). The controller/response use the RFC 8414 "Metadata" naming so they don't collide with a future OpenID Connect Discovery (`.well-known/openid-configuration`) implementation. Endpoints disabled through `skip_controllers` are omitted from the response instead of raising a route-generation error.
+- [#1839] Send client credentials in the request body (not the query string) in the token endpoint specs, per RFC 6749 §2.3.1. Test-only change: the `*_endpoint_url` helpers now return a path plus a matching `*_endpoint_params` builder so flow specs post credentials through the body.
+- [#1840] Introduce a pluggable client authentication registry (RFC 6749 §2.3).
+  - New `client_authentication` config option declares which methods are accepted and in which order. Built-in strategies: `client_secret_basic`, `client_secret_post` and `none`.
+  - Custom strategies can be registered with `Doorkeeper::ClientAuthentication.register`.
+  - **[BREAKING]** Client credentials are no longer read from the query string — send them in the request body or via HTTP Basic. This applies to every endpoint that authenticates clients: token, revocation and introspection.
+  - **[BREAKING]** The `none` strategy rejects requests that carry a non-blank `Authorization` header. A common casualty is a public client POSTing to `/oauth/revoke` with a body `client_id` while still sending its `Authorization: Bearer <token>` header — drop the header from that request.
+  - **[BREAKING]** The `Doorkeeper::OAuth::Client::Credentials` class methods `.from_request`, `.from_basic` and `.from_params` are removed — extensions extracting credentials from a request should register a client authentication method instead.
+  - **Deprecated**: the `client_credentials` option — use `client_authentication` instead.
+  - **Deprecated**: the `Doorkeeper::OAuth::Client::Credentials` constant itself — it remains as an alias of `Doorkeeper::ClientAuthentication::Credentials` (the plain uid/secret struct).
+  - See the [Upgrade Guide](https://github.com/doorkeeper-gem/doorkeeper/wiki/Migration-from-old-versions) for detailed breaking changes, deprecations and migration steps.
+- [#1841] Reject requests that use more than one client authentication method (RFC 6749 §2.3: "The client MUST NOT use more than one authentication method in each request") with an `invalid_request` error instead of silently using the first match. The request payload is validated against every registered method before the configured one is selected, so a client sending e.g. both Basic and body credentials is rejected even when only one of those methods is enabled. This applies to every endpoint that authenticates clients — token, revocation and introspection. Only real authentication mechanisms count: a bare `client_id` (the `none` method) is not a mechanism of its own, and deprecated `client_credentials` callable extractors never count towards the limit (they keep the historical first-extractor-wins selection).
+- [#1842] **[BREAKING]** `force_pkce` now requires PKCE for all clients, including confidential ones, in line with the OAuth 2.0 Security BCP (RFC 9700) and OAuth 2.1. Previously confidential clients were exempt. If you enable `force_pkce` and have confidential clients that do not yet send a `code_challenge`/`code_verifier`, their authorization requests will start to be rejected.
+- [#1845] Fix `NameError` when the config option DSL (`Doorkeeper::Config::Option`) is extended into a class that does not define `self.builder_class`. The guard raised `Doorkeeper::MissingConfigurationBuilderClass`, a constant that was never defined, so callers saw `uninitialized constant` instead of the intended message. The error is now defined as `Doorkeeper::Errors::MissingConfigurationBuilderClass` (a `DoorkeeperError`) and referenced correctly.
+- [#1846] Document and pin with regression specs that a `scope` parameter sent to the token endpoint is ignored for the `authorization_code` grant (RFC 6749 §4.1.3 does not define one): the access token always inherits the scopes of the authorization grant, and the response reports the actual granted `scope`. No behavior change.
+- [#1847] Fix `Doorkeeper.config.enabled_grant_flows` (and `calculate_grant_flows`) not listing the `refresh_token` grant flow when `use_refresh_token` is configured, so consumers (e.g. RFC 8414 metadata) no longer need to append it manually — the built-in metadata endpoint now relies on this too. The flow is no longer duplicated in `token_grant_flows` when `refresh_token` is also listed in `grant_flows` explicitly, a configuration-time warning is logged when `grant_flows` enables `refresh_token` without `use_refresh_token` (no refresh tokens would ever be issued), and the initializer template documents the flow.
+- [#1848] Derive `token_endpoint_auth_methods_supported` in the RFC 8414 metadata response from the effective client authentication configuration (including a deprecated `client_credentials`-only setup) instead of hardcoding the default methods. Servers that customize `client_authentication` (including extension-registered methods like `private_key_jwt`) now see their metadata reflect what the server actually accepts; unregistered names are not advertised.
+- [#1849] Support RFC 9207 (Authorization Server Issuer Identification): when `issuer` is configured, the `iss` parameter is added to the authorization responses redirected back to the client (successful and error responses alike) and `authorization_response_iss_parameter_supported` is advertised in the server metadata. Clients that parse the authorization redirect will start seeing the new `iss` parameter. A configured `issuer` that is not RFC-compliant (not an https URL, or containing a query/fragment) now logs a warning at boot, as does a path-bearing issuer, which RFC 8414 clients would not discover through Doorkeeper's root-only well-known metadata route.
+- [#1850] Fix `reuse_access_token` returning a refresh token that doesn't match the request: token reuse now requires the candidate's refresh token presence to match what the request asks for, in both directions. A request that expects a refresh token (e.g. `use_refresh_token` enabled) no longer reuses a token issued without one (previously the refresh token was silently omitted), and a request that does not expect one no longer reuses a token that carries one (previously an unrequested refresh token was returned, reachable via a per-request `refresh_token_enabled` callable). The requirement participates in the token matching itself, so an older matching token that satisfies it is still reused; a fresh token is created only when none does. **API change for ORM extensions**: `matching_token_for` and `find_matching_token` now take an optional block (`&filter`) that a token must satisfy to count as a match — extensions overriding either method must accept the block and honor it (accept and yield).
+- [#1851] Fix duplicate query parameter in the authorization callback when a client's registered `redirect_uri` already contains a parameter with the same name as a response parameter (e.g. `state`). The redirect query was merged with string keys on one side and symbol keys on the other, so a collision emitted the parameter twice (`?state=fixed&code=...&state=user`); the response parameter now overrides the registered one and appears exactly once. A blank response parameter (e.g. no `state` sent with the request) leaves the registered parameter untouched, per RFC 6749 §3.1.2.
+- [#1852] Fix the `pkce_code_challenge_methods` config validator using line anchors (`^`/`$`) instead of string anchors (`\A`/`\z`), so a multi-line value such as `"plain\ngarbage"` passed validation and was retained as a (never-matching) challenge method instead of being rejected and reset to the default.
 - [#1853] Fix `reuse_access_token` reusing a token that was created with `custom_access_token_attributes` values when the new request doesn't specify any custom attributes. Such requests now only match tokens without custom attributes.
+- [#1854] Fix the RFC 8414 metadata endpoint raising `ActionController::UrlGenerationError` (HTTP 500) when `use_doorkeeper` configures a custom controller whose namespace depth differs from `doorkeeper/metadata` (e.g. `controllers tokens: "custom_tokens"`).
+- [#1855] Perform the fallback secret upgrade-on-access write (plain → hashed token or application secret) through the primary database role, so `enable_multiple_database_roles` setups no longer attempt the write on a read replica when the lookup happens in a request routed to the reading role.
+- [#1857] Pin with regression specs that a `+` between scopes in a form-encoded token request is decoded as a space (so `scope=public+write` refreshes fine), while a percent-encoded literal `+` (`%2B`) names a single scope and is rejected when unknown, per RFC 6749 §3.3. Test-only change, closes [#1686].
+- [#1859] Pin with regression specs that a refresh token bound to an expired access token can be revoked (fixed by [#1744]) and that the revoked refresh token is rejected at the token endpoint afterwards. Test-only change, closes [#1671].
+- [#1860] Fix introspection of refresh tokens (RFC 7662): a refresh token bound to an expired access token now introspects as `active: true`, matching the token endpoint which still accepts it. The introspection response for a presented refresh token no longer includes the paired access token's `token_type` and `exp`. Fixes [#1858].
+- [#1862] Document that with `reuse_access_token` enabled token matching considers only the application, resource owner, scopes and custom token attributes — separate authorization grants for the same combination intentionally share one access token — and pin the behavior with a regression spec. Docs/test-only change, closes [#1693].
+- [#1864] Fix `custom_access_token_attributes` values being dropped when the authorization goes through the consent screen: the approve/deny forms now carry the custom attributes as hidden fields, and the pre-authorization JSON (`api_only` mode) includes them so custom consent UIs can send them back.
+- [#1869] Improve test coverage
+- [#1870] Fix: raise the intended `Doorkeeper::Errors::TokenGeneratorNotFound` / `UnableToGenerateToken` (instead of a confusing `NameError`) when `application_secret_generator` is misconfigured.
+- Please add here
 
 ## 5.9.3
 
@@ -47,6 +67,7 @@ User-visible changes worth mentioning.
 - [#1797] Fix `doorkeeper:db:cleanup` rake task failure on PostgreSQL
 - [#1800] Set `@grant_type` in `ClientCredentialsRequest` and `RefreshTokenRequest` constructors so `request.grant_type` returns
   the correct value in hooks like `before_successful_strategy_response`.
+- [#1801] Fix `hash_application_secrets` fallback not upgrading secret on access.
 - [#1802] Fix `filter_parameters` not applied when `Doorkeeper.configure` is called inside to_prepare.
 - [#1804] Use `ActiveSupport.on_load(:active_record)` in ORM hooks to prevent loading ActiveRecord models too early
 - [#1806] Fix token revocation bypass for public clients (RFC 7009)
@@ -77,6 +98,7 @@ User-visible changes worth mentioning.
 - [#1779] Only lock previous access token model when creating a new token from its refresh token if revoke_previous_refresh_token_on_use is false
 - [#1778] Ensure that token revocation is idempotent by checking that that token has not already been revoked before revoking.
 
+
 ## 5.8.2
 
 - [#1755] Fix the error message for force_pkce

data/README.md

@@ -24,6 +24,7 @@ Supported features:
 - [OAuth 2.0 Threat Model and Security Considerations](https://datatracker.ietf.org/doc/html/rfc6819)
 - [OAuth 2.0 for Native Apps](https://datatracker.ietf.org/doc/html/rfc8252)
 - [Proof Key for Code Exchange by OAuth Public Clients](https://datatracker.ietf.org/doc/html/rfc7636)
+- [OAuth 2.0 Authorization Server Issuer Identification](https://datatracker.ietf.org/doc/html/rfc9207) — opt-in by setting `issuer`; adds the `iss` parameter to authorization redirects returned to the client
 
 ## Table of Contents
 

data/app/controllers/doorkeeper/authorizations_controller.rb

@@ -16,13 +16,7 @@ module Doorkeeper
       redirect_or_render(authorize_response)
     end
 
-    # The deny path answers a request the client sent, so it is subject to the
-    # same client and redirect URI validation as #create: without it an
-    # unregistered redirect_uri was honoured and the user-agent redirected to
-    # it, carrying the OAuth `state` to an origin of the caller's choosing.
     def destroy
-      return if refuse_invalid_client?
-
       redirect_or_render(authorization.deny)
     rescue Doorkeeper::Errors::InvalidTokenStrategy => e
       error_response = get_error_response_from_exception(e)
@@ -51,37 +45,13 @@ module Doorkeeper
 
       if Doorkeeper.configuration.redirect_on_errors? && pre_auth.error_response.redirectable?
         redirect_or_render(pre_auth.error_response)
+      elsif Doorkeeper.configuration.api_only
+        render json: pre_auth.error_response.body, status: pre_auth.error_response.status
       else
-        render_error_response(pre_auth.error_response)
-      end
-    end
-
-    def render_error_response(error_response)
-      if Doorkeeper.configuration.api_only
-        render json: error_response.body, status: error_response.status
-      else
-        render :error, locals: { error_response: error_response }, status: error_response.status
+        render :error, locals: { error_response: pre_auth.error_response }, status: pre_auth.error_response.status
       end
     end
 
-    # Renders the error when the request's client_id or redirect_uri is missing
-    # or invalid, and answers whether the request was refused. Errors are
-    # rendered, never redirected, regardless of `handle_auth_errors :redirect`:
-    # no failure this check can produce leaves a redirect target worth
-    # trusting. Either the client failed first, so the redirect URI was never
-    # reached, or the redirect URI is itself the invalid one - and RFC 6749
-    # Section 3.1.2.4 forbids redirecting the user-agent to an invalid
-    # redirection URI.
-    def refuse_invalid_client?
-      return false if pre_auth.client_valid?
-
-      error_response = pre_auth.error_response
-      error_response.raise_exception! if Doorkeeper.config.raise_on_errors?
-
-      render_error_response(error_response)
-      true
-    end
-
     def can_authorize_response?
       Doorkeeper.config.custom_access_token_attributes.empty? && pre_auth.client.application.confidential? && matching_token?
     end

data/app/controllers/doorkeeper/authorized_applications_controller.rb

@@ -3,7 +3,6 @@
 module Doorkeeper
   class AuthorizedApplicationsController < Doorkeeper::ApplicationController
     before_action :authenticate_resource_owner!
-    before_action :validate_resource_owner
 
     def index
       @applications = Doorkeeper.config.application_model.authorized_for(current_resource_owner)
@@ -30,27 +29,5 @@ module Doorkeeper
         format.json { head :no_content }
       end
     end
-
-    private
-
-    # `authenticate_resource_owner!` hands the request to the host
-    # application's `resource_owner_authenticator` block, which is expected to
-    # halt the request itself — redirect to a sign-in page, raise, render —
-    # when nobody is signed in. A block that merely answers nil halts nothing:
-    # the library default (no block configured) logs a warning and answers
-    # nil, and so does any block written as a bare lookup such as
-    # `User.find_by(id: session[:user_id])`.
-    #
-    # Both actions here scope their work to `current_resource_owner`, and a
-    # nil owner is not "no scope" — it is the scope of the records that have
-    # no resource owner, which is what the client credentials flow issues.
-    # #index would list every application holding one and #destroy would
-    # revoke them, for a caller that never authenticated. So refuse the
-    # request rather than treat "nobody" as an owner. Only this controller is
-    # guarded; `authenticate_resource_owner!` itself is left alone because
-    # AuthorizationsController shapes its own response around the owner.
-    def validate_resource_owner
-      head :unauthorized unless current_resource_owner
-    end
   end
 end

data/app/controllers/doorkeeper/metadata_controller.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Doorkeeper
+  class MetadataController < Doorkeeper::ApplicationMetalController
+    def show
+      headers.merge!(metadata_response.headers)
+      render json: metadata_response.body,
+             status: metadata_response.status
+    end
+
+    private
+
+    def metadata_response
+      @metadata_response ||= Doorkeeper::OAuth::MetadataResponse.new(
+        request.base_url,
+        ->(**args) { url_for(**args) },
+      )
+    end
+  end
+end

data/app/controllers/doorkeeper/tokens_controller.rb

@@ -34,7 +34,7 @@ module Doorkeeper
 
     # OAuth 2.0 Token Introspection - https://datatracker.ietf.org/doc/html/rfc7662
     def introspect
-      introspection = OAuth::TokenIntrospection.new(server, token)
+      introspection = OAuth::TokenIntrospection.new(server, token, token_type: presented_token_type)
 
       if introspection.authorized?
         render json: introspection.to_json, status: 200
@@ -138,6 +138,15 @@ module Doorkeeper
       RevocableTokens::RevocableRefreshToken.new(token)
     end
 
+    # Revocation (RFC 7009) and introspection (RFC 7662) deliberately share
+    # the same request shape — `token` plus an optional `token_type_hint` —
+    # so both actions resolve the presented token through #revocable_token.
+    # The wrapper type doubles as the record of which credential the client
+    # actually presented.
+    def presented_token_type
+      revocable_token.is_a?(RevocableTokens::RevocableRefreshToken) ? :refresh_token : :access_token
+    end
+
     def access_token
       token = Doorkeeper.config.access_token_model.by_token(params["token"])
       return unless token

data/app/views/doorkeeper/authorizations/new.html.erb

@@ -29,6 +29,9 @@
       <%= hidden_field_tag :scope, @pre_auth.scope, id: nil %>
       <%= hidden_field_tag :code_challenge, @pre_auth.code_challenge, id: nil %>
       <%= hidden_field_tag :code_challenge_method, @pre_auth.code_challenge_method, id: nil %>
+      <% @pre_auth.custom_access_token_attributes.each do |attribute_name, attribute_value| %>
+        <%= hidden_field_tag attribute_name, attribute_value, id: nil %>
+      <% end %>
       <%= submit_tag t('doorkeeper.authorizations.buttons.authorize'), class: "btn btn-success btn-lg btn-block" %>
     <% end %>
     <%= form_tag oauth_authorization_path, method: :delete do %>
@@ -40,6 +43,9 @@
       <%= hidden_field_tag :scope, @pre_auth.scope, id: nil %>
       <%= hidden_field_tag :code_challenge, @pre_auth.code_challenge, id: nil %>
       <%= hidden_field_tag :code_challenge_method, @pre_auth.code_challenge_method, id: nil %>
+      <% @pre_auth.custom_access_token_attributes.each do |attribute_name, attribute_value| %>
+        <%= hidden_field_tag attribute_name, attribute_value, id: nil %>
+      <% end %>
       <%= submit_tag t('doorkeeper.authorizations.buttons.deny'), class: "btn btn-danger btn-lg btn-block" %>
     <% end %>
   </div>

data/lib/doorkeeper/client_authentication/credentials.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Doorkeeper
+  module ClientAuthentication
+    Credentials = Struct.new(:uid, :secret) do
+      # Public clients may have their secret blank, but "credentials" are
+      # still present as long as the uid is present.
+      delegate :blank?, to: :uid
+    end
+  end
+end

data/lib/doorkeeper/client_authentication/fallback_method.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Doorkeeper
+  module ClientAuthentication
+    # Used when no registered client authentication method matches the
+    # request. It matches everything and authenticates to nothing, mirroring
+    # the previous behaviour where an unauthenticated request simply yielded
+    # no credentials.
+    class FallbackMethod
+      def self.matches_request?(_request)
+        true
+      end
+
+      def self.authenticate(_request)
+        nil
+      end
+    end
+  end
+end

data/lib/doorkeeper/client_authentication/legacy_callable.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Doorkeeper
+  module ClientAuthentication
+    # Adapter that lets a legacy callable +client_credentials+ extractor
+    # (e.g. +->(request) { [client_id, client_secret] }+) keep working through
+    # the client authentication registry during the deprecation window.
+    #
+    # The callable is expected to return a +[uid, secret]+ pair (or +nil+ when
+    # it does not apply), matching the historical +Credentials.from_request+
+    # contract. It is considered to match a request whenever it yields present
+    # credentials, mirroring the previous "first extractor that returns a uid
+    # wins" behaviour.
+    class LegacyCallable
+      def initialize(callable)
+        @callable = callable
+      end
+
+      def matches_request?(request)
+        credentials_for(request).present?
+      end
+
+      def authenticate(request)
+        credentials_for(request)
+      end
+
+      private
+
+      # Invoke the wrapped extractor at most once per request. +matches_request?+
+      # and +authenticate+ both need the extracted credentials, and the legacy
+      # +Credentials.from_request+ contract called each extractor exactly once,
+      # so cache the result on the request itself to preserve that. The adapter
+      # is stored in the config/registry and therefore shared across requests
+      # and threads, so the cache must live on the per-request +env+ (keyed per
+      # adapter instance) rather than on the adapter, which would otherwise race.
+      def credentials_for(request)
+        request.env[cache_key] ||=
+          Doorkeeper::ClientAuthentication::Credentials.new(*@callable.call(request))
+      end
+
+      def cache_key
+        @cache_key ||= "doorkeeper.client_authentication.legacy_callable.#{@callable.object_id}"
+      end
+    end
+  end
+end

data/lib/doorkeeper/client_authentication/method.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Doorkeeper
+  module ClientAuthentication
+    # Wraps a registered client authentication method, pairing its
+    # registration +name+ with the +strategy+ object that knows how to match
+    # and authenticate a request.
+    #
+    # NOTE: the wrapped object is exposed as +strategy+ rather than +method+ on
+    # purpose — an +attr_reader :method+ would shadow Ruby's core
+    # +Object#method+ reflection API and break +wrapper.method(:authenticate)+.
+    class Method
+      attr_reader :name, :strategy
+
+      delegate :matches_request?, :authenticate, to: :strategy
+
+      def initialize(name, strategy)
+        @name = name
+        @strategy = strategy
+      end
+    end
+  end
+end

data/lib/doorkeeper/client_authentication/registry.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Doorkeeper
+  module ClientAuthentication
+    # Holds the registered client authentication methods and provides the DSL
+    # to register and look them up by name.
+    module Registry
+      mattr_accessor :registered_methods
+      self.registered_methods = {}
+
+      # Allows to register a custom OAuth client authentication method so that
+      # Doorkeeper could recognize and process it.
+      #
+      def register(name, method)
+        unless name.respond_to?(:to_sym)
+          raise ArgumentError,
+                "client authentication method name must be a Symbol or String, got #{name.inspect}"
+        end
+
+        unless method.respond_to?(:matches_request?) && method.respond_to?(:authenticate)
+          raise ArgumentError,
+                "client authentication method '#{name}' must respond to " \
+                "#matches_request? and #authenticate, got #{method.inspect}"
+        end
+
+        name_key = name.to_sym
+
+        if registered_methods.key?(name_key)
+          ::Kernel.warn <<~WARNING
+            [DOORKEEPER] '#{name_key}' client authentication strategy is already registered and will be overridden
+            in #{caller(1..1).first}
+          WARNING
+        end
+
+        registered_methods[name_key] = Doorkeeper::ClientAuthentication::Method.new(name_key, method)
+      end
+
+      # [NOTE]: switch to #fetch once the deprecated client_credentials
+      # fallbacks are removed.
+      def get(name)
+        return unless name.respond_to?(:to_sym)
+
+        registered_methods[name.to_sym]
+      end
+    end
+  end
+end

data/lib/doorkeeper/client_authentication.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "doorkeeper/client_authentication/credentials"
+require "doorkeeper/client_authentication/fallback_method"
+require "doorkeeper/client_authentication/legacy_callable"
+require "doorkeeper/client_authentication/method"
+require "doorkeeper/client_authentication/registry"
+
+module Doorkeeper
+  # Registry of the OAuth client authentication methods (RFC 6749 §2.3)
+  # Doorkeeper knows how to process. Each registered method is able to tell
+  # whether it +matches_request?+ and how to +authenticate+ it into a
+  # Credentials object.
+  module ClientAuthentication
+    extend Registry
+
+    # Default ordered client authentication methods (RFC 6749 §2.3) used when
+    # +client_authentication+ is not configured.
+    DEFAULT_METHODS = %i[client_secret_basic client_secret_post none].freeze
+
+    # Maps the current method names back onto the deprecated +client_credentials+
+    # names so the +client_credentials_methods+ alias can keep returning the
+    # legacy symbols that external callers (e.g. doorkeeper-openid_connect) map
+    # from. Names without a legacy equivalent (e.g. +:none+, custom methods) are
+    # returned unchanged — consumers that don't recognise them drop them, just
+    # as they did before.
+    LEGACY_NAME_FOR = {
+      client_secret_basic: :from_basic,
+      client_secret_post: :from_params,
+    }.freeze
+
+    # Converts resolved Method objects into the legacy client_credentials
+    # symbol names for the deprecated +client_credentials_methods+ alias.
+    def self.to_legacy_client_credentials_names(methods)
+      methods.map { |method| LEGACY_NAME_FOR.fetch(method.name, method.name) }
+    end
+
+    register(
+      :none,
+      Doorkeeper::OAuth::ClientAuthentication::None,
+    )
+
+    register(
+      :client_secret_post,
+      Doorkeeper::OAuth::ClientAuthentication::ClientSecretPost,
+    )
+
+    register(
+      :client_secret_basic,
+      Doorkeeper::OAuth::ClientAuthentication::ClientSecretBasic,
+    )
+
+    # Converts a deprecated +client_credentials+ configuration into the client
+    # authentication method names / adapters understood by the registry.
+    # Unknown values are warned about and dropped; callables are wrapped in a
+    # LegacyCallable adapter. +:none+ (public client support) is appended only
+    # for +:from_params+ — the sole legacy method that accepted a bare
+    # +client_id+ without a secret — so a Basic-only configuration is not
+    # silently broadened.
+    def self.from_legacy_client_credentials(methods)
+      converted = methods.filter_map { |method| legacy_client_credential(method) }
+      converted.push(:none) if methods.include?(:from_params)
+      converted
+    end
+
+    def self.legacy_client_credential(method)
+      case method
+      when :from_basic
+        :client_secret_basic
+      when :from_params
+        :client_secret_post
+      else
+        legacy_extractor_or_nil(method)
+      end
+    end
+    private_class_method :legacy_client_credential
+
+    def self.legacy_extractor_or_nil(method)
+      unless method.respond_to?(:call)
+        Kernel.warn("[DOORKEEPER] Unknown client_credentials method detected: #{method}")
+        return nil
+      end
+
+      Kernel.warn(
+        "[DOORKEEPER] client_credentials callable extractors are deprecated; wrapping it in a " \
+        "legacy client authentication adapter. Register it via " \
+        "Doorkeeper::ClientAuthentication.register instead.",
+      )
+      Method.new(:legacy_callable, LegacyCallable.new(method))
+    end
+    private_class_method :legacy_extractor_or_nil
+  end
+end

data/lib/doorkeeper/config/option.rb

@@ -74,7 +74,7 @@ module Doorkeeper
       def self.extended(base)
         return if base.respond_to?(:builder_class)
 
-        raise Doorkeeper::MissingConfigurationBuilderClass, "Define `self.builder_class` method " \
+        raise Doorkeeper::Errors::MissingConfigurationBuilderClass, "Define `self.builder_class` method " \
                           "for #{base} that returns your custom Builder class to use options DSL!"
       end
     end