doorkeeper 5.9.3 → 6.0.0.beta1

data/lib/doorkeeper/config.rb

@@ -65,13 +65,50 @@ module Doorkeeper
       end
 
       # 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.
+      #
+      # @deprecated Use the +client_authentication+ option instead. The legacy
+      #   +:from_basic+ / +:from_params+ methods are automatically converted to
+      #   the +:client_secret_basic+ / +:client_secret_post+ authentication
+      #   methods. +:none+ (public client support) is appended only when
+      #   +:from_params+ was configured, since that is the only legacy method
+      #   that accepted a bare +client_id+ without a secret — +:from_basic+ on
+      #   its own never did, so it is not broadened. Callable extractors are
+      #   wrapped in a legacy adapter so they keep working during the
+      #   deprecation window.
       #
       # @param methods [Array] Define client credentials
       def client_credentials(*methods)
-        @config.instance_variable_set(:@client_credentials_methods, methods)
+        deprecated(
+          "client_credentials",
+          "Use the client_authentication option instead. Automatically converting to client_authentication",
+        )
+
+        client_authentication = Doorkeeper::ClientAuthentication.from_legacy_client_credentials(methods)
+
+        if client_authentication.empty?
+          Kernel.warn(
+            "[DOORKEEPER] No known client_credentials method detected, " \
+            "cannot automatically convert to client_authentication option",
+          )
+        else
+          @config.instance_variable_set(:@client_credentials_methods, client_authentication)
+        end
+      end
+
+      # Declare which client authentication methods (RFC 6749 §2.3) are
+      # accepted and the order in which they are tried. Accepts either an array
+      # or varargs, so both forms are honoured exactly as written:
+      #
+      #   client_authentication %i[client_secret_basic client_secret_post none]
+      #   client_authentication :client_secret_basic, :client_secret_post
+      #
+      # Unlike the deprecated +client_credentials+ option, the listed methods
+      # are used verbatim — nothing (in particular +:none+) is appended, so a
+      # restrictive configuration is never silently broadened.
+      #
+      # @param methods [Array<Symbol>] the client authentication method names
+      def client_authentication(*methods)
+        @config.instance_variable_set(:@client_authentication, methods.flatten)
       end
 
       # Change the way access token is authenticated from the request object.
@@ -202,6 +239,13 @@ module Doorkeeper
 
       private
 
+      def deprecated(name, message = nil)
+        warning = "[DOORKEEPER] #{name} has been deprecated and will soon be removed"
+        warning = "#{warning}\n#{message}" if message.present?
+
+        Kernel.warn(warning)
+      end
+
       # Configure the secret storing functionality
       def configure_secrets_for(type, using:, fallback:)
         raise ArgumentError, "Invalid type #{type}" if %i[application token].exclude?(type)
@@ -337,6 +381,10 @@ module Doorkeeper
     #
     option :realm,                          default: "Doorkeeper"
 
+    # Issuer URL advertised in the OAuth 2.0 Authorization Server Metadata
+    # (RFC 8414). When nil, the request base URL is used instead.
+    option :issuer,                         default: nil
+
     # Forces the usage of the HTTPS protocol in non-native redirect uris
     # (enabled by default in non-development environments). OAuth2
     # delegates security in communication to the HTTPS protocol so it is
@@ -413,6 +461,10 @@ module Doorkeeper
     option :application_class,
            default: "Doorkeeper::Application"
 
+    # Allows setting a hash of custom data merged into the OAuth 2.0
+    # Authorization Server Metadata response (RFC 8414).
+    option :custom_metadata, default: {}
+
     # Allows to set blank redirect URIs for Applications in case
     # server configured to use URI-less grant flows.
     #
@@ -596,8 +648,57 @@ module Doorkeeper
       pkce_code_challenge_methods
     end
 
+    # Resolves the configured client authentication methods (RFC 6749 §2.3)
+    # into the registered +Doorkeeper::ClientAuthentication::Method+ objects.
+    #
+    # Honors the deprecated +client_credentials+ option for backwards
+    # compatibility: if it was used it provides the source of truth, unless
+    # +client_authentication+ was also set explicitly, in which case the
+    # latter wins.
+    def client_authentication_methods
+      return @client_authentication_methods if defined?(@client_authentication_methods)
+
+      # When both the deprecated +client_credentials+ and the new
+      # +client_authentication+ are set, +client_authentication+ wins. The
+      # conflict is warned about at validation time (see Validations), not here,
+      # so the message is not swallowed by this memoised resolver.
+      only_legacy = instance_variable_defined?(:@client_credentials_methods) &&
+                    !instance_variable_defined?(:@client_authentication)
+      names = only_legacy ? @client_credentials_methods : client_authentication
+
+      # Names configured more than once resolve to the same registered Method
+      # instance, so identity-based #uniq drops the duplicates (which would
+      # otherwise be matched against requests twice and advertised twice in
+      # the server metadata) while distinct legacy callable adapters survive.
+      @client_authentication_methods = names.filter_map do |name|
+        # Legacy callables are already wrapped as Method adapters (see #client_credentials).
+        name.is_a?(Doorkeeper::ClientAuthentication::Method) ? name : Doorkeeper::ClientAuthentication.get(name)
+      end.uniq
+    end
+
+    # The configured client authentication method names (RFC 6749 §2.3),
+    # defaulting to the registry's DEFAULT_METHODS when not set.
+    def client_authentication
+      return Doorkeeper::ClientAuthentication::DEFAULT_METHODS.dup unless instance_variable_defined?(:@client_authentication)
+
+      @client_authentication
+    end
+
+    # @deprecated Renamed to +client_authentication_methods+. This alias keeps
+    #   external callers (e.g. doorkeeper-openid_connect) working for one release
+    #   and will be removed afterwards. It returns the legacy symbol names
+    #   (e.g. +:from_basic+) rather than the internal Method objects so that
+    #   consumers mapping from those symbols keep working unchanged.
     def client_credentials_methods
-      @client_credentials_methods ||= %i[from_basic from_params]
+      unless defined?(@client_credentials_methods_rename_warned)
+        Kernel.warn(
+          "[DOORKEEPER] Doorkeeper.config.client_credentials_methods has been renamed to " \
+          "client_authentication_methods and will be removed in a future version.",
+        )
+        @client_credentials_methods_rename_warned = true
+      end
+
+      Doorkeeper::ClientAuthentication.to_legacy_client_credentials_names(client_authentication_methods)
     end
 
     def access_token_methods
@@ -665,13 +766,17 @@ module Doorkeeper
     def calculate_token_grant_types
       types = grant_flows - ["implicit"]
       types << "refresh_token" if refresh_token_enabled?
-      types
+      types.uniq
     end
 
     # Calculates grant flows configured by the user in Doorkeeper
     # configuration considering registered aliases that is exposed
     # to single or multiple other flows.
     #
+    # The refresh_token flow is added implicitly when +use_refresh_token+
+    # is configured, so the result lists every enabled flow (useful for
+    # RFC 8414 authorization server metadata).
+    #
     def calculate_grant_flows
       configured_flows = grant_flows.map(&:to_s)
       aliases = Doorkeeper::GrantFlow.aliases.keys.map(&:to_s)
@@ -683,6 +788,8 @@ module Doorkeeper
         flows.concat(Doorkeeper::GrantFlow.expand_alias(flow_alias))
       end
 
+      flows << "refresh_token" if refresh_token_enabled?
+
       flows.flatten.uniq
     end
 
@@ -713,9 +820,7 @@ module Doorkeeper
     end
 
     def calculate_token_grant_flows
-      flows = enabled_grant_flows.select(&:handles_grant_type?)
-      flows << Doorkeeper::GrantFlow.get("refresh_token") if refresh_token_enabled?
-      flows
+      enabled_grant_flows.select(&:handles_grant_type?)
     end
   end
 end

data/lib/doorkeeper/errors.rb

@@ -24,6 +24,19 @@ module Doorkeeper
       end
     end
 
+    # Raised when a request uses more than one client authentication method,
+    # which RFC 6749 §2.3 explicitly forbids ("The client MUST NOT use more
+    # than one authentication method in each request").
+    class MultipleClientAuthMethods < DoorkeeperError
+      def type
+        :invalid_request
+      end
+
+      def reason
+        :multiple_client_auth_methods
+      end
+    end
+
     class MissingRequiredParameter < DoorkeeperError
       attr_reader :missing_param
 
@@ -62,6 +75,7 @@ module Doorkeeper
     UnableToGenerateToken = Class.new(DoorkeeperError)
     TokenGeneratorNotFound = Class.new(DoorkeeperError)
     NoOrmCleaner = Class.new(DoorkeeperError)
+    MissingConfigurationBuilderClass = Class.new(DoorkeeperError)
 
     InvalidRequest = Class.new(BaseResponseError)
     InvalidToken = Class.new(BaseResponseError)

data/lib/doorkeeper/helpers/controller.rb

@@ -56,7 +56,8 @@ module Doorkeeper
           OAuth::InvalidRequestResponse.new(
             name: exception.type,
             state: params[:state],
-            missing_param: exception.missing_param,
+            missing_param: exception.try(:missing_param),
+            reason: exception.try(:reason),
           )
         else
           OAuth::ErrorResponse.new(name: exception.type, state: params[:state])

data/lib/doorkeeper/models/access_token_mixin.rb

@@ -89,15 +89,19 @@ module Doorkeeper
       # @param custom_attributes [Nilable Hash]
       #   A nil value, or hash with keys corresponding to the custom attributes
       #   configured with the `custom_access_token_attributes` config option.
-      #   A nil value will ignore custom attributes.
+      #   A nil value will ignore custom attributes, while an empty hash will
+      #   only match tokens that have no custom attributes set.
+      #
+      # @yield [token] optional additional predicate a token must satisfy to
+      #   count as a match (e.g. the refresh token requirement of the request).
       #
       # @return [Doorkeeper::AccessToken, nil] Access Token instance or
       #   nil if matching record was not found
       #
-      def matching_token_for(application, resource_owner, scopes, custom_attributes: nil, include_expired: true)
+      def matching_token_for(application, resource_owner, scopes, custom_attributes: nil, include_expired: true, &filter)
         tokens = authorized_tokens_for(application&.id, resource_owner)
         tokens = tokens.not_expired unless include_expired
-        find_matching_token(tokens, application, custom_attributes, scopes)
+        find_matching_token(tokens, application, custom_attributes, scopes, &filter)
       end
 
       # Interface to enumerate access token records in batches in order not
@@ -124,12 +128,13 @@ module Doorkeeper
       # @param custom_attributes [Nilable Hash]
       #   A nil value, or hash with keys corresponding to the custom attributes
       #   configured with the `custom_access_token_attributes` config option.
-      #   A nil value will ignore custom attributes.
+      #   A nil value will ignore custom attributes, while an empty hash will
+      #   only match tokens that have no custom attributes set.
       #
       # @return [Doorkeeper::AccessToken, nil] Access Token instance or
       #   nil if matching record was not found
       #
-      def find_matching_token(relation, application, custom_attributes, scopes)
+      def find_matching_token(relation, application, custom_attributes, scopes, &filter)
         return nil unless relation
 
         matching_tokens = []
@@ -138,7 +143,8 @@ module Doorkeeper
         find_access_token_in_batches(relation, batch_size: batch_size) do |batch|
           tokens = batch.select do |token|
             scopes_match?(token.scopes, scopes, application&.scopes) &&
-              custom_attributes_match?(token, custom_attributes)
+              custom_attributes_match?(token, custom_attributes) &&
+              (filter.nil? || filter.call(token))
           end
 
           matching_tokens.concat(tokens)
@@ -147,6 +153,32 @@ module Doorkeeper
         matching_tokens.max_by(&:created_at)
       end
 
+      # Checks whether a candidate token for reuse matches the refresh token
+      # requirement of the current request.
+      #
+      # The candidate's refresh token presence must match what the request asks
+      # for, in both directions. A request that expects a refresh token (e.g. an
+      # authorization_code or password grant while `use_refresh_token` is
+      # enabled) must not reuse a token issued without one, or the response would
+      # silently omit the refresh token. Conversely, a request that does not ask
+      # for a refresh token must not reuse a token that carries one, or the
+      # response would return a refresh token the request never requested (this
+      # is reachable when `refresh_token_enabled` is a per-request callable).
+      # When no matching token satisfies the requirement a fresh token is
+      # issued instead.
+      #
+      # @param access_token [Doorkeeper::AccessToken]
+      #   the candidate token for reuse
+      # @param token_attributes [Hash]
+      #   attributes for the token being requested
+      #
+      # @return [Boolean] true if the candidate token's refresh token presence
+      #   matches the request's refresh token requirement, false otherwise
+      #
+      def refresh_token_matches?(access_token, token_attributes)
+        access_token.refresh_token.present? == !!token_attributes[:use_refresh_token]
+      end
+
       # Checks whether the token scopes match the scopes from the parameters
       #
       # @param token_scopes [#to_s]
@@ -220,10 +252,18 @@ module Doorkeeper
         scopes = Doorkeeper::OAuth::Scopes.from_string(scopes) if scopes.is_a?(String)
 
         if Doorkeeper.config.reuse_access_token
-          custom_attributes = extract_custom_attributes(token_attributes).presence
+          # An empty hash must stay distinct from nil here: nil ignores custom
+          # attributes when matching, while an empty hash only matches tokens
+          # that have no custom attributes set.
+          custom_attributes = extract_custom_attributes(token_attributes)
+          # The refresh token requirement participates in the matching itself
+          # rather than being checked on its single newest result: the newest
+          # matching token may carry the wrong refresh token presence (e.g. it
+          # was issued through a grant with a different `use_refresh_token`)
+          # while an older token satisfies the request and can still be reused.
           access_token = matching_token_for(
             application, resource_owner, scopes, custom_attributes: custom_attributes, include_expired: false,
-          )
+          ) { |token| refresh_token_matches?(token, token_attributes) }
 
           return access_token if access_token&.reusable?
         end

data/lib/doorkeeper/models/application_mixin.rb

@@ -5,6 +5,7 @@ module Doorkeeper
     extend ActiveSupport::Concern
 
     include OAuth::Helpers
+    include Models::Concerns::WriteToPrimary
     include Models::Orderable
     include Models::SecretStorable
     include Models::Scopes
@@ -27,9 +28,8 @@ module Doorkeeper
         app = by_uid(uid)
         return unless app
         return app if secret.blank? && !app.confidential?
-        return unless app.secret_matches?(secret)
 
-        app
+        app if app.secret_matches?(secret)
       end
 
       # Returns an instance of the Doorkeeper::Application with specific UID.
@@ -76,18 +76,26 @@ module Doorkeeper
     # @return [Boolean] Whether the given secret matches the stored secret
     #                of this application.
     #
+    # @note When the secret matches only via the fallback strategy, the stored
+    #       secret is upgraded to the active strategy as a side-effect (mirrors
+    #       the find_by_plaintext_token -> find_by_fallback_token pattern).
+    #
     def secret_matches?(input)
       # return false if either is nil, since secure_compare depends on strings
       # but Application secrets MAY be nil depending on confidentiality.
       return false if input.nil? || secret.nil?
 
+      input = input.to_s
+
       # When matching the secret by comparer function, all is well.
       return true if secret_strategy.secret_matches?(input, secret)
 
-      # When fallback lookup is enabled, ensure applications
-      # with plain secrets can still be found
-      if fallback_secret_strategy
-        fallback_secret_strategy.secret_matches?(input, secret)
+      # When fallback lookup is enabled, ensure applications with plain secrets
+      # can still be found, upgrading the stored secret to the active strategy
+      # on a successful match.
+      if fallback_secret_strategy&.secret_matches?(input, secret)
+        self.class.upgrade_fallback_value(self, :secret, input)
+        true
       else
         false
       end

data/lib/doorkeeper/models/concerns/secret_storable.rb

@@ -84,7 +84,16 @@ module Doorkeeper
         #
         def upgrade_fallback_value(instance, attr, plain_secret)
           upgraded = secret_strategy.store_secret(instance, attr, plain_secret)
-          instance.update(attr => upgraded)
+
+          # The upgrade is a write on what is otherwise a read path (finding a
+          # record by its secret), so it must reach the primary database when
+          # automatic role switching would route the surrounding request to a
+          # read replica.
+          if respond_to?(:with_primary_role)
+            with_primary_role { instance.update(attr => upgraded) }
+          else
+            instance.update(attr => upgraded)
+          end
         end
 
         ##

data/lib/doorkeeper/oauth/authorization/uri_builder.rb

@@ -10,6 +10,17 @@ module Doorkeeper
           def uri_with_query(url, parameters = {})
             uri = URI.parse(url)
             original_query = Rack::Utils.parse_query(uri.query)
+            # `parse_query` yields string keys while `parameters` uses symbol
+            # keys, so a naive merge cannot dedupe a collision (e.g. a registered
+            # redirect_uri already carrying `state`) and would emit the param
+            # twice. Normalize keys so the response parameters win over any
+            # same-named query already present in the redirect_uri. Blank
+            # response parameters are dropped before the merge: they carry no
+            # value to respond with, and letting them clobber a same-named
+            # registered parameter would violate RFC 6749 §3.1.2 (the registered
+            # query component "MUST be retained when adding additional query
+            # parameters").
+            parameters = parameters.transform_keys(&:to_s).reject { |_, value| value.blank? }
             uri.query = build_query(original_query.merge(parameters))
             uri.to_s
           end

data/lib/doorkeeper/oauth/authorization_code_request.rb

@@ -13,6 +13,9 @@ module Doorkeeper
       attr_reader :grant, :client, :redirect_uri, :access_token, :code_verifier,
                   :invalid_request_reason, :missing_param
 
+      # A scope parameter is deliberately not read here: RFC 6749 does not
+      # define one for the authorization_code token request (§4.1.3), so it
+      # is ignored and the access token inherits the scopes of the grant.
       def initialize(server, grant, client, parameters = {})
         super()
         @server = server
@@ -64,7 +67,7 @@ module Doorkeeper
         @missing_param =
           if grant&.uses_pkce? && code_verifier.blank?
             :code_verifier
-          elsif client && !client.confidential && Doorkeeper.config.force_pkce? && code_verifier.blank?
+          elsif client && Doorkeeper.config.force_pkce? && code_verifier.blank?
             :code_verifier
           elsif redirect_uri.blank?
             :redirect_uri

data/lib/doorkeeper/oauth/client.rb

@@ -1,8 +1,26 @@
 # frozen_string_literal: true
 
+# The full registry rather than just credentials: requiring only
+# client_authentication/credentials fires the ClientAuthentication autoload
+# mid-load, which re-requires the in-progress file and warns under -w
+# ("circular require considered harmful").
+require "doorkeeper/client_authentication"
+
 module Doorkeeper
   module OAuth
     class Client
+      # @deprecated Moved to +Doorkeeper::ClientAuthentication::Credentials+.
+      #   This alias keeps the long-standing +Doorkeeper::OAuth::Client::Credentials+
+      #   constant resolvable for one release so referencing code does not raise
+      #   +NameError+; update references to the new constant. Note the legacy
+      #   +.from_request+/+.from_basic+/+.from_params+ class methods are gone —
+      #   client credential extraction now goes through the client authentication
+      #   registry (RFC 6749 §2.3). Marked with +deprecate_constant+, so Ruby
+      #   warns on access when deprecation warnings are enabled
+      #   (+Warning[:deprecated] = true+ or +-W:deprecated+).
+      Credentials = Doorkeeper::ClientAuthentication::Credentials
+      deprecate_constant :Credentials
+
       attr_reader :application
 
       delegate :id, :name, :uid, :redirect_uri, :scopes, :confidential, to: :@application

data/lib/doorkeeper/oauth/client_authentication/client_secret_basic.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Doorkeeper
+  module OAuth
+    module ClientAuthentication
+      # RFC 6749 §2.3.1 "client_secret_basic": client credentials are sent
+      # using HTTP Basic authentication.
+      #
+      # Known deviation: §2.3.1 also requires the client_id and client_secret
+      # to be form-urlencoded before being placed into the Basic header.
+      # Doorkeeper has never URL-decoded them (like much of the ecosystem),
+      # and this strategy deliberately keeps that behaviour — adding the
+      # decoding now would break every existing client whose credentials
+      # contain URL-encodable characters.
+      class ClientSecretBasic
+        # Match whenever the header decodes to a non-blank +client_id+ — i.e.
+        # whenever a Basic authentication *attempt* is present. The secret may
+        # be empty (public clients) or missing; those are still Basic auth
+        # attempts and must be claimed here so that invalid credentials fail
+        # with +invalid_client+ instead of silently falling through to another
+        # configured method or the fallback (which would downgrade a failed
+        # authentication attempt to "no authentication provided").
+        def self.matches_request?(request)
+          credentials_from(request).present?
+        end
+
+        def self.authenticate(request)
+          client_id, client_secret = credentials_from(request)
+          return unless client_id
+
+          Doorkeeper::ClientAuthentication::Credentials.new(client_id, client_secret)
+        end
+
+        # Returns the decoded [client_id, client_secret] pair, or nil when the
+        # request carries no HTTP Basic +client_id+. A header that merely
+        # starts with "Basic " but decodes to an empty/blank client_id (e.g.
+        # an empty payload or a leading ":") is not a usable attempt and does
+        # not match.
+        def self.credentials_from(request)
+          authorization = request.authorization.to_s
+          return unless authorization.downcase.start_with?("basic ")
+
+          value = authorization.split(" ", 2).last
+          client_id, client_secret = Base64.decode64(value.to_s).split(":", 2)
+          return if client_id.blank?
+
+          [client_id, client_secret]
+        end
+        private_class_method :credentials_from
+      end
+    end
+  end
+end

data/lib/doorkeeper/oauth/client_authentication/client_secret_post.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Doorkeeper
+  module OAuth
+    module ClientAuthentication
+      # RFC 6749 §2.3.1 "client_secret_post": client credentials are sent in
+      # the request body. The query string is intentionally ignored so that
+      # credentials must be supplied in the body as the spec requires.
+      class ClientSecretPost
+        def self.matches_request?(request)
+          params = request.request_parameters.with_indifferent_access
+
+          request.post? &&
+            params[:client_id].present? &&
+            params[:client_secret].present?
+        end
+
+        def self.authenticate(request)
+          params = request.request_parameters.with_indifferent_access
+
+          Doorkeeper::ClientAuthentication::Credentials.new(
+            params[:client_id],
+            params[:client_secret],
+          )
+        end
+      end
+    end
+  end
+end

data/lib/doorkeeper/oauth/client_authentication/none.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Doorkeeper
+  module OAuth
+    module ClientAuthentication
+      # RFC 6749 §2.3 "none": a public client that authenticates with only a
+      # client_id and no secret (in the request body, not the query string).
+      class None
+        # Requires the Authorization header to be absent or blank: a request
+        # that carries a non-blank one (Basic, Bearer, or anything else) is
+        # attempting header-based authentication and must not be silently
+        # treated as an unauthenticated public client. This is narrower than
+        # the legacy +from_params+ extractor, which read the body +client_id+
+        # regardless of the Authorization header.
+        def self.matches_request?(request)
+          params = request.request_parameters.with_indifferent_access
+
+          request.post? &&
+            request.authorization.blank? &&
+            params[:client_id].present? &&
+            params[:client_secret].blank?
+        end
+
+        def self.authenticate(request)
+          params = request.request_parameters.with_indifferent_access
+
+          Doorkeeper::ClientAuthentication::Credentials.new(params[:client_id], nil)
+        end
+      end
+    end
+  end
+end

data/lib/doorkeeper/oauth/client_credentials/creator.rb

@@ -45,8 +45,11 @@ module Doorkeeper
         end
 
         def find_active_existing_token_for(client, scopes, attributes)
+          # An empty hash must stay distinct from nil here: nil ignores custom
+          # attributes when matching, while an empty hash only matches tokens
+          # that have no custom attributes set.
           custom_attributes = Doorkeeper.config.access_token_model
-            .extract_custom_attributes(attributes).presence
+            .extract_custom_attributes(attributes)
           Doorkeeper.config.access_token_model.matching_token_for(
             client, nil, scopes, custom_attributes: custom_attributes, include_expired: false,
           )

data/lib/doorkeeper/oauth/code_response.rb

@@ -28,17 +28,22 @@ module Doorkeeper
             token_type: auth.token.token_type,
             expires_in: auth.token.expires_in_seconds,
             state: pre_auth.state,
-          }
+          }.merge(iss_parameter)
         elsif auth.try(:access_grant?)
           {
             code: auth.token.plaintext_token,
             state: pre_auth.state,
-          }
+          }.merge(iss_parameter)
         end
       end
 
       def redirect_uri
         if URIChecker.oob_uri?(pre_auth.redirect_uri)
+          # Out-of-band "redirects" render the code/token on an authorization
+          # server page for the user to copy manually; there is no redirect
+          # back to the client. RFC 9207 scopes the iss parameter to the
+          # authorization response sent to the client, so - like state, which
+          # oob_redirect also omits - iss is intentionally not carried here.
           auth.oob_redirect
         elsif response_on_fragment
           Authorization::URIBuilder.uri_with_fragment(pre_auth.redirect_uri, body)
@@ -46,6 +51,15 @@ module Doorkeeper
           Authorization::URIBuilder.uri_with_query(pre_auth.redirect_uri, body)
         end
       end
+
+      private
+
+      # RFC 9207 Authorization Server Issuer Identification: advertise the
+      # issuer in the authorization response only when an issuer is configured.
+      def iss_parameter
+        issuer = Doorkeeper.config.issuer
+        issuer.present? ? { iss: issuer } : {}
+      end
     end
   end
 end