doorkeeper 5.9.5 → 6.0.0.beta2

data/lib/doorkeeper/client_authentication/legacy_callable.rb

@@ -0,0 +1,52 @@
+# 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
+
+      # Legacy extractors pull a uid/secret pair out of the request, so they
+      # are treated as shared-secret methods.
+      def uses_shared_secret?
+        true
+      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,40 @@
+# 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
+
+      # Whether this method authenticates clients with a shared symmetric
+      # secret. Callers that must refuse such methods — because no secret
+      # can have been established with the client — can ask the registry
+      # instead of keeping a hard-coded list of method names.
+      #
+      # Strategies may declare this themselves by defining
+      # +uses_shared_secret?+; for strategies that don't, the registration
+      # name is checked for "client_secret" as a conservative fallback, so an
+      # undeclared method errs on the side of being treated as secret-based.
+      def uses_shared_secret?
+        if strategy.respond_to?(:uses_shared_secret?)
+          strategy.uses_shared_secret?
+        else
+          name.to_s.include?("client_secret")
+        end
+      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/verified_credentials.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Doorkeeper
+  module ClientAuthentication
+    # Credentials for a client that was already fully authenticated by its
+    # authentication method (e.g. a verified private_key_jwt assertion), so
+    # the client lookup must not run a secret comparison — there is no
+    # secret, and the proof of identity has already been checked.
+    class VerifiedCredentials < Credentials
+      def initialize(uid)
+        super(uid, nil)
+      end
+
+      def pre_authenticated?
+        true
+      end
+    end
+  end
+end

data/lib/doorkeeper/client_authentication.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "doorkeeper/client_authentication/credentials"
+require "doorkeeper/client_authentication/verified_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,
+    )
+
+    # Registered but not part of DEFAULT_METHODS: servers opt in through the
+    # +client_authentication+ config option. Requires the "jwt" gem at the
+    # moment an assertion is authenticated.
+    register(
+      :private_key_jwt,
+      Doorkeeper::OAuth::ClientAuthentication::PrivateKeyJwt,
+    )
+
+    # 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