doorkeeper 5.9.3 → 6.0.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 71a32b8766b44f5eff16fbc128cfff6ab676b5af9104d16d58f060a0ed6d894c
-  data.tar.gz: 864e07764f1ba86d6f52a10e5a081291c2748dcecbfb8bcc60b0f27baa4e616e
+  metadata.gz: 454edd4f496ec3750a0be3da7db728302d93b355c075d6aded28792c8a53b9a8
+  data.tar.gz: 8be2862ad184cb71e36a5b9d2747bfc5186fe8bf9c539b6d61fbe92d05a57e5c
 SHA512:
-  metadata.gz: 4116cfa7e4e06a1bff79489ddeced66af1803dedd6f2e1b1b5edd67db0d90e444922a87cfc2215a4e61357e54ddf988606c3ecce40e50afb24fdd5e06808a2bd
-  data.tar.gz: 558ec2ac88215ba2cde034380a27d44d0c989841942c070e4ea02a746d154944b094ae2aa6a9284c7cca6d310705634fde4f6566fbf8a268a0c1b33e41937107
+  metadata.gz: 3cb1367a63c3404a1dc79dd910265e5c189da7e8745b40c48f46e06d9b326f7a215760747c0273e28a51a26ff8e6447c376faf6a169d9f93cec84aac97191022
+  data.tar.gz: 3a3dc94969468b7ff5ef364876d068bf8fde231fcaeaa5ea6e43c207f7aafb236f02b5264b32678ad100788a1deb99caee79a3701cca1b4f79fd3a7f487865f1

data/CHANGELOG.md

@@ -9,6 +9,46 @@ User-visible changes worth mentioning.
 
 - 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
 
 - [#1834] Fix default `allow_token_introspection` returning `false` when a custom `application_class` is configured. The default proc compared application objects with `==`, which fails when the authorized client and the introspected token's application are resolved as different classes (e.g. a base `Doorkeeper::Application` vs. a configured subclass) even though they reference the same record. It now compares application ids instead.
@@ -27,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)

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/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/config/locales/en.yml

@@ -97,6 +97,7 @@ en:
           missing_param: 'Missing required parameter: %{value}.'
           request_not_authorized: 'Request needs to be authorized. Required parameter for authorizing the request is missing or invalid.'
           invalid_code_challenge: 'Code challenge is required.'
+          multiple_client_auth_methods: 'The request utilizes more than one mechanism for authenticating the client.'
         invalid_redirect_uri: "The requested redirect URI is malformed or doesn't match the client redirect URI."
         unauthorized_client: 'The client is not authorized to perform this request using this method.'
         access_denied: 'The resource owner or authorization server denied the request.'

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

data/lib/doorkeeper/config/validations.rb

@@ -8,14 +8,68 @@ module Doorkeeper
       # Validates configuration options to be set properly.
       #
       def validate!
+        validate_client_authentication_conflict
+        validate_client_authentication_registered
         validate_reuse_access_token_value
         validate_token_reuse_limit
         validate_secret_strategies
         validate_pkce_code_challenge_methods
+        validate_custom_metadata
+        validate_refresh_token_flow
+        validate_issuer_format
+        validate_issuer_metadata_discoverability
       end
 
       private
 
+      # Warn once, at configuration time, when both the deprecated
+      # +client_credentials+ and the new +client_authentication+ options are
+      # set. +client_authentication+ takes precedence; the warning lives here
+      # (rather than in the memoised resolver) so it is not swallowed and
+      # surfaces during boot instead of on the first request.
+      def validate_client_authentication_conflict
+        return unless instance_variable_defined?(:@client_credentials_methods) &&
+                      instance_variable_defined?(:@client_authentication)
+
+        ::Rails.logger.warn(
+          "[DOORKEEPER] Both client_credentials and client_authentication are set, " \
+          "using client_authentication",
+        )
+      end
+
+      # Warn about configured client authentication methods that are not
+      # registered (e.g. a typo, or an extension that failed to load). Such
+      # names are silently ignored when resolving the methods, which could
+      # otherwise leave the application with no usable authentication methods.
+      def validate_client_authentication_registered
+        # The deprecated client_credentials path already validates its own input.
+        return if instance_variable_defined?(:@client_credentials_methods) &&
+                  !instance_variable_defined?(:@client_authentication)
+
+        configured = client_authentication
+        unknown = configured.reject { |name| Doorkeeper::ClientAuthentication.get(name) }
+
+        unless unknown.empty?
+          ::Rails.logger.warn(
+            "[DOORKEEPER] Unknown client authentication method(s) configured and will be ignored: " \
+            "#{unknown.map(&:inspect).join(", ")}. " \
+            "Ensure each method is registered (e.g. by the extension that provides it).",
+          )
+        end
+
+        # A configuration that resolves to zero usable methods fails every
+        # client authentication attempt (all requests fall back to no
+        # credentials), so make that loud rather than silent.
+        return unless (configured - unknown).empty?
+
+        ::Rails.logger.error(
+          "[DOORKEEPER] No usable client authentication methods are configured " \
+          "(client_authentication resolved to an empty set). All client authentication " \
+          "will fail. Configure at least one registered method, e.g. " \
+          "client_authentication #{Doorkeeper::ClientAuthentication::DEFAULT_METHODS.inspect}.",
+        )
+      end
+
       # Determine whether +reuse_access_token+ and a non-restorable
       # +token_secret_strategy+ have both been activated.
       #
@@ -51,7 +105,15 @@ module Doorkeeper
       end
 
       def validate_pkce_code_challenge_methods
-        return if pkce_code_challenge_methods.all? { |method| method =~ /^plain$|^S256$/ }
+        methods = pkce_code_challenge_methods.map(&:to_s)
+        if methods.all? { |method| method.match?(/\A(?:plain|S256)\z/) }
+          # Persist the normalized (string) values only when the option was
+          # explicitly configured — the default is already normalized, and an
+          # unconfigured option should stay undefined rather than have
+          # validation flip its instance_variable_defined? signal.
+          @pkce_code_challenge_methods = methods if instance_variable_defined?(:@pkce_code_challenge_methods)
+          return
+        end
 
         ::Rails.logger.warn(
           "[DOORKEEPER] You have configured an invalid value for pkce_code_challenge_methods option. " \
@@ -60,6 +122,105 @@ module Doorkeeper
 
         @pkce_code_challenge_methods = ["plain", "S256"]
       end
+
+      def validate_custom_metadata
+        return if custom_metadata.is_a? Hash
+
+        ::Rails.logger.warn(
+          "[DOORKEEPER] You have configured an invalid value for custom_metadata option. " \
+          "It must be a Hash, and will be overridden with an empty hash.",
+        )
+
+        @custom_metadata = {}
+      end
+
+      # Warn when the refresh_token grant flow is enabled but refresh tokens
+      # are never issued: refresh token requests would always fail because
+      # there are no tokens to refresh. The flow is enabled automatically
+      # when +use_refresh_token+ is configured, so it doesn't need to be
+      # listed in +grant_flows+ explicitly.
+      #
+      # +calculate_grant_flows+ is used (rather than the raw +grant_flows+) so
+      # that the flow is also detected when enabled through a registered
+      # grant-flow alias. When +use_refresh_token+ is not configured the
+      # refresh_token flow is not appended implicitly, so its presence there
+      # means it was requested explicitly (directly or via an alias).
+      def validate_refresh_token_flow
+        return if refresh_token_enabled?
+        return unless calculate_grant_flows.map(&:to_s).include?("refresh_token")
+
+        ::Rails.logger.warn(
+          "[DOORKEEPER] You have enabled the refresh_token grant flow without " \
+          "configuring use_refresh_token, so refresh tokens will not be issued. " \
+          "Configure use_refresh_token to issue refresh tokens (the refresh_token " \
+          "grant flow is then enabled automatically).",
+        )
+      end
+
+      # Warn when a configured issuer is not RFC-compliant. RFC 8414 (the
+      # metadata issuer) and RFC 9207 (the authorization response iss parameter)
+      # both require an https URL with a host and no query or fragment component.
+      # The value is still used as-is - this is a warning, not a hard failure, so
+      # local setups using e.g. http://localhost keep working - but a
+      # non-compliant issuer produces responses that strict clients may reject.
+      def validate_issuer_format
+        return if issuer.blank?
+
+        uri =
+          begin
+            URI.parse(issuer.to_s)
+          rescue URI::InvalidURIError
+            nil
+          end
+
+        return if uri.is_a?(URI::HTTPS) && uri.host.present? &&
+                  uri.query.nil? && uri.fragment.nil?
+
+        ::Rails.logger.warn(
+          "[DOORKEEPER] issuer #{redacted_issuer.inspect} is not RFC-compliant: " \
+          "RFC 8414 and RFC 9207 require an https URL with a host and no query " \
+          "or fragment component. It is still advertised in the metadata and " \
+          "emitted as the iss parameter as-is, but strict clients may reject it.",
+        )
+      end
+
+      # Warn when a path-bearing issuer cannot be discovered. RFC 8414 clients
+      # build the metadata URL by inserting the well-known path into the issuer,
+      # so an issuer of https://host/tenant is looked up at
+      # https://host/.well-known/oauth-authorization-server/tenant. Doorkeeper
+      # only serves the document at the root well-known path, so such a value is
+      # not discoverable (and its advertised issuer would not match the lookup).
+      # This is a separate concern from validate_issuer_format: a path component
+      # is valid per RFC 8414, just unsupported by Doorkeeper's fixed route.
+      def validate_issuer_metadata_discoverability
+        return if issuer.blank?
+
+        uri =
+          begin
+            URI.parse(issuer.to_s)
+          rescue URI::InvalidURIError
+            nil
+          end
+
+        return if uri&.host.blank?
+        return if uri.path.blank? || uri.path == "/"
+
+        ::Rails.logger.warn(
+          "[DOORKEEPER] issuer #{redacted_issuer.inspect} has a path component, but " \
+          "Doorkeeper serves its RFC 8414 metadata only at the root " \
+          "/.well-known/oauth-authorization-server. RFC 8414 clients derive the " \
+          "metadata URL from the issuer path (…/.well-known/" \
+          "oauth-authorization-server#{uri.path}), so they will not discover the " \
+          "document. Use a host-only issuer, or route the derived well-known path " \
+          "to Doorkeeper.",
+        )
+      end
+
+      # Redact any userinfo (e.g. a misconfigured user:pass@host) before the
+      # issuer is written to the log, so credentials are not leaked there.
+      def redacted_issuer
+        issuer.to_s.sub(%r{//[^/@]*@}, "//***@")
+      end
     end
   end
 end