doorkeeper 6.0.0.beta2 → 6.0.0.rc2

data/lib/doorkeeper/rails/helpers.rb

@@ -13,6 +13,8 @@ module Doorkeeper
 
       def doorkeeper_forbidden_render_options(**); end
 
+      def doorkeeper_bad_request_render_options(**); end
+
       def valid_doorkeeper_token?
         doorkeeper_token&.acceptable?(@_doorkeeper_scopes)
       end
@@ -42,15 +44,28 @@ module Doorkeeper
       end
 
       def doorkeeper_error
-        if doorkeeper_invalid_token_response?
+        if @_doorkeeper_multiple_token_methods_error
+          OAuth::InvalidRequestResponse.new(
+            reason: @_doorkeeper_multiple_token_methods_error.reason,
+          )
+        elsif doorkeeper_invalid_token_response?
           OAuth::InvalidTokenResponse.from_access_token(doorkeeper_token)
         else
           OAuth::ForbiddenTokenResponse.from_scopes(@_doorkeeper_scopes)
         end
       end
 
+      # Keyed on the response doorkeeper_error chose rather than on the state
+      # that chose it, so a response this method does not know about cannot be
+      # rendered through a hook meant for a different one: a request refused
+      # for transmitting the token by more than one method leaves
+      # doorkeeper_token nil, and answering it through the hook a host wrote
+      # for its 401s would give an "unauthorized" body a 400 status.
       def doorkeeper_render_options(error)
-        if doorkeeper_invalid_token_response?
+        case error.status
+        when :bad_request
+          doorkeeper_bad_request_render_options(error: error)
+        when :unauthorized
           doorkeeper_unauthorized_render_options(error: error)
         else
           doorkeeper_forbidden_render_options(error: error)
@@ -69,6 +84,11 @@ module Doorkeeper
         !doorkeeper_token || !doorkeeper_token.accessible?
       end
 
+      # Answers nil (not a raise) when the request transmits an access token
+      # by more than one method, so host code that consults doorkeeper_token
+      # directly keeps its token-or-nil contract; doorkeeper_authorize! then
+      # renders the invalid_request (400) response RFC 6750 §3.1 prescribes
+      # instead of invalid_token, via doorkeeper_error above.
       def doorkeeper_token
         return @doorkeeper_token if defined?(@doorkeeper_token)
 
@@ -76,6 +96,9 @@ module Doorkeeper
           request,
           *Doorkeeper.config.access_token_methods,
         )
+      rescue Errors::MultipleAccessTokenMethods => e
+        @_doorkeeper_multiple_token_methods_error = e
+        @doorkeeper_token = nil
       end
     end
   end

data/lib/doorkeeper/request.rb

@@ -25,18 +25,30 @@ module Doorkeeper
         end
       end
 
+      # Resolves the strategy that answers the given response_type at the
+      # authorization endpoint.
+      #
+      # A response_type no registered authorization flow handles is refused
+      # rather than turned into a class name: `constantize` would otherwise
+      # resolve any constant under Doorkeeper::Request, token endpoint
+      # strategies (`password`, `client_credentials`, `refresh_token`,
+      # `authorization_code`) included, none of which can answer an
+      # authorization request.
       def authorization_strategy(response_type)
+        response_type = response_type.to_s
+
         grant_flow = authorization_flows.detect do |flow|
           flow.matches_response_type?(response_type)
         end
 
-        if grant_flow
-          grant_flow.response_type_strategy
-        else
-          # [NOTE]: this will be removed in a newer versions of Doorkeeper.
-          # For retro-compatibility only
-          build_fallback_strategy_class(response_type)
-        end
+        raise Errors::InvalidTokenStrategy unless grant_flow
+
+        # [NOTE]: this will be removed in a newer versions of Doorkeeper.
+        # For retro-compatibility only: flows declared through the deprecated
+        # Config#calculate_authorization_response_types hook are built as
+        # GrantFlow::FallbackFlow and carry no strategy, so the class is looked
+        # up by name — but only for a response type the server does declare.
+        grant_flow.response_type_strategy || build_fallback_strategy_class(response_type)
       end
 
       def token_strategy(grant_type)

data/lib/doorkeeper/version.rb

@@ -6,7 +6,7 @@ module Doorkeeper
     MAJOR = 6
     MINOR = 0
     TINY = 0
-    PRE = "beta2"
+    PRE = "rc2"
 
     # Full version number
     STRING = [MAJOR, MINOR, TINY, PRE].compact.join(".")

data/lib/doorkeeper.rb

@@ -206,8 +206,19 @@ module Doorkeeper
       @orm_adapter.initialize_application_owner!
     end
 
+    # Answers the access token authorizing the request, or nil when there is
+    # none. A request that transmits a token by more than one method (RFC 6750
+    # §2) has no single authorizing token, so it answers nil here rather than
+    # propagating Errors::MultipleAccessTokenMethods: this is the entry point
+    # host applications call, and its token-or-nil contract is what they build
+    # on. Callers that need to tell a refused request apart from one that
+    # carried no token — to describe it as the multi-method refusal it is —
+    # call OAuth::Token.authenticate and handle the error, as the Rails and
+    # Grape helpers do.
     def authenticate(request, methods = Doorkeeper.config.access_token_methods)
       OAuth::Token.authenticate(request, *methods)
+    rescue Errors::MultipleAccessTokenMethods
+      nil
     end
 
     def gem_version

data/lib/generators/doorkeeper/refresh_token_scopes_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 refresh token scopes column to the
+  # database for Doorkeeper tables, so that a refresh token keeps the scope
+  # originally granted by the resource owner (RFC 6749 §6) when the access
+  # tokens issued with it are narrowed.
+  #
+  class RefreshTokenScopesGenerator < ::Rails::Generators::Base
+    include ::Rails::Generators::Migration
+    source_root File.expand_path("templates", __dir__)
+    desc "Keep the granted scope on refresh tokens (RFC 6749 §6)"
+
+    def self.next_migration_number(path)
+      ActiveRecord::Generators::Base.next_migration_number(path)
+    end
+
+    def refresh_token_scopes
+      return unless no_refresh_token_scopes_column?
+
+      migration_template(
+        "add_refresh_token_scopes_to_access_tokens.rb.erb",
+        "db/migrate/add_refresh_token_scopes_to_access_tokens.rb",
+      )
+    end
+
+    private
+
+    def migration_version
+      "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+    end
+
+    def no_refresh_token_scopes_column?
+      !ActiveRecord::Base.connection.column_exists?(
+        :oauth_access_tokens,
+        :refresh_token_scopes,
+      )
+    end
+  end
+end

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

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+class AddRefreshTokenScopesToAccessTokens < ActiveRecord::Migration<%= migration_version %>
+  def change
+    # Existing rows are left NULL: their refresh tokens keep behaving as
+    # before (validated against the access token's own scope) until they
+    # are rotated, at which point the new row records the granted scope.
+    add_column :oauth_access_tokens, :refresh_token_scopes, :string
+  end
+end

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

@@ -119,9 +119,13 @@ Doorkeeper.configure do
   # non-expiring access token (which is not recommended) then you need to return
   # Float::INFINITY from this block.
   #
+  # The block is also called for the refresh_token grant (`context.grant_type` is
+  # Doorkeeper::OAuth::REFRESH_TOKEN). Returning `nil` there keeps the TTL of the token
+  # being refreshed rather than falling back to +access_token_expires_in+.
+  #
   # `context` has the following properties available:
   #
-  #   * `client` - the OAuth client application (see Doorkeeper::OAuth::Client)
+  #   * `client` - the client application record (Doorkeeper::Application, or nil when client authentication was skipped)
   #   * `grant_type` - the grant type of the request (see Doorkeeper::OAuth)
   #   * `scopes` - the requested scopes (see Doorkeeper::OAuth::Scopes)
   #   * `resource_owner` - authorized resource owner instance (if present)
@@ -130,6 +134,20 @@ Doorkeeper.configure do
   #   context.client.additional_settings.implicit_oauth_expiration
   # end
 
+  # Cap the lifetime of access tokens issued to public (non-confidential) clients,
+  # for every grant including refresh_token, whatever +access_token_expires_in+ or
+  # +custom_access_token_expires_in+ would have given them (a never-expiring token
+  # is capped too). OAuth 2.1 (Section 2.4) requires an authorization server to limit
+  # the exposure of tokens issued to unauthenticated clients. A request without a
+  # client (e.g. with +skip_client_authentication_for_password_grant+) is treated as a
+  # public client. Confidential clients are not affected. Disabled (nil) by default.
+  #
+  # With +reuse_access_token+ enabled, an existing token that would outlive the cap
+  # (issued before the cap was configured, or while the client was confidential) is
+  # not reused for a public client; a new, capped token is issued instead.
+  #
+  # public_client_access_token_expires_in 1.hour
+
   # Use a custom class for generating the access token.
   # See https://doorkeeper.gitbook.io/guides/configuration/other-configurations#custom-access-token-generator
   #
@@ -202,12 +220,26 @@ Doorkeeper.configure do
   #
   # force_pkce
 
+  # Validate the authorization request's client_id and redirect_uri before
+  # authenticating the resource owner, so users are not sent through login for
+  # a request that can only fail (RFC 6749 Section 4.1.2.1 asks for the
+  # resource owner to be informed of an invalid client_id, Section 3.1.2.4 of
+  # an invalid redirect URI). Disabled by default: enabling it changes when
+  # your `resource_owner_authenticator` block runs, and lets an unauthenticated
+  # party learn whether a client_id is registered (client identifiers are not
+  # confidential per RFC 6749 Section 2.2). To refuse clients on your own terms
+  # as well, override Doorkeeper::AuthorizationsController#validate_client.
+  #
+  # validate_client_before_resource_owner_authentication
+
   # Hash access and refresh tokens before persisting them.
   # This will disable the possibility to use +reuse_access_token+
   # since plain values can no longer be retrieved.
   #
   # Note: If you are already a user of doorkeeper and have existing tokens
   # in your installation, they will be invalid without adding 'fallback: :plain'.
+  # Read the note on the fallback option below before you do: it is a setting
+  # for the migration period, not a permanent one.
   #
   # hash_token_secrets
   # By default, token secrets will be hashed using the
@@ -234,23 +266,37 @@ Doorkeeper.configure do
   # hash_application_secrets using: '::Doorkeeper::SecretStoring::BCrypt'
 
   # When the above option is enabled, and a hashed token or secret is not found,
-  # you can allow to fall back to another strategy. For users upgrading
-  # doorkeeper and wishing to enable hashing, you will probably want to enable
-  # the fallback to plain tokens.
-  #
-  # This will ensure that old access tokens and secrets
-  # will remain valid even if the hashing above is enabled.
-  #
-  # This can be done by adding 'fallback: plain', e.g. :
+  # you can allow to fall back to another strategy, so that values written
+  # before hashing was enabled remain valid. For users upgrading doorkeeper and
+  # wishing to enable hashing, that is the fallback to plain tokens, added with
+  # 'fallback: :plain', e.g. :
   #
   # hash_application_secrets using: '::Doorkeeper::SecretStoring::BCrypt', fallback: :plain
+  #
+  # [IMPORTANT] The fallback is meant for the migration period only, and should
+  # be removed once every row has been migrated to the hashed format. A value
+  # found through the fallback is rewritten in the new format as it is used, so
+  # rows migrate themselves as their tokens and secrets are presented; rows that
+  # are never presented again keep their old format until you migrate or clean
+  # them up yourself. Doorkeeper warns at boot for as long as a fallback is
+  # configured.
+  #
+  # While 'fallback: :plain' is configured, a stored value is itself a valid
+  # credential: the fallback looks the column up by the value exactly as it was
+  # given, so whatever the column holds authenticates. What the hashing above is
+  # meant to protect you from - a database dump, a read-only SQL injection, a
+  # query written to a log - still yields usable tokens and secrets. Protect the
+  # contents of those columns as carefully as plaintext credentials for as long
+  # as it is configured, and remove it as soon as the migration is done. A
+  # fallback to another hashing strategy still transforms what it stores, so
+  # only the reminder above applies to it.
 
   # Issue access tokens with refresh token (disabled by default), you may also
   # pass a block which accepts `context` to customize when to give a refresh
   # token or not. Similar to +custom_access_token_expires_in+, `context` has
   # the following properties:
   #
-  # `client` - the OAuth client application (see Doorkeeper::OAuth::Client)
+  # `client` - the client application record (Doorkeeper::Application, or nil when client authentication was skipped)
   # `grant_type` - the grant type of the request (see Doorkeeper::OAuth)
   # `scopes` - the requested scopes (see Doorkeeper::OAuth::Scopes)
   #
@@ -321,9 +367,11 @@ Doorkeeper.configure do
   # 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.
+  # `default_url_options`, never from the request's Host header - the audience
+  # is what tells your server apart from another one, so it cannot come from a
+  # value the caller controls. Set at least one of them: with neither
+  # configured no audience is acceptable and every assertion is refused
+  # (Doorkeeper says so in the log at boot).
   #
   # A client's `jwks_uri` is fetched with a hardened HTTP client (HTTPS
   # only, no redirects, hosts resolving to RFC 6890 special-use addresses
@@ -339,6 +387,23 @@ Doorkeeper.configure do
   # Check out https://github.com/doorkeeper-gem/doorkeeper/wiki/Changing-how-clients-are-authenticated
   # for more information on customization
   #
+  # RFC 6750 §2 defines three transmission methods and forbids a client from
+  # using more than one of them per request, so a request presenting a token
+  # through two of the built-in methods is refused with `invalid_request`
+  # (400). What §2 forbids is the second method, not a disagreement between
+  # the two, so repeating the same token across methods is refused as well.
+  # The form-encoded body (§2.2) and the URI query (§2.3) count as two methods
+  # even though Rails and Rack merge them into a single `params` hash, so
+  # `access_token` carried by both is refused too.
+  #
+  # A custom callable extractor sits outside that check and keeps the
+  # historical first-wins selection — the same boundary client authentication
+  # draws around the legacy `client_credentials` callable extractors. If you
+  # configure one, a request presenting one token through it and a different
+  # token through a built-in method is served under whichever comes first in
+  # this list, and the other is discarded, so make sure the layers in front of
+  # Doorkeeper agree with this list about which one authorizes the request.
+  #
   # access_token_methods :from_bearer_authorization, :from_access_token_param, :from_bearer_param
 
   # Forces the usage of the HTTPS protocol in non-native redirect uris (enabled
@@ -356,10 +421,13 @@ Doorkeeper.configure do
   # Specify what redirect URI's you want to block during Application creation.
   # Any redirect URI is allowed by default.
   #
-  # You can use this option in order to forbid URI's with 'javascript' scheme
+  # Redirect URIs with a script scheme (`javascript`, `vbscript`, `data`) are
+  # always rejected, regardless of this option.
+  #
+  # You can use this option in order to forbid URI's of a particular host
   # for example.
   #
-  # forbid_redirect_uri { |uri| uri.scheme.to_s.downcase == 'javascript' }
+  # forbid_redirect_uri { |uri| uri.host == 'example.com' }
 
   # Allows to set blank redirect URIs for Applications in case Doorkeeper configured
   # to use URI-less OAuth grant flows like Client Credentials or Resource Owner
@@ -391,6 +459,17 @@ Doorkeeper.configure do
   #   Doorkeeper::Errors::TokenForbidden, Doorkeeper::Errors::TokenExpired,
   #   Doorkeeper::Errors::TokenRevoked, Doorkeeper::Errors::TokenUnknown
   #
+  # One more can reach your rescue: a request that transmits an access token by
+  # more than one method (RFC 6750 §2 forbids it) is refused as invalid_request
+  # rather than invalid_token, and raises
+  #
+  #   Doorkeeper::Errors::InvalidRequest
+  #
+  # That one is a sibling of Doorkeeper::Errors::InvalidToken, not a subclass,
+  # so an existing `rescue Doorkeeper::Errors::InvalidToken` does not cover it.
+  # Rescue it explicitly, or rescue their common parent
+  # Doorkeeper::Errors::BaseResponseError, to handle both.
+  #
   # handle_auth_errors :raise
   #
   # If you want to redirect back to the client application in accordance with

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

@@ -85,6 +85,15 @@ class CreateDoorkeeperTables < ActiveRecord::Migration<%= migration_version %>
       # Comment out this line if you want refresh tokens to be instantly
       # revoked after use.
       t.string   :previous_refresh_token, null: false, default: ""
+
+      # A refresh token keeps the scope originally granted by the resource
+      # owner, so a client that narrowed an access token on one refresh can
+      # request the granted scope again on the next one.
+      # @see https://datatracker.ietf.org/doc/html/rfc6749#section-6
+      #
+      # Comment out this line if you want a narrowed refresh to permanently
+      # narrow the refresh token as well.
+      t.string   :refresh_token_scopes
     end
 
     add_index :oauth_access_tokens, :token, unique: true

metadata

@@ -1,17 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: doorkeeper
 version: !ruby/object:Gem::Version
-  version: 6.0.0.beta2
+  version: 6.0.0.rc2
 platform: ruby
 authors:
 - Felipe Elias Philipp
 - Tute Costa
 - Jon Moss
 - Nikita Bulai
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-08-10 00:00:00.000000000 Z
+date: 2026-09-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -56,19 +55,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: coveralls_reborn
+  name: simplecov
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.1'
 - !ruby/object:Gem::Dependency
   name: database_cleaner
   requirement: !ruby/object:Gem::Requirement
@@ -317,6 +316,7 @@ files:
 - lib/doorkeeper/orm/active_record/mixins/access_grant.rb
 - lib/doorkeeper/orm/active_record/mixins/access_token.rb
 - lib/doorkeeper/orm/active_record/mixins/application.rb
+- lib/doorkeeper/orm/active_record/mixins/secret_storable.rb
 - lib/doorkeeper/orm/active_record/redirect_uri_validator.rb
 - lib/doorkeeper/orm/active_record/stale_records_cleaner.rb
 - lib/doorkeeper/rails/helpers.rb
@@ -354,6 +354,7 @@ files:
 - lib/generators/doorkeeper/migration_generator.rb
 - lib/generators/doorkeeper/pkce_generator.rb
 - lib/generators/doorkeeper/previous_refresh_token_generator.rb
+- lib/generators/doorkeeper/refresh_token_scopes_generator.rb
 - lib/generators/doorkeeper/remove_applications_secret_not_null_constraint_generator.rb
 - lib/generators/doorkeeper/resource_indicators_generator.rb
 - lib/generators/doorkeeper/templates/README
@@ -361,6 +362,7 @@ files:
 - lib/generators/doorkeeper/templates/add_confidential_to_applications.rb.erb
 - lib/generators/doorkeeper/templates/add_owner_to_application_migration.rb.erb
 - lib/generators/doorkeeper/templates/add_previous_refresh_token_to_access_tokens.rb.erb
+- lib/generators/doorkeeper/templates/add_refresh_token_scopes_to_access_tokens.rb.erb
 - lib/generators/doorkeeper/templates/enable_pkce_migration.rb.erb
 - lib/generators/doorkeeper/templates/enable_polymorphic_resource_owner_migration.rb.erb
 - lib/generators/doorkeeper/templates/enable_resource_indicators_migration.rb.erb
@@ -379,7 +381,6 @@ metadata:
   bug_tracker_uri: https://github.com/doorkeeper-gem/doorkeeper/issues
   documentation_uri: https://doorkeeper.gitbook.io/guides/
   funding_uri: https://opencollective.com/doorkeeper-gem
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -387,15 +388,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.7'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
-signing_key: 
+rubygems_version: 3.6.2
 specification_version: 4
 summary: OAuth 2 provider for Rails and Grape
 test_files: []