doorkeeper 5.9.5 → 6.0.0.beta2

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,25 @@ 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
+
+        # RFC 8707: include audience restriction when resource indicators are present
+        if @token.try(:resource).present?
+          aud = @token.resource.split
+          response[:aud] = aud.length == 1 ? aud.first : aud
+        end
+
+        # `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 +193,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 = 5
-    PRE = nil
+    MAJOR = 6
+    MINOR = 0
+    TINY = 0
+    PRE = "beta2"
 
     # Full version number
     STRING = [MAJOR, MINOR, TINY, PRE].compact.join(".")

data/lib/doorkeeper.rb

@@ -7,7 +7,10 @@ require "doorkeeper/engine"
 #
 module Doorkeeper
   autoload :Errors, "doorkeeper/errors"
+  autoload :ClientAuthentication, "doorkeeper/client_authentication"
+  autoload :DocumentCache, "doorkeeper/document_cache"
   autoload :GrantFlow, "doorkeeper/grant_flow"
+  autoload :HttpFetcher, "doorkeeper/http_fetcher"
   autoload :OAuth, "doorkeeper/oauth"
   autoload :Rake, "doorkeeper/rake"
   autoload :Request, "doorkeeper/request"
@@ -52,16 +55,25 @@ 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"
     autoload :RefreshTokenRequest, "doorkeeper/oauth/refresh_token_request"
+    autoload :ResourceIndicatorValidator, "doorkeeper/oauth/resource_indicator_validator"
     autoload :Scopes, "doorkeeper/oauth/scopes"
     autoload :Token, "doorkeeper/oauth/token"
     autoload :TokenIntrospection, "doorkeeper/oauth/token_introspection"
     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"
+      autoload :PrivateKeyJwt, "doorkeeper/oauth/client_authentication/private_key_jwt"
+    end
+
     module Authorization
       autoload :Code, "doorkeeper/oauth/authorization/code"
       autoload :Context, "doorkeeper/oauth/authorization/context"
@@ -69,10 +81,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/grant_reuse_revocation_generator.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Doorkeeper
+  # Generates migration to add the access token reference column to the
+  # access grants table, enabling revocation of previously issued tokens
+  # when an authorization code is reused (RFC 6749 §4.1.2, §10.5).
+  #
+  class GrantReuseRevocationGenerator < ::Rails::Generators::Base
+    include ::Rails::Generators::Migration
+    source_root File.expand_path("templates", __dir__)
+    desc "Support revoking issued tokens on authorization code reuse"
+
+    def self.next_migration_number(path)
+      ActiveRecord::Generators::Base.next_migration_number(path)
+    end
+
+    def grant_reuse_revocation
+      return unless no_access_token_id_column?
+
+      migration_template(
+        "add_access_token_to_access_grants.rb.erb",
+        "db/migrate/add_access_token_to_access_grants.rb",
+        migration_version: migration_version,
+      )
+    end
+
+    private
+
+    def migration_version
+      "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+    end
+
+    def no_access_token_id_column?
+      !ActiveRecord::Base.connection.column_exists?(
+        :oauth_access_grants,
+        :access_token_id,
+      )
+    end
+  end
+end

data/lib/generators/doorkeeper/resource_indicators_generator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Doorkeeper
+  # Generates migration with the `resource` column for access grants and
+  # access tokens, required for RFC 8707 Resource Indicators support.
+  #
+  class ResourceIndicatorsGenerator < ::Rails::Generators::Base
+    include ::Rails::Generators::Migration
+    source_root File.expand_path("templates", __dir__)
+    desc "Add resource indicators support (RFC 8707) to Doorkeeper tables."
+
+    def resource_indicators
+      migration_template(
+        "enable_resource_indicators_migration.rb.erb",
+        "db/migrate/enable_resource_indicators.rb",
+        migration_version: migration_version,
+      )
+    end
+
+    def self.next_migration_number(dirname)
+      ActiveRecord::Generators::Base.next_migration_number(dirname)
+    end
+
+    private
+
+    def migration_version
+      "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+    end
+  end
+end

data/lib/generators/doorkeeper/templates/add_access_token_to_access_grants.rb.erb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+class AddAccessTokenToAccessGrants < ActiveRecord::Migration<%= migration_version %>
+  def change
+    # Indexed: when a code is replayed, the revocation checks whether the
+    # issued token is still referenced by another grant, which filters
+    # oauth_access_grants by access_token_id.
+    add_reference :oauth_access_grants, :access_token, index: true
+  end
+end

data/lib/generators/doorkeeper/templates/enable_resource_indicators_migration.rb.erb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+class EnableResourceIndicators < ActiveRecord::Migration<%= migration_version %>
+  def change
+    add_column :oauth_access_grants, :resource, :text, null: true
+    add_column :oauth_access_tokens, :resource, :text, null: true
+  end
+end

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,13 +286,52 @@ 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
   #
-  # client_credentials :from_basic, :from_params
+  # client_authentication %i[client_secret_basic client_secret_post none]
+  #
+  # The legacy `client_credentials` option is deprecated; `:from_basic` and
+  # `:from_params` are automatically mapped to `:client_secret_basic` and
+  # `:client_secret_post`.
+  #
+  # A `private_key_jwt` method (RFC 7523 / OIDC Core §9) is also registered
+  # but not enabled by default — add it to the list above to accept it. It
+  # requires the `jwt` gem (>= 2.7) in your bundle, and verifies assertions
+  # against the client's published public keys: `jwks` / `jwks_uri`
+  # attributes you define on your Application model (Doorkeeper does not add
+  # these columns itself). Assertions must carry iss = sub =
+  # client_id, an aud of your `issuer` (or the token endpoint URL), a bounded
+  # exp (at most 1 hour ahead), a kid header, and a single-use jti.
+  #
+  # jti replay is tracked in process-local memory by default (bounded at
+  # 10 000 entries, each held at most 1 hour), so an assertion replayed to a
+  # different server process is not caught. To share the tracking across
+  # processes, supply your own store (e.g. backed by Redis):
+  #
+  # private_key_jwt_replay_guard MyRedisReplayGuard.new
+  #
+  # JWK Sets fetched from a `jwks_uri` are cached in process-local memory
+  # for 60 seconds; to change the TTL or share the cache across processes:
+  #
+  # private_key_jwt_jwks_cache Doorkeeper::DocumentCache.new(ttl: 300)
+  #
+  # The accepted audiences are built from your `issuer` or from Rails'
+  # `default_url_options`; set at least one of them, otherwise Doorkeeper has
+  # nothing but the request's Host header to identify itself with and the
+  # audience check cannot tell your server apart from another one.
+  #
+  # A client's `jwks_uri` is fetched with a hardened HTTP client (HTTPS
+  # only, no redirects, hosts resolving to RFC 6890 special-use addresses
+  # refused), so a jwks_uri on a private network or on localhost is refused
+  # even though you configured it yourself; inline `jwks` has no such
+  # restriction.
+  #
+  # client_authentication %i[client_secret_basic client_secret_post none private_key_jwt]
 
   # Change the way access token is authenticated from the request object.
   # By default it retrieves first from the `HTTP_AUTHORIZATION` header, then
@@ -319,6 +367,9 @@ Doorkeeper.configure do
   # types, but you **need** to manually drop `NOT NULL` constraint from `redirect_uri`
   # column for `oauth_applications` database table.
   #
+  # You almost certainly do not want to change this. There are very, very few cases
+  # where you want to change this configuration value.
+  #
   # You can completely disable this feature with:
   #
   # allow_blank_redirect_uri false
@@ -377,6 +428,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
@@ -541,4 +595,75 @@ 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",
+  # )
+
+  # Resource Indicators for OAuth 2.0 (RFC 8707)
+  #
+  # When configured with a callable, enables RFC 8707 support. The callable
+  # receives an array of resource indicator URIs and the OAuth client, and must
+  # return true if the resources are acceptable, or false to reject with
+  # `invalid_target`.
+  #
+  # Clients may then include one or more `resource` parameters in authorization
+  # and token requests to signal which protected resource(s) they intend to
+  # access. The authorization server will:
+  #   - Validate resource URIs (must be absolute, no fragment)
+  #   - Store resource indicators on grants and tokens
+  #   - Enforce subset restrictions on token/refresh requests
+  #   - Include `aud` in token introspection responses
+  #
+  # NOTE: RFC 8707 specifies repeated query parameters (?resource=…&resource=…)
+  # for multiple values, but Rack collapses repeated keys to the last value.
+  # Clients must use the Rails bracket syntax (resource[]=…&resource[]=…) to
+  # send multiple resource indicators. A single resource=… works as-is.
+  #
+  # To use this feature, first run `rails generate doorkeeper:resource_indicators`
+  # to add the required `resource` column to the access grants and tokens tables.
+  #
+  # resource_indicator_validator ->(resource_indicators, client) {
+  #   allowed = %w[https://api.example.com/ https://calendar.example.com/]
+  #   resource_indicators.all? { |r| allowed.include?(r) }
+  # }
 end

data/lib/generators/doorkeeper/templates/migration.rb.erb

@@ -28,6 +28,19 @@ class CreateDoorkeeperTables < ActiveRecord::Migration<%= migration_version %>
       t.string   :scopes,            null: false, default: ''
       t.datetime :created_at,        null: false
       t.datetime :revoked_at
+
+      # Authorization codes are single-use (RFC 6749 §4.1.2). Doorkeeper
+      # records the access token issued when the code is exchanged, so that
+      # a second exchange attempt revokes the previously issued tokens as
+      # recommended by RFC 6749 §10.5.
+      #
+      # Comment out this line if you don't want a reused authorization code
+      # to revoke the tokens already issued for it.
+      #
+      # Indexed: when a code is replayed, the revocation checks whether the
+      # issued token is still referenced by another grant, which filters
+      # this table by access_token_id.
+      t.references :access_token,    index: true
     end
 
     add_index :oauth_access_grants, :token, unique: true