doorkeeper 5.9.7 → 6.0.0.beta1

data/lib/doorkeeper/oauth/metadata_response.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Doorkeeper
+  module OAuth
+    # OAuth 2.0 Authorization Server Metadata response as described in
+    # RFC 8414 (https://www.rfc-editor.org/rfc/rfc8414).
+    class MetadataResponse < BaseResponse
+      def initialize(base_url, url_builder)
+        super()
+        @base_url = base_url
+        @url_builder = url_builder
+      end
+
+      def body
+        @body ||= begin
+          data = {
+            # presence: a blank issuer (e.g. an unset env var) must fall back
+            # to base_url, matching the issuer.present? condition below so the
+            # two fields cannot disagree.
+            issuer: issuer.presence || @base_url,
+            # Only advertise endpoints whose controllers are installed. A
+            # controller disabled through skip_controllers has no routes mapping,
+            # so endpoint_for resolves it to nil and it is dropped below.
+            authorization_endpoint: authorization_endpoint,
+            token_endpoint: token_endpoint,
+            revocation_endpoint: revocation_endpoint,
+            introspection_endpoint: (introspection_endpoint if introspection_enabled?),
+            scopes_supported: scopes_supported,
+            response_types_supported: response_types_supported,
+            response_modes_supported: response_modes_supported,
+            grant_types_supported: grant_types_supported,
+            token_endpoint_auth_methods_supported: token_endpoint_auth_methods_supported,
+            code_challenge_methods_supported: code_challenge_methods_supported,
+            # RFC 9207: true only when an issuer is configured, matching the
+            # condition under which the iss parameter is emitted. false survives
+            # the compaction below, so it is advertised explicitly.
+            authorization_response_iss_parameter_supported: config.issuer.present?,
+          }
+          data.compact!
+
+          # userinfo_endpoint is intentionally advertised as null for backwards
+          # compatibility; it is meant to be populated through custom_metadata
+          # (e.g. by an OIDC extension), so it must survive the compaction above.
+          data[:userinfo_endpoint] = userinfo_endpoint
+
+          data.merge(custom_metadata)
+        end
+      end
+
+      def status
+        :ok
+      end
+
+      def headers
+        {
+          "Cache-Control" => "public",
+          "Content-Type" => "application/json; charset=utf-8",
+        }
+      end
+
+      private
+
+      def config
+        @config ||= Doorkeeper.configuration
+      end
+
+      def url_for(**args)
+        @url_builder.call(**args)
+      end
+
+      # Resolve the URL for the given route group, or nil when the group has no
+      # routes mapping (i.e. the controller was disabled via skip_controllers).
+      def endpoint_for(group, action:)
+        mapping = Doorkeeper::Rails::Routes.mapping[group]
+        return unless mapping
+
+        # The leading slash anchors the controller name: without it, Rails
+        # resolves the name relative to the current (doorkeeper/metadata)
+        # namespace whenever their segment depths differ, e.g. a configured
+        # `controllers tokens: "custom_tokens"` would be looked up as
+        # "doorkeeper/custom_tokens" and raise ActionController::UrlGenerationError.
+        url_for(controller: "/#{mapping[:controllers]}", action: action)
+      end
+
+      def custom_metadata
+        config.custom_metadata.symbolize_keys
+      end
+
+      def issuer
+        config.issuer
+      end
+
+      def authorization_endpoint
+        endpoint_for(:authorizations, action: "new")
+      end
+
+      def token_endpoint
+        endpoint_for(:tokens, action: "create")
+      end
+
+      def userinfo_endpoint
+        nil
+      end
+
+      def revocation_endpoint
+        endpoint_for(:tokens, action: "revoke")
+      end
+
+      def introspection_endpoint
+        endpoint_for(:tokens, action: "introspect")
+      end
+
+      def introspection_enabled?
+        Doorkeeper.configured? &&
+          !config.allow_token_introspection.is_a?(FalseClass)
+      end
+
+      def scopes_supported
+        config.scopes.to_a
+      end
+
+      def response_types_supported
+        config.authorization_response_types
+      end
+
+      def response_modes_supported
+        config.authorization_response_flows.flat_map(&:response_mode_matches).uniq
+      end
+
+      def grant_types_supported
+        # RFC 8414 lists token-endpoint grant type values (e.g.
+        # "authorization_code", "refresh_token"), so derive them from the
+        # flows that actually handle a grant_type and use their grant_type
+        # value rather than the configured flow name. This drops
+        # response-type-only flows such as :implicit and reports the real
+        # grant type for flows whose name differs from it (e.g. a URN).
+        config.token_grant_types
+      end
+
+      # The resolved methods (rather than the raw client_authentication names)
+      # reflect what the server actually accepts: unregistered names are
+      # dropped by the resolver, and a deprecated client_credentials-only
+      # configuration is honored as the source of truth. Legacy callable
+      # extractors have no registered method name a client could use, so they
+      # are not advertised.
+      def token_endpoint_auth_methods_supported
+        config.client_authentication_methods.filter_map do |method|
+          method.name.to_s if Doorkeeper::ClientAuthentication.get(method.name)
+        end
+      end
+
+      def code_challenge_methods_supported
+        config.pkce_code_challenge_methods_supported
+      end
+    end
+  end
+end

data/lib/doorkeeper/oauth/pre_authorization.rb

@@ -7,9 +7,9 @@ module Doorkeeper
 
       validate :client_id, error: Errors::InvalidRequest
       validate :client, error: Errors::InvalidClient
-      validate :client_supports_grant_flow, error: Errors::UnauthorizedClient
-      validate :resource_owner_authorize_for_client, error: Errors::InvalidClient
       validate :redirect_uri, error: Errors::InvalidRedirectUri
+      validate :client_supports_grant_flow, error: Errors::UnauthorizedClient
+      validate :resource_owner_authorize_for_client, error: Errors::AccessDenied
       validate :params, error: Errors::InvalidRequest
       validate :response_type, error: Errors::UnsupportedResponseType
       validate :response_mode, error: Errors::UnsupportedResponseMode
@@ -49,13 +49,21 @@ module Doorkeeper
       end
 
       def error_response
+        # RFC 9207: authorization error responses advertise the issuer. Passing
+        # the configured issuer here (nil when unset) scopes the iss parameter
+        # to the authorization endpoint only.
         if error == Errors::InvalidRequest
           OAuth::InvalidRequestResponse.from_request(
             self,
             response_on_fragment: response_on_fragment?,
+            issuer: Doorkeeper.config.issuer,
           )
         else
-          OAuth::ErrorResponse.from_request(self, response_on_fragment: response_on_fragment?)
+          OAuth::ErrorResponse.from_request(
+            self,
+            response_on_fragment: response_on_fragment?,
+            issuer: Doorkeeper.config.issuer,
+          )
         end
       end
 
@@ -147,7 +155,6 @@ module Doorkeeper
 
       def validate_code_challenge
         return true unless Doorkeeper.config.force_pkce?
-        return true if client.confidential
         return true if code_challenge.present?
 
         @invalid_request_reason = :invalid_code_challenge
@@ -180,7 +187,7 @@ module Doorkeeper
           scope: scope,
           client_name: client.name,
           status: I18n.t("doorkeeper.pre_authorization.status"),
-        }
+        }.reverse_merge(custom_access_token_attributes.symbolize_keys)
       end
     end
   end

data/lib/doorkeeper/oauth/token.rb

@@ -3,54 +3,8 @@
 module Doorkeeper
   module OAuth
     class Token
-      # Built-in extractors that read a request parameter, and the parameter
-      # each of them reads. RFC 6750 treats the form-encoded body (§2.2) and
-      # the URI query string (§2.3) as two distinct transmission methods, but
-      # Rack and ActionDispatch both collapse them into a single parameter
-      # hash — ActionDispatch lets the query win, Rack lets the body win — so
-      # a request carrying the parameter in both would present a single value
-      # to the extractor and never be refused. The multi-method check reads
-      # the two sources separately for these extractors; selection keeps
-      # using the extractor, so which one wins is unchanged.
-      PARAMETER_EXTRACTORS = {
-        from_access_token_param: "access_token",
-        from_bearer_param: "bearer_token",
-      }.freeze
-
       class << self
-        # RFC 6750 §2: "Clients MUST NOT use more than one method to transmit
-        # the token in each request", and §3.1 lists using more than one method
-        # among the conditions an invalid_request answers. Returning the first
-        # method that yields a value would discard every other token presented
-        # in the same request with no error, warning or log entry, leaving
-        # which token authorizes the request to be decided by the configured
-        # order of +access_token_methods+ rather than by what the caller sent —
-        # so a layer in front of Doorkeeper that reads a different one of them
-        # can reach a different verdict about the very same request.
-        #
-        # What §2 forbids is using more than one method, so the check counts
-        # transmission methods rather than comparing the tokens they carry:
-        # the same value presented twice is still two methods. Refusal answers
-        # nil: the caller is told the request carries no usable token and
-        # fails closed with the invalid_token (401) response, keeping every
-        # calling contract on this stable branch intact — the invalid_request
-        # (400) that §3.1 strictly prescribes needs a new error and render
-        # path, so it ships with 6.0 only.
-        #
-        # Only the built-in extractors — symbols naming methods on this class,
-        # all of them side-effect-free reads of the request — take part in
-        # that check. A custom callable extractor is a configuration adapter
-        # rather than a transmission method: it keeps the historical
-        # first-wins selection and is never invoked more than once, the same
-        # exemption client authentication gives its legacy callable
-        # extractors (Request#validate_client_authentication!).
         def from_request(request, *methods)
-          used = methods.sum do |method|
-            method.is_a?(Symbol) ? transmission_methods_used(request, method) : 0
-          end
-
-          return if used > 1
-
           methods.inject(nil) do |_, method|
             method = self.method(method) if method.is_a?(Symbol)
             credentials = method.call(request)
@@ -90,36 +44,6 @@ module Doorkeeper
 
         private
 
-        # How many transmission methods the given built-in extractor finds a
-        # token in. Usually one, or none — but for the parameter extractors
-        # above it is the body and the query counted separately, since the
-        # parameter hash collapsed them into the single value the extractor
-        # reads. That value is counted on its own only when neither raw source
-        # explains it, so a token reaching the extractor by some other route —
-        # an :access_token path segment, or a host that overrode the extractor
-        # — is still counted exactly once rather than twice.
-        def transmission_methods_used(request, method)
-          value = self.method(method).call(request).presence
-
-          parameter = PARAMETER_EXTRACTORS[method]
-          return value ? 1 : 0 unless parameter
-
-          sources = parameter_sources(request, parameter)
-          sources.size + (value && !sources.include?(value) ? 1 : 0)
-        end
-
-        # The form-encoded body (§2.2) and the URI query (§2.3) as Rack
-        # exposes them, for a request object that keeps the two apart.
-        def parameter_sources(request, parameter)
-          return [] unless request.respond_to?(:GET) && request.respond_to?(:POST)
-
-          query = request.GET
-          body = request.POST
-          return [] unless query.is_a?(Hash) && body.is_a?(Hash)
-
-          [query[parameter], body[parameter]].filter_map(&:presence)
-        end
-
         def token_from_basic_header(header, pattern)
           encoded_header = token_from_header(header, pattern)
           decode_basic_credentials_token(encoded_header)

data/lib/doorkeeper/oauth/token_introspection.rb

@@ -8,9 +8,13 @@ module Doorkeeper
     class TokenIntrospection
       attr_reader :token, :error, :invalid_request_reason
 
-      def initialize(server, token)
+      # +token_type+ tells which credential of the token record the caller
+      # actually received (:access_token or :refresh_token), so the "active"
+      # state and the response describe the presented token per RFC 7662 §2.2.
+      def initialize(server, token, token_type: :access_token)
         @server = server
         @token = token
+        @token_type = token_type
       end
 
       def authorized?
@@ -106,12 +110,19 @@ module Doorkeeper
           active: true,
           scope: @token.scopes_string,
           client_id: @token.try(:application).try(:uid),
-          token_type: @token.token_type,
           iat: @token.created_at.to_i,
         }
-        # `exp` is OPTIONAL per RFC 7662 §2.2; omit it for non-expiring tokens
-        # so clients don't interpret `0` as "expired at 1970-01-01".
-        response[:exp] = @token.expires_at.to_i if @token.expires_at
+
+        # `token_type` (RFC 6749 §7.1) and `exp` describe the access token:
+        # a refresh token is not a Bearer credential and has no expiry of its
+        # own, so both are omitted (they are OPTIONAL per RFC 7662 §2.2) when
+        # a refresh token is presented.
+        unless refresh_token_presented?
+          response[:token_type] = @token.token_type
+          # `exp` is OPTIONAL per RFC 7662 §2.2; omit it for non-expiring tokens
+          # so clients don't interpret `0` as "expired at 1970-01-01".
+          response[:exp] = @token.expires_at.to_i if @token.expires_at
+        end
 
         customize_response(response)
       end
@@ -176,9 +187,18 @@ module Doorkeeper
         end
       end
 
-      # Token can be valid only if it is not expired or revoked.
+      # The presented token can be valid only if it is not revoked; an access
+      # token must additionally be unexpired. A refresh token has no expiry of
+      # its own and stays usable at the token endpoint after its paired access
+      # token expires, so that expiry is not consulted here.
       def valid_token?
-        @token&.accessible?
+        return false if @token.blank?
+
+        refresh_token_presented? ? !@token.revoked? : @token.accessible?
+      end
+
+      def refresh_token_presented?
+        @token_type == :refresh_token
       end
 
       def valid_authorized_token?

data/lib/doorkeeper/orm/active_record/mixins/application.rb

@@ -116,9 +116,9 @@ module Doorkeeper::Orm::ActiveRecord::Mixins
 
         return generator if generator.respond_to?(:generate)
 
-        raise Errors::UnableToGenerateToken, "#{generator} does not respond to `.generate`."
+        raise Doorkeeper::Errors::UnableToGenerateToken, "#{generator} does not respond to `.generate`."
       rescue NameError
-        raise Errors::TokenGeneratorNotFound, "#{generator_name} not found"
+        raise Doorkeeper::Errors::TokenGeneratorNotFound, "#{generator_name} not found"
       end
 
       def generate_uid

data/lib/doorkeeper/rails/routes/mapping.rb

@@ -11,6 +11,7 @@ module Doorkeeper
             authorizations: "doorkeeper/authorizations",
             applications: "doorkeeper/applications",
             authorized_applications: "doorkeeper/authorized_applications",
+            metadata: "doorkeeper/metadata",
             tokens: "doorkeeper/tokens",
             token_info: "doorkeeper/token_info",
           }

data/lib/doorkeeper/rails/routes.rb

@@ -41,10 +41,16 @@ module Doorkeeper
           map_route(:authorized_applications, :authorized_applications_routes)
           map_route(:token_info, :token_info_routes)
         end
+
+        map_route(:metadata, :metadata_routes)
       end
 
       private
 
+      def metadata_routes(mapping)
+        routes.get ".well-known/oauth-authorization-server", controller: mapping[:controllers], action: :show
+      end
+
       def authorization_routes(mapping)
         routes.resource(
           :authorization,

data/lib/doorkeeper/request.rb

@@ -3,6 +3,28 @@
 module Doorkeeper
   module Request
     class << self
+      # Detect the OAuth client authentication method (RFC 6749 §2.3) that the
+      # given request uses. Returns the matching method's strategy (not the
+      # registry's Method wrapper), or FallbackMethod when none matches
+      # (which authenticates to no credentials).
+      #
+      # Raises Errors::MultipleClientAuthMethods when the request itself
+      # uses more than one client authentication method, since RFC 6749 §2.3
+      # forbids that (see +validate_client_authentication!+).
+      def client_authentication_method(request)
+        validate_client_authentication!(request)
+
+        authentication_method = client_authentication_methods.detect do |method|
+          method.matches_request?(request)
+        end
+
+        if authentication_method
+          authentication_method.strategy
+        else
+          Doorkeeper::ClientAuthentication::FallbackMethod
+        end
+      end
+
       def authorization_strategy(response_type)
         grant_flow = authorization_flows.detect do |flow|
           flow.matches_response_type?(response_type)
@@ -40,6 +62,43 @@ module Doorkeeper
 
       private
 
+      # RFC 6749 §2.3 forbids clients to "use more than one authentication
+      # method in each request", so the request payload is validated against
+      # every *registered* method — regardless of which ones are configured —
+      # before any method is selected: a client sending, say, both Basic
+      # credentials and body credentials is rejected even when only one of
+      # those methods is enabled on the server.
+      #
+      # Only real authentication mechanisms count towards the limit:
+      #
+      # * +:none+ is the absence of client authentication (a public client
+      #   identifying itself with a bare +client_id+), not a mechanism of its
+      #   own — RFC 7521 §4.2, for example, explicitly allows a +client_id+
+      #   next to a client assertion.
+      # * Deprecated +client_credentials+ callable extractors are
+      #   configuration adapters rather than registered methods, so they
+      #   cannot count either; they keep the historical "first extractor that
+      #   returns a uid wins" selection (see
+      #   ClientAuthentication::LegacyCallable) for the deprecation window.
+      def validate_client_authentication!(request)
+        matched = 0
+
+        Doorkeeper::ClientAuthentication.registered_methods.each_value do |method|
+          next if method.name == :none
+          next unless method.matches_request?(request)
+
+          matched += 1
+
+          # RFC 6749 §2.3 only forbids using more than one method, so bail out
+          # on the second match instead of evaluating the remaining methods.
+          raise Errors::MultipleClientAuthMethods if matched > 1
+        end
+      end
+
+      def client_authentication_methods
+        Doorkeeper.configuration.client_authentication_methods
+      end
+
       def authorization_flows
         Doorkeeper.configuration.authorization_response_flows
       end

data/lib/doorkeeper/server.rb

@@ -8,6 +8,10 @@ module Doorkeeper
       @context = context
     end
 
+    def client_authentication_method_for_request
+      Request.client_authentication_method(context.request)
+    end
+
     def authorization_request(strategy)
       klass = Request.authorization_strategy(strategy)
       klass.new(self)
@@ -37,8 +41,7 @@ module Doorkeeper
     end
 
     def credentials
-      methods = Doorkeeper.config.client_credentials_methods
-      @credentials ||= OAuth::Client::Credentials.from_request(context.request, *methods)
+      @credentials ||= client_authentication_method_for_request.authenticate(context.request)
     end
   end
 end

data/lib/doorkeeper/version.rb

@@ -3,10 +3,10 @@
 module Doorkeeper
   module VERSION
     # Semantic versioning
-    MAJOR = 5
-    MINOR = 9
-    TINY = 7
-    PRE = nil
+    MAJOR = 6
+    MINOR = 0
+    TINY = 0
+    PRE = "beta1"
 
     # Full version number
     STRING = [MAJOR, MINOR, TINY, PRE].compact.join(".")

data/lib/doorkeeper.rb

@@ -7,6 +7,7 @@ require "doorkeeper/engine"
 #
 module Doorkeeper
   autoload :Errors, "doorkeeper/errors"
+  autoload :ClientAuthentication, "doorkeeper/client_authentication"
   autoload :GrantFlow, "doorkeeper/grant_flow"
   autoload :OAuth, "doorkeeper/oauth"
   autoload :Rake, "doorkeeper/rake"
@@ -52,6 +53,7 @@ module Doorkeeper
     autoload :InvalidTokenResponse, "doorkeeper/oauth/invalid_token_response"
     autoload :InvalidRequestResponse, "doorkeeper/oauth/invalid_request_response"
     autoload :ForbiddenTokenResponse, "doorkeeper/oauth/forbidden_token_response"
+    autoload :MetadataResponse, "doorkeeper/oauth/metadata_response"
     autoload :NonStandard, "doorkeeper/oauth/nonstandard"
     autoload :PasswordAccessTokenRequest, "doorkeeper/oauth/password_access_token_request"
     autoload :PreAuthorization, "doorkeeper/oauth/pre_authorization"
@@ -62,6 +64,12 @@ module Doorkeeper
     autoload :TokenRequest, "doorkeeper/oauth/token_request"
     autoload :TokenResponse, "doorkeeper/oauth/token_response"
 
+    module ClientAuthentication
+      autoload :None, "doorkeeper/oauth/client_authentication/none"
+      autoload :ClientSecretBasic, "doorkeeper/oauth/client_authentication/client_secret_basic"
+      autoload :ClientSecretPost, "doorkeeper/oauth/client_authentication/client_secret_post"
+    end
+
     module Authorization
       autoload :Code, "doorkeeper/oauth/authorization/code"
       autoload :Context, "doorkeeper/oauth/authorization/context"
@@ -69,10 +77,6 @@ module Doorkeeper
       autoload :URIBuilder, "doorkeeper/oauth/authorization/uri_builder"
     end
 
-    class Client
-      autoload :Credentials, "doorkeeper/oauth/client/credentials"
-    end
-
     module ClientCredentials
       autoload :Validator, "doorkeeper/oauth/client_credentials/validator"
       autoload :Creator, "doorkeeper/oauth/client_credentials/creator"

data/lib/generators/doorkeeper/templates/initializer.rb

@@ -150,6 +150,15 @@ Doorkeeper.configure do
   # token found for the application, resources owner and/or set of scopes.
   # Rationale: https://github.com/doorkeeper-gem/doorkeeper/issues/383
   #
+  # Matching considers only the application, resource owner, scopes, custom access token
+  # attributes (see +custom_access_token_attributes+) and whether a refresh token is
+  # expected — not the authorization request that produced the token. Separate authorization
+  # grants for the same combination share a single access token, so concurrent sessions of
+  # the same client become interdependent (e.g. refreshing the token in one session revokes
+  # it for the others). If you need independent tokens per session or device, keep this
+  # option disabled or differentiate the sessions with +custom_access_token_attributes+.
+  # See https://github.com/doorkeeper-gem/doorkeeper/issues/1693
+  #
   # You can not enable this option together with +hash_token_secrets+.
   #
   # reuse_access_token
@@ -188,8 +197,8 @@ Doorkeeper.configure do
   #
   # revoke_previous_authorization_code_token
 
-  # Require non-confidential clients to use PKCE when using an authorization code
-  # to obtain an access_token (disabled by default)
+  # Require all clients (including confidential ones) to use PKCE when using an
+  # authorization code to obtain an access_token (disabled by default)
   #
   # force_pkce
 
@@ -277,21 +286,18 @@ Doorkeeper.configure do
   #
   # enforce_configured_scopes
 
-  # Change the way client credentials are retrieved from the request object.
-  # By default it retrieves first from the `HTTP_AUTHORIZATION` header, then
-  # falls back to the `:client_id` and `:client_secret` params from the `params` object.
+  # Configure the OAuth client authentication methods (RFC 6749 §2.3) Doorkeeper
+  # will accept and the order in which they are tried. By default it accepts
+  # HTTP Basic auth (`client_secret_basic`), credentials in the request body
+  # (`client_secret_post`), and public clients with no secret (`none`).
   # Check out https://github.com/doorkeeper-gem/doorkeeper/wiki/Changing-how-clients-are-authenticated
   # for more information on customization
   #
-  # NOTE: configuring a callable extractor opts the request out of the RFC 6749
-  # §2.3 checks that reject a request authenticating the client with more than
-  # one method, or presenting more than one client identity. A callable may
-  # legitimately overlap the built-in extractors, and the extractors after the
-  # matching one are never called, so what they would have returned is unknown.
-  # Prefer the symbol extractors unless you need something they cannot express;
-  # a callable has to reject such a request itself.
+  # client_authentication %i[client_secret_basic client_secret_post none]
   #
-  # client_credentials :from_basic, :from_params
+  # The legacy `client_credentials` option is deprecated; `:from_basic` and
+  # `:from_params` are automatically mapped to `:client_secret_basic` and
+  # `:client_secret_post`.
 
   # Change the way access token is authenticated from the request object.
   # By default it retrieves first from the `HTTP_AUTHORIZATION` header, then
@@ -385,6 +391,9 @@ Doorkeeper.configure do
   # If not specified, Doorkeeper enables authorization_code and
   # client_credentials.
   #
+  # The Refresh Token Grant Flow ("refresh_token") doesn't need to be listed
+  # here: it is enabled automatically when +use_refresh_token+ is configured.
+  #
   # implicit and password grant flows have risks that you should understand
   # before enabling:
   #   https://datatracker.ietf.org/doc/html/rfc6819#section-4.4.2
@@ -549,4 +558,47 @@ Doorkeeper.configure do
   # WWW-Authenticate Realm (default: "Doorkeeper").
   #
   # realm "Doorkeeper"
+
+  # OAuth 2.0 Authorization Server Metadata (RFC 8414).
+  #
+  # Doorkeeper exposes an authorization server metadata document at
+  # `/.well-known/oauth-authorization-server`, built from the configuration
+  # above. The two options below let you customize that document.
+  #
+  # `issuer` is the authorization server's issuer identifier. When left as nil
+  # (the default) the request base URL is used for the metadata `issuer` field
+  # only. Note the asymmetry: RFC 9207 below is gated on an explicitly
+  # configured issuer, so leaving it nil still advertises a metadata `issuer`
+  # (the base URL) while `authorization_response_iss_parameter_supported` stays
+  # false and no `iss` parameter is emitted.
+  #
+  # Configuring an issuer also enables RFC 9207 (Authorization Server Issuer
+  # Identification): the `iss` parameter is added to the authorization
+  # responses redirected back to the client - both successful responses and
+  # error responses such as access_denied - and advertised via the
+  # `authorization_response_iss_parameter_supported` metadata field. Clients
+  # that parse the authorization redirect will start seeing this parameter.
+  # Per RFC 8414 and RFC 9207 the value should be an https URL with no query or
+  # fragment; a non-compliant value logs a warning at boot but is still used.
+  # Prefer a host-only issuer: Doorkeeper serves its metadata only at the root
+  # /.well-known/oauth-authorization-server, so a path-bearing issuer (e.g.
+  # https://auth.example.com/tenant) is not discoverable by RFC 8414 clients and
+  # also logs a warning.
+  #
+  # issuer "https://auth.example.com"
+  #
+  # `custom_metadata` is a Hash that is merged into the metadata response. Use
+  # it to advertise additional or non-default metadata fields, for example a
+  # `userinfo_endpoint` (which Doorkeeper itself leaves null) when pairing with
+  # an OpenID Connect extension.
+  #
+  # The merge happens last, so it can also override computed fields - including
+  # `authorization_response_iss_parameter_supported`, which Doorkeeper derives
+  # from whether `issuer` is set. Overriding a computed field is allowed but is
+  # your responsibility to keep consistent with the server's actual behaviour
+  # (e.g. don't advertise iss support as true if no `issuer` is configured).
+  #
+  # custom_metadata(
+  #   userinfo_endpoint: "https://auth.example.com/oauth/userinfo",
+  # )
 end