doorkeeper 5.9.5 → 6.0.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d3e4ee342094b7729f29bb64d9045cfd9736d99388c5bb15d68568c6d59a8a54
-  data.tar.gz: e1549e74f00d26b85ed9afedbfaba17adce5a4e8a62c5ee01a8c4ff70c71bbcf
+  metadata.gz: b401160f58e48398c2e25631a27e5dabc423480e08f34a64c91c25107ffcab53
+  data.tar.gz: 6c6dc01f00118c8525fe7ec329cab28cdaad05b5c5b06402cbb7f59ceb565e1a
 SHA512:
-  metadata.gz: d91e3f678a7a3d53e94c607b5b88d5a6e695e166a52fd9f5527c8988bd717c60debc292798c159da7356966baa4d26ad22d56a9b922582040e758c37ef26ea96
-  data.tar.gz: e335f698b2a3fe29b139e826fafada70b94fd239a0c2e0f2be762075c27bb73c8dab4c93a9581089214b07f9016af893cd0c70daf0fdc2db9c8b72f7ae848850
+  metadata.gz: c394405b84f4b64de4db90e9ab8ea932f2899a2f3898d78df4d06add7765c6f5ae7a457e8e3c19ed69bf7592ffec8c3d1ab5c241f1a521e0347780ead79c233d
+  data.tar.gz: 2275e90f19537ae4cda5e60ad1571ec29e0468e53b84d91bb165dea68960c2bf60d358194373ebd183b688d9043d86ef3a0e3685c0c38c7d4db8822ee7a98534

data/CHANGELOG.md

@@ -7,14 +7,80 @@ User-visible changes worth mentioning.
 
 ## main
 
+- [#PR ID] Description of the change.
+
+## 6.0.0.beta2
+
+**Please make sure** you read the [Upgrade guides](https://github.com/doorkeeper-gem/doorkeeper/wiki/Migration-from-old-versions)
+and changelog below before the update since this version includes breaking changes.
+
+- [#1865] Revoke the token issued for an authorization code when the code is exchanged more than once, per RFC 6749 §4.1.2 / §10.5. Active when the `oauth_access_grants.access_token_id` column exists: new installs get it from the generated migration, existing apps can add it with `rails generate doorkeeper:grant_reuse_revocation`. Closes [#1713].
+- [#1871] **[BREAKING]** `redirect_uri` is now compared to the registered redirect URIs with the simple string comparison required by RFC 6749 §3.1.2.3 (the RFC 8252 §7.3 loopback port exception is kept). Clients relying on the previous lenient matching must send the exact registered URI, closes [#1718].
+- [#1874] Fix `force_pkce` requiring a `code_challenge` from response types that never issue an authorization code (e.g. `token`, or an OIDC extension's `id_token` / `id_token token`). PKCE (RFC 7636) protects the authorization code exchange, so for code-less response types there is no token-endpoint step where a `code_verifier` could ever be checked — such requests were rejected over a parameter that cannot be validated. `force_pkce` now only enforces the challenge for response types that issue a code (`code` and code-carrying hybrid types such as `code id_token`).
+- [#1876] Fix: reject a non-string `scope` parameter (e.g. `scope[a]=b`, which Rack parses into a Hash) with `invalid_request` (RFC 6749 §3.3) instead of an unhandled 500. `Scopes.from_string` now raises `Errors::InvalidScopeParameter` for a non-string argument — turned into `invalid_request` by the token endpoint's `rescue_from`, so every grant type is covered — and the authorization endpoint rejects it up front in pre-authorization validation. The crash was reachable unauthenticated, before client authentication.
+- [#1877] Fix: let the `none` client authentication strategy match a request whose `Authorization` header carries a Bearer token. A bearer credential authorizes access to the endpoint itself (e.g. a bearer-protected introspection endpoint per RFC 7662 §2.1, or a revocation request) rather than authenticating the client, so it must not suppress the public-client `none` strategy when the client identifies itself with a body `client_id`. Any other non-blank `Authorization` value — Basic, or a `Bearer` with no token — is still treated as header-based client authentication and continues to bypass `none`. The 6.0.0.beta1 workaround of dropping the `Authorization` header from such a request is no longer needed.
+- [#1878] Fix: the loopback redirect URI exception (RFC 8252 §7.3) now varies by port only, not by userinfo. The port was cleared with `URI#port=`, which on Ruby >= 4.0 also drops the userinfo, so `http://attacker@127.0.0.1/cb` matched a registered `http://127.0.0.1/cb`. The match is now made component-by-component. The destination host is always the loopback interface, so this was not a cross-origin open redirect, and non-loopback hosts were never affected.
+- [#1879] Fix: with `reuse_access_token` enabled, replaying an authorization code no longer revokes an access token that another grant still shares. The single-use revocation added in [#1865] followed the grant's `access_token_id`, which a reused token shares across grants, so a replay could collaterally revoke a token another valid session still held. The revocation now skips a token referenced by another grant and only reaches one unique to the replayed code; a token unique to the code is still revoked as before.
+- [#1881] Fix: `Doorkeeper::ApplicationsController` no longer 500s on `create`/`update`/`destroy` in `api_only` mode, where `ActionController::API` provides no `flash`. Confining `flash` to the HTML path is not sufficient on its own, because a client that does not name JSON explicitly still negotiates its way into that path — an absent `Accept` header and a browser-like list such as `application/json, text/plain, */*` both resolve to `text/html`, and a bare `*/*` resolves to the first registered format — so `api_only` mode now pins the response format to JSON.
+- [#1883] Internal: merge `CHANGELOG.md` with git's `union` driver, so two pull requests that each add an entry no longer conflict on the line above "Please add here".
+- [#1884] Fix: `/oauth/introspect` and `/oauth/revoke` extend the token lookup across both token types when the lookup by `token_type_hint` finds nothing (RFC 7662 §2.1 / RFC 7009 §2.1), so a wrong hint no longer hides a token the server knows about ([#1882])
+- [#1885] Index `oauth_access_grants.access_token_id` in the migration templates: since [#1879] the code-replay revocation filters access grants by that column, the "never used to filter queries" premise behind `index: false` no longer holds.
+- [#1886] Add support for Resource Indicators for OAuth 2.0 (RFC 8707). Clients can include a `resource` parameter in authorization and token requests to indicate the target protected resource(s). The authorization server validates resource URIs, enforces audience restriction on tokens, and includes `aud` in introspection responses. Enable by configuring `resource_indicator_validator` with a callable. Requires new `resource` columns on access grants and tokens — run `rails generate doorkeeper:resource_indicators` to add the migration.
+- [#1887] [test] Pin that a requested non-default scope reaches the authorization grant and the exchanged token, and that the authorization strategy shares the controller's pre-authorization — the mismatch reported in [#1576] does not reproduce. Test-only change, closes [#1576].
+- [#1888] Document custom grant flow registration (`Doorkeeper::GrantFlow.register`) in the README with a SAML 2.0 bearer assertion (RFC 7522) walkthrough, and pin URN-shaped custom grant types with an end-to-end request spec. Docs/test-only change, closes [#764].
+- [#1890] [test] Pin that the authorization endpoint answers `invalid_redirect_uri` for a client registered without a redirect URI (`allow_blank_redirect_uri`), whether or not the request supplies one — the behavior required by RFC 6749 §3.1.2.3. Test-only change, closes [#1682].
+- [#1898] Fix: with `reuse_access_token` enabled, the `client_credentials` grant no longer reuses a token whose `resource` differs from the one requested (RFC 8707), so the audience restriction the client asked for is always applied. Follow-up to [#1886].
+- [#1899] Document the client authentication methods registry (`Doorkeeper::ClientAuthentication.register`) in the README with a walkthrough for registering a custom method, and pin it with an end-to-end request spec. Docs/test-only change, closes [#1894].
+- [#1891] Fix: an authorization request carrying a `redirect_uri` for a client registered without one (`redirect_uri` is `nil` under `allow_blank_redirect_uri`) now answers `invalid_redirect_uri` instead of crashing with an unhandled 500.
+- [#1896] Add an opt-in `private_key_jwt` client authentication method (RFC 7523 / OIDC Core §9, requires the `jwt` gem >= 2.7) that verifies assertions against the client's published public keys — `jwks` / `jwks_uri` attributes you define on your Application model, the latter fetched with an SSRF-hardened HTTP client. The jti replay guard and the fetched-JWKS cache are process-local by default and can be replaced with shared stores via the `private_key_jwt_replay_guard` / `private_key_jwt_jwks_cache` config options. Part of [#1875].
+- [#1901] [test] Pin the answered behaviors behind [#984], [#1554], [#1600], [#1663], [#1759] and [#1787] with regression specs — the built-in client authentication methods, the unmodified echo of long `state` values, DB persistence with custom token generators, refresh token rotation/expiry semantics and the introspection asymmetry. Test-only change, closes those issues along with [#1291], [#1756] and [#1764].
+- [#1902] Fix: requests that omit `scope` now compute the same default scopes at the authorization and token endpoints (`Scopes#common`, symmetric). With dynamic scopes enabled, a scope pattern in either `default_scopes` or the application's scopes grants the matching concrete scope at both endpoints, closes [#1889].
+- [#1903] Fix: `revoke_previous_client_credentials_token` no longer revokes a client's live access token issued for a different `resource` ([#1886]), so a client can keep one audience-restricted token per resource server.
+- [#1905] [test] Cover `private_key_jwt` client authentication on the `client_credentials` grant, the one flow where an assertion is the client's only credential end to end. Test-only change.
 - Please add here
 
+## 6.0.0.beta1
+
+**Please make sure** you read the [Upgrade guides](https://github.com/doorkeeper-gem/doorkeeper/wiki/Migration-from-old-versions)
+and changelog below before the update since this version includes breaking changes.
+
+- [#1816] Fix: redirect `unauthorized_client` errors per RFC 6749 Section 4.1.2.1; validate redirect_uri before `client_supports_grant_flow` to prevent open redirect
+- [#1867] Fix: use `access_denied` instead of `invalid_client` for `resource_owner_authorize_for_client` validation per RFC 6749 Section 4.1.2.1. `invalid_client` is a token endpoint error (Section 5.2), not an authorization endpoint error.
+- [#1838] Add OAuth 2.0 Authorization Server Metadata endpoint (RFC 8414) served at `/.well-known/oauth-authorization-server`. The response is built from your Doorkeeper configuration and advertises the authorization, token, revocation and (when token introspection is enabled) introspection endpoints, supported scopes, response/grant types and PKCE code challenge methods. Two new config options are available: `issuer` (defaults to the request base URL) and `custom_metadata` (a Hash merged into the response, e.g. to advertise an OIDC `userinfo_endpoint`). The controller/response use the RFC 8414 "Metadata" naming so they don't collide with a future OpenID Connect Discovery (`.well-known/openid-configuration`) implementation. Endpoints disabled through `skip_controllers` are omitted from the response instead of raising a route-generation error.
+- [#1839] Send client credentials in the request body (not the query string) in the token endpoint specs, per RFC 6749 §2.3.1. Test-only change: the `*_endpoint_url` helpers now return a path plus a matching `*_endpoint_params` builder so flow specs post credentials through the body.
+- [#1840] Introduce a pluggable client authentication registry (RFC 6749 §2.3).
+  - New `client_authentication` config option declares which methods are accepted and in which order. Built-in strategies: `client_secret_basic`, `client_secret_post` and `none`.
+  - Custom strategies can be registered with `Doorkeeper::ClientAuthentication.register`.
+  - **[BREAKING]** Client credentials are no longer read from the query string — send them in the request body or via HTTP Basic. This applies to every endpoint that authenticates clients: token, revocation and introspection.
+  - **[BREAKING]** The `none` strategy rejects requests that carry a non-blank `Authorization` header. A common casualty is a public client POSTing to `/oauth/revoke` with a body `client_id` while still sending its `Authorization: Bearer <token>` header — drop the header from that request.
+  - **[BREAKING]** The `Doorkeeper::OAuth::Client::Credentials` class methods `.from_request`, `.from_basic` and `.from_params` are removed — extensions extracting credentials from a request should register a client authentication method instead.
+  - **Deprecated**: the `client_credentials` option — use `client_authentication` instead.
+  - **Deprecated**: the `Doorkeeper::OAuth::Client::Credentials` constant itself — it remains as an alias of `Doorkeeper::ClientAuthentication::Credentials` (the plain uid/secret struct).
+  - See the [Upgrade Guide](https://github.com/doorkeeper-gem/doorkeeper/wiki/Migration-from-old-versions) for detailed breaking changes, deprecations and migration steps.
+- [#1841] Reject requests that use more than one client authentication method (RFC 6749 §2.3: "The client MUST NOT use more than one authentication method in each request") with an `invalid_request` error instead of silently using the first match. The request payload is validated against every registered method before the configured one is selected, so a client sending e.g. both Basic and body credentials is rejected even when only one of those methods is enabled. This applies to every endpoint that authenticates clients — token, revocation and introspection. Only real authentication mechanisms count: a bare `client_id` (the `none` method) is not a mechanism of its own, and deprecated `client_credentials` callable extractors never count towards the limit (they keep the historical first-extractor-wins selection).
+- [#1842] **[BREAKING]** `force_pkce` now requires PKCE for all clients, including confidential ones, in line with the OAuth 2.0 Security BCP (RFC 9700) and OAuth 2.1. Previously confidential clients were exempt. If you enable `force_pkce` and have confidential clients that do not yet send a `code_challenge`/`code_verifier`, their authorization requests will start to be rejected.
+- [#1845] Fix `NameError` when the config option DSL (`Doorkeeper::Config::Option`) is extended into a class that does not define `self.builder_class`. The guard raised `Doorkeeper::MissingConfigurationBuilderClass`, a constant that was never defined, so callers saw `uninitialized constant` instead of the intended message. The error is now defined as `Doorkeeper::Errors::MissingConfigurationBuilderClass` (a `DoorkeeperError`) and referenced correctly.
+- [#1846] Document and pin with regression specs that a `scope` parameter sent to the token endpoint is ignored for the `authorization_code` grant (RFC 6749 §4.1.3 does not define one): the access token always inherits the scopes of the authorization grant, and the response reports the actual granted `scope`. No behavior change.
+- [#1847] Fix `Doorkeeper.config.enabled_grant_flows` (and `calculate_grant_flows`) not listing the `refresh_token` grant flow when `use_refresh_token` is configured, so consumers (e.g. RFC 8414 metadata) no longer need to append it manually — the built-in metadata endpoint now relies on this too. The flow is no longer duplicated in `token_grant_flows` when `refresh_token` is also listed in `grant_flows` explicitly, a configuration-time warning is logged when `grant_flows` enables `refresh_token` without `use_refresh_token` (no refresh tokens would ever be issued), and the initializer template documents the flow.
+- [#1848] Derive `token_endpoint_auth_methods_supported` in the RFC 8414 metadata response from the effective client authentication configuration (including a deprecated `client_credentials`-only setup) instead of hardcoding the default methods. Servers that customize `client_authentication` (including extension-registered methods like `private_key_jwt`) now see their metadata reflect what the server actually accepts; unregistered names are not advertised.
+- [#1849] Support RFC 9207 (Authorization Server Issuer Identification): when `issuer` is configured, the `iss` parameter is added to the authorization responses redirected back to the client (successful and error responses alike) and `authorization_response_iss_parameter_supported` is advertised in the server metadata. Clients that parse the authorization redirect will start seeing the new `iss` parameter. A configured `issuer` that is not RFC-compliant (not an https URL, or containing a query/fragment) now logs a warning at boot, as does a path-bearing issuer, which RFC 8414 clients would not discover through Doorkeeper's root-only well-known metadata route.
+- [#1850] Fix `reuse_access_token` returning a refresh token that doesn't match the request: token reuse now requires the candidate's refresh token presence to match what the request asks for, in both directions. A request that expects a refresh token (e.g. `use_refresh_token` enabled) no longer reuses a token issued without one (previously the refresh token was silently omitted), and a request that does not expect one no longer reuses a token that carries one (previously an unrequested refresh token was returned, reachable via a per-request `refresh_token_enabled` callable). The requirement participates in the token matching itself, so an older matching token that satisfies it is still reused; a fresh token is created only when none does. **API change for ORM extensions**: `matching_token_for` and `find_matching_token` now take an optional block (`&filter`) that a token must satisfy to count as a match — extensions overriding either method must accept the block and honor it (accept and yield).
+- [#1851] Fix duplicate query parameter in the authorization callback when a client's registered `redirect_uri` already contains a parameter with the same name as a response parameter (e.g. `state`). The redirect query was merged with string keys on one side and symbol keys on the other, so a collision emitted the parameter twice (`?state=fixed&code=...&state=user`); the response parameter now overrides the registered one and appears exactly once. A blank response parameter (e.g. no `state` sent with the request) leaves the registered parameter untouched, per RFC 6749 §3.1.2.
+- [#1852] Fix the `pkce_code_challenge_methods` config validator using line anchors (`^`/`$`) instead of string anchors (`\A`/`\z`), so a multi-line value such as `"plain\ngarbage"` passed validation and was retained as a (never-matching) challenge method instead of being rejected and reset to the default.
+- [#1853] Fix `reuse_access_token` reusing a token that was created with `custom_access_token_attributes` values when the new request doesn't specify any custom attributes. Such requests now only match tokens without custom attributes.
+- [#1854] Fix the RFC 8414 metadata endpoint raising `ActionController::UrlGenerationError` (HTTP 500) when `use_doorkeeper` configures a custom controller whose namespace depth differs from `doorkeeper/metadata` (e.g. `controllers tokens: "custom_tokens"`).
+- [#1855] Perform the fallback secret upgrade-on-access write (plain → hashed token or application secret) through the primary database role, so `enable_multiple_database_roles` setups no longer attempt the write on a read replica when the lookup happens in a request routed to the reading role.
+- [#1857] Pin with regression specs that a `+` between scopes in a form-encoded token request is decoded as a space (so `scope=public+write` refreshes fine), while a percent-encoded literal `+` (`%2B`) names a single scope and is rejected when unknown, per RFC 6749 §3.3. Test-only change, closes [#1686].
+- [#1859] Pin with regression specs that a refresh token bound to an expired access token can be revoked (fixed by [#1744]) and that the revoked refresh token is rejected at the token endpoint afterwards. Test-only change, closes [#1671].
+- [#1860] Fix introspection of refresh tokens (RFC 7662): a refresh token bound to an expired access token now introspects as `active: true`, matching the token endpoint which still accepts it. The introspection response for a presented refresh token no longer includes the paired access token's `token_type` and `exp`. Fixes [#1858].
+- [#1862] Document that with `reuse_access_token` enabled token matching considers only the application, resource owner, scopes and custom token attributes — separate authorization grants for the same combination intentionally share one access token — and pin the behavior with a regression spec. Docs/test-only change, closes [#1693].
+- [#1864] Fix `custom_access_token_attributes` values being dropped when the authorization goes through the consent screen: the approve/deny forms now carry the custom attributes as hidden fields, and the pre-authorization JSON (`api_only` mode) includes them so custom consent UIs can send them back.
+- [#1869] Improve test coverage
+- [#1870] Fix: raise the intended `Doorkeeper::Errors::TokenGeneratorNotFound` / `UnableToGenerateToken` (instead of a confusing `NameError`) when `application_secret_generator` is misconfigured.
+
 ## 5.9.5
 
 - [#1901] Reject requests that authenticate the client with more than one method (RFC 6749 §2.3) with an `invalid_request` error, instead of silently authenticating with the first method that matched and discarding the other credentials.
-
-## 5.9.4
-
 - [#1853] Fix `reuse_access_token` reusing a token that was created with `custom_access_token_attributes` values when the new request doesn't specify any custom attributes. Such requests now only match tokens without custom attributes.
 
 ## 5.9.3
@@ -35,6 +101,7 @@ User-visible changes worth mentioning.
 - [#1797] Fix `doorkeeper:db:cleanup` rake task failure on PostgreSQL
 - [#1800] Set `@grant_type` in `ClientCredentialsRequest` and `RefreshTokenRequest` constructors so `request.grant_type` returns
   the correct value in hooks like `before_successful_strategy_response`.
+- [#1801] Fix `hash_application_secrets` fallback not upgrading secret on access.
 - [#1802] Fix `filter_parameters` not applied when `Doorkeeper.configure` is called inside to_prepare.
 - [#1804] Use `ActiveSupport.on_load(:active_record)` in ORM hooks to prevent loading ActiveRecord models too early
 - [#1806] Fix token revocation bypass for public clients (RFC 7009)

data/README.md

@@ -24,6 +24,8 @@ Supported features:
 - [OAuth 2.0 Threat Model and Security Considerations](https://datatracker.ietf.org/doc/html/rfc6819)
 - [OAuth 2.0 for Native Apps](https://datatracker.ietf.org/doc/html/rfc8252)
 - [Proof Key for Code Exchange by OAuth Public Clients](https://datatracker.ietf.org/doc/html/rfc7636)
+- [OAuth 2.0 Authorization Server Issuer Identification](https://datatracker.ietf.org/doc/html/rfc9207) — opt-in by setting `issuer`; adds the `iss` parameter to authorization redirects returned to the client
+- [Resource Indicators for OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)
 
 ## Table of Contents
 
@@ -37,6 +39,9 @@ Supported features:
   - [Grape](#grape)
 - [ORMs](#orms)
 - [Extensions](#extensions)
+- [Resource Indicators](#resource-indicators)
+- [Custom Grant Flows](#custom-grant-flows)
+- [Custom Client Authentication Methods](#custom-client-authentication-methods)
 - [Example Applications](#example-applications)
 - [Sponsors](#sponsors)
 - [Development](#development)
@@ -106,6 +111,205 @@ Extensions that are not included by default and can be installed separately.
 | CIBA - Client Initiated Backchannel Authentication Flow extension | [doorkeeper-ciba](https://github.com/autoseg/doorkeeper-ciba) |
 | Device Authorization Grant | [doorkeeper-device_authorization_grant](https://github.com/exop-group/doorkeeper-device_authorization_grant) |
 
+## Resource Indicators
+
+Doorkeeper supports [Resource Indicators for OAuth 2.0 (RFC 8707)](https://datatracker.ietf.org/doc/html/rfc8707), allowing clients to signal which protected resource(s) they intend to access. Tokens are then audience-restricted to those resources.
+
+### Setup
+
+1. Run the generator to add the required `resource` column:
+
+```bash
+rails generate doorkeeper:resource_indicators
+rails db:migrate
+```
+
+2. Configure a validator in your initializer:
+
+```ruby
+# config/initializers/doorkeeper.rb
+Doorkeeper.configure do
+  resource_indicator_validator ->(resource_indicators, client) {
+    allowed = %w[https://api.example.com/ https://calendar.example.com/]
+    resource_indicators.all? { |r| allowed.include?(r) }
+  }
+end
+```
+
+The callable receives an array of resource URIs and the OAuth client. Return `true` to accept or `false` to reject with `invalid_target`.
+
+### Behavior
+
+- Resource URIs must be absolute and must not contain a fragment component.
+- Resource indicators are stored on grants and tokens.
+- Token and refresh requests enforce subset restrictions against the original grant.
+- Token introspection responses include `aud` when resource indicators are present.
+- Grants issued with resource indicators retain their audience restriction even if the validator is later removed from configuration.
+
+### Multiple resources
+
+RFC 8707 uses repeated query parameters (`?resource=…&resource=…`) for multiple values, but Rack collapses repeated keys to the last value. Clients must use the Rails bracket syntax for multiple resource indicators:
+
+```
+?resource[]=https://api.example.com/&resource[]=https://calendar.example.com/
+```
+
+A single `resource=…` works as-is.
+
+## Custom Grant Flows
+
+Besides the built-in OAuth 2 flows, Doorkeeper can recognize and process any custom grant type through its grant flow registry — including grant types whose names are URNs or URIs, such as the SAML 2.0 bearer assertion grant defined by [RFC 7522](https://www.rfc-editor.org/rfc/rfc7522).
+
+A grant flow bundles a matcher for the `grant_type` parameter with a strategy class that processes the token request. Register it before `Doorkeeper.configure` and enable it by adding its registered name to `grant_flows`:
+
+```ruby
+# config/initializers/doorkeeper.rb
+Doorkeeper::GrantFlow.register(
+  :saml2_bearer,
+  grant_type_matches: "urn:ietf:params:oauth:grant-type:saml2-bearer",
+  grant_type_strategy: SamlBearer::Strategy,
+)
+
+Doorkeeper.configure do
+  grant_flows %w[authorization_code saml2_bearer]
+  # ...
+end
+```
+
+Note that `grant_flows` lists the *registered flow name* (`saml2_bearer`), while `grant_type_matches` — a `String` or a `Regexp` — is what the request's `grant_type` parameter is matched against.
+
+The strategy class receives the authorization server as `server` and builds the request object handling the grant:
+
+```ruby
+module SamlBearer
+  class Strategy < Doorkeeper::Request::Strategy
+    delegate :client, :parameters, to: :server
+
+    def request
+      @request ||= TokenRequest.new(Doorkeeper.config, client, parameters)
+    end
+  end
+end
+```
+
+The request object validates the grant and issues the token. Subclassing `Doorkeeper::OAuth::BaseRequest` provides the response handling, scope calculation and token creation, so only the grant-specific parts remain (per RFC 7522 §2.1 the `assertion` parameter carries a single SAML assertion, base64url-encoded without padding):
+
+```ruby
+module SamlBearer
+  class TokenRequest < Doorkeeper::OAuth::BaseRequest
+    validate :client, error: Doorkeeper::Errors::InvalidClient
+    validate :client_supports_grant_flow, error: Doorkeeper::Errors::UnauthorizedClient
+    validate :assertion, error: Doorkeeper::Errors::InvalidGrant
+    validate :scopes, error: Doorkeeper::Errors::InvalidScope
+
+    attr_reader :client, :parameters, :access_token
+
+    def initialize(server, client, parameters = {})
+      @server          = server
+      @client          = client
+      @parameters      = parameters
+      @original_scopes = parameters[:scope]
+      @grant_type      = "urn:ietf:params:oauth:grant-type:saml2-bearer"
+    end
+
+    private
+
+    def before_successful_response
+      find_or_create_access_token(client, resource_owner, scopes, {}, server)
+      super
+    end
+
+    def assertion
+      # Decode and verify the SAML assertion — signature, audience, validity
+      # window, etc. — e.g. with the ruby-saml gem. Skipping verification
+      # turns the endpoint into a token vending machine for anyone.
+      @assertion ||= decode_and_verify_saml(parameters[:assertion])
+    end
+
+    def resource_owner
+      # Map the assertion's subject to a resource owner.
+      @resource_owner ||= User.find_by(email: assertion.name_id)
+    end
+
+    def validate_client
+      client.present?
+    end
+
+    def validate_client_supports_grant_flow
+      Doorkeeper.config.allow_grant_flow_for_client?(grant_type, client&.application)
+    end
+
+    def validate_assertion
+      assertion.present? && resource_owner.present?
+    end
+
+    def validate_scopes
+      return true if scopes.blank?
+
+      Doorkeeper::OAuth::Helpers::ScopeChecker.valid?(
+        scope_str: scopes.to_s,
+        server_scopes: server.scopes,
+        app_scopes: client&.scopes,
+        grant_type: grant_type,
+      )
+    end
+  end
+end
+```
+
+The `client_supports_grant_flow` validation keeps the custom grant subject to the `allow_grant_flow_for_client` configuration option (per-client grant restrictions), just like the built-in flows.
+
+Flows can also handle custom `response_type` values on the authorization endpoint via the `response_type_matches` / `response_type_strategy` options — see the built-in registrations in [`lib/doorkeeper/grant_flow.rb`](lib/doorkeeper/grant_flow.rb) for reference. An extension can also group several flows under one configuration name with `Doorkeeper::GrantFlow.register_alias` (e.g. the OpenID Connect extension registers `implicit_oidc` to expand to multiple response types).
+
+## Custom Client Authentication Methods
+
+Doorkeeper authenticates clients (RFC 6749 §2.3) through a registry of named methods. `client_secret_basic`, `client_secret_post` and `none` are built in, and an application or extension can register additional ones — for instance to keep accepting credentials that a partner integration sends in its own headers.
+
+A method is any object that responds to `matches_request?` and `authenticate`. Register it before `Doorkeeper.configure` and enable it by listing its registered name in `client_authentication`:
+
+```ruby
+# config/initializers/doorkeeper.rb
+Doorkeeper::ClientAuthentication.register(
+  :partner_headers,
+  PartnerHeaders::Authentication,
+)
+
+Doorkeeper.configure do
+  client_authentication %i[client_secret_basic client_secret_post partner_headers none]
+  # ...
+end
+```
+
+The order of `client_authentication` is the order the methods are tried in: the first one whose `matches_request?` returns true handles the request.
+
+`matches_request?` decides whether the request carries this method's credentials, and `authenticate` extracts them into a `Doorkeeper::ClientAuthentication::Credentials` pair (or `nil`):
+
+```ruby
+module PartnerHeaders
+  class Authentication
+    def self.matches_request?(request)
+      request.get_header("HTTP_X_CLIENT_ID").present? &&
+        request.get_header("HTTP_X_CLIENT_SECRET").present?
+    end
+
+    def self.authenticate(request)
+      Doorkeeper::ClientAuthentication::Credentials.new(
+        request.get_header("HTTP_X_CLIENT_ID"),
+        request.get_header("HTTP_X_CLIENT_SECRET"),
+      )
+    end
+  end
+end
+```
+
+Two things are worth keeping in mind when writing one.
+
+**Keep `matches_request?` as narrow as possible.** RFC 6749 §2.3 forbids a client from using more than one authentication method in a single request, and Doorkeeper enforces that across the whole registry rather than only the enabled methods. A method that matches too broadly therefore collides with a built-in one and the request is answered with `invalid_request`.
+
+**The returned credentials are resolved with `by_uid_and_secret`.** A blank secret resolves only a public (non-confidential) client — that is what the built-in `none` method relies on — while a confidential client is resolved only when the secret matches the registered one. A method that establishes the client's identity by some other proof, such as a client certificate or a signed assertion, therefore still has to produce the registered secret for a confidential client.
+
+Enabled methods are advertised in the authorization server metadata, so a registered method appears in `token_endpoint_auth_methods_supported` at `/.well-known/oauth-authorization-server` once `client_authentication` lists it.
+
 ## Example Applications
 
 These applications show how Doorkeeper works and how to integrate with it. Start with the oAuth2 server and use the clients to connect with the server.

data/app/controllers/doorkeeper/applications_controller.rb

@@ -5,6 +5,7 @@ module Doorkeeper
     layout "doorkeeper/admin" unless Doorkeeper.configuration.api_only
 
     before_action :authenticate_admin!
+    before_action :force_json_format, if: :api_only?
     before_action :set_application, only: %i[show edit update destroy]
 
     def index
@@ -31,11 +32,13 @@ module Doorkeeper
       @application = Doorkeeper.config.application_model.new(application_params)
 
       if @application.save
-        flash[:notice] = I18n.t(:notice, scope: %i[doorkeeper flash applications create])
-        flash[:application_secret] = @application.plaintext_secret
-
         respond_to do |format|
-          format.html { redirect_to oauth_application_url(@application) }
+          format.html do
+            flash[:notice] = I18n.t(:notice, scope: %i[doorkeeper flash applications create])
+            flash[:application_secret] = @application.plaintext_secret
+
+            redirect_to oauth_application_url(@application)
+          end
           format.json { render json: @application, as_owner: true }
         end
       else
@@ -54,10 +57,12 @@ module Doorkeeper
 
     def update
       if @application.update(application_params)
-        flash[:notice] = I18n.t(:notice, scope: i18n_scope(:update))
-
         respond_to do |format|
-          format.html { redirect_to oauth_application_url(@application) }
+          format.html do
+            flash[:notice] = I18n.t(:notice, scope: i18n_scope(:update))
+
+            redirect_to oauth_application_url(@application)
+          end
           format.json { render json: @application, as_owner: true }
         end
       else
@@ -73,10 +78,14 @@ module Doorkeeper
     end
 
     def destroy
-      flash[:notice] = I18n.t(:notice, scope: i18n_scope(:destroy)) if @application.destroy
+      destroyed = @application.destroy
 
       respond_to do |format|
-        format.html { redirect_to oauth_applications_url }
+        format.html do
+          flash[:notice] = I18n.t(:notice, scope: i18n_scope(:destroy)) if destroyed
+
+          redirect_to oauth_applications_url
+        end
         format.json { head :no_content }
       end
     end
@@ -95,5 +104,25 @@ module Doorkeeper
     def i18n_scope(action)
       %i[doorkeeper flash applications] << action
     end
+
+    def api_only?
+      Doorkeeper.config.api_only
+    end
+
+    # In api_only mode this controller descends from ActionController::API,
+    # which has no flash and renders no views — but Rails still negotiates a
+    # format from the request, and only a client that names JSON explicitly
+    # lands on the json branch. Measured on Rails 8.0: an absent Accept header
+    # and a browser-like list such as "application/json, text/plain, */*"
+    # (axios's default) both resolve to text/html, while a bare "*/*" (curl,
+    # Net::HTTP, python-requests) resolves to Mime::ALL, which respond_to
+    # answers with the first registered format — html in every action here.
+    # Those requests therefore ran the html branch and raised on flash, after
+    # create had already persisted the record and destroy had already deleted
+    # it. Nothing needs negotiating when only JSON can be served, so pin the
+    # format rather than leaving a branch registered that cannot run.
+    def force_json_format
+      request.format = :json
+    end
   end
 end

data/app/controllers/doorkeeper/authorizations_controller.rb

@@ -65,7 +65,12 @@ module Doorkeeper
         pre_auth.client,
         current_resource_owner,
         pre_auth.scopes,
-      )
+      ) do |token|
+        # RFC 8707: a token for a different audience must not satisfy the match.
+        Doorkeeper.config.access_token_model.resource_indicators_match?(
+          token, pre_auth.resource_indicators&.join(" ").presence,
+        )
+      end
     end
 
     def redirect_or_render(auth)
@@ -101,11 +106,20 @@ module Doorkeeper
     end
 
     def pre_auth_params
-      params.slice(*pre_auth_param_fields).permit(*pre_auth_param_fields)
+      # RFC 8707: `resource` may appear as a single value (?resource=…) or as
+      # a Rails-style array (?resource[]=…&resource[]=…). Both scalar and array
+      # forms are permitted through strong parameters.
+      #
+      # NOTE: The RFC wire format uses repeated keys (?resource=…&resource=…),
+      # but Rack collapses those into the last value. Clients targeting this
+      # endpoint must use the resource[] bracket syntax for multiple values.
+      params
+        .slice(*pre_auth_param_fields, :resource)
+        .permit(*pre_auth_param_fields, :resource, resource: [])
     end
 
     def pre_auth_param_fields
-      custom_access_token_attributes + %i[
+      @pre_auth_param_fields ||= custom_access_token_attributes + %i[
         client_id
         code_challenge
         code_challenge_method

data/app/controllers/doorkeeper/metadata_controller.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Doorkeeper
+  class MetadataController < Doorkeeper::ApplicationMetalController
+    def show
+      headers.merge!(metadata_response.headers)
+      render json: metadata_response.body,
+             status: metadata_response.status
+    end
+
+    private
+
+    def metadata_response
+      @metadata_response ||= Doorkeeper::OAuth::MetadataResponse.new(
+        request.base_url,
+        ->(**args) { url_for(**args) },
+      )
+    end
+  end
+end

data/app/controllers/doorkeeper/tokens_controller.rb

@@ -34,7 +34,7 @@ module Doorkeeper
 
     # OAuth 2.0 Token Introspection - https://datatracker.ietf.org/doc/html/rfc7662
     def introspect
-      introspection = OAuth::TokenIntrospection.new(server, token)
+      introspection = OAuth::TokenIntrospection.new(server, token, token_type: presented_token_type)
 
       if introspection.authorized?
         render json: introspection.to_json, status: 200
@@ -123,9 +123,13 @@ module Doorkeeper
     def revocable_token
       return @revocable_token if defined? @revocable_token
 
+      # The hint is a lookup-order optimization, not a filter: a client is
+      # explicitly allowed to guess it wrong, so when the lookup by the hinted
+      # type finds nothing, RFC 7009 §2.1 and RFC 7662 §2.1 require the search
+      # to extend across the other supported token type.
       @revocable_token =
         if params[:token_type_hint] == "refresh_token"
-          refresh_token
+          refresh_token || access_token
         else
           access_token || refresh_token
         end
@@ -138,6 +142,15 @@ module Doorkeeper
       RevocableTokens::RevocableRefreshToken.new(token)
     end
 
+    # Revocation (RFC 7009) and introspection (RFC 7662) deliberately share
+    # the same request shape — `token` plus an optional `token_type_hint` —
+    # so both actions resolve the presented token through #revocable_token.
+    # The wrapper type doubles as the record of which credential the client
+    # actually presented.
+    def presented_token_type
+      revocable_token.is_a?(RevocableTokens::RevocableRefreshToken) ? :refresh_token : :access_token
+    end
+
     def access_token
       token = Doorkeeper.config.access_token_model.by_token(params["token"])
       return unless token

data/app/views/doorkeeper/authorizations/new.html.erb

@@ -19,6 +19,18 @@
     </div>
   <% end %>
 
+  <% if Array(@pre_auth.resource_indicators).any? %>
+    <div id="oauth-resources">
+      <h3><%= t('.resources') %></h3>
+
+      <ul class="text-info">
+        <% Array(@pre_auth.resource_indicators).each do |resource| %>
+          <li><%= resource %></li>
+        <% end %>
+      </ul>
+    </div>
+  <% end %>
+
   <div class="actions">
     <%= form_tag oauth_authorization_path, method: :post do %>
       <%= hidden_field_tag :client_id, @pre_auth.client.uid, id: nil %>
@@ -29,6 +41,12 @@
       <%= hidden_field_tag :scope, @pre_auth.scope, id: nil %>
       <%= hidden_field_tag :code_challenge, @pre_auth.code_challenge, id: nil %>
       <%= hidden_field_tag :code_challenge_method, @pre_auth.code_challenge_method, id: nil %>
+      <% @pre_auth.custom_access_token_attributes.each do |attribute_name, attribute_value| %>
+        <%= hidden_field_tag attribute_name, attribute_value, id: nil %>
+      <% end %>
+      <% Array.wrap(@pre_auth.resource_indicators).each do |resource_value| %>
+        <%= hidden_field_tag "resource[]", resource_value, id: nil %>
+      <% end %>
       <%= submit_tag t('doorkeeper.authorizations.buttons.authorize'), class: "btn btn-success btn-lg btn-block" %>
     <% end %>
     <%= form_tag oauth_authorization_path, method: :delete do %>
@@ -40,6 +58,12 @@
       <%= hidden_field_tag :scope, @pre_auth.scope, id: nil %>
       <%= hidden_field_tag :code_challenge, @pre_auth.code_challenge, id: nil %>
       <%= hidden_field_tag :code_challenge_method, @pre_auth.code_challenge_method, id: nil %>
+      <% @pre_auth.custom_access_token_attributes.each do |attribute_name, attribute_value| %>
+        <%= hidden_field_tag attribute_name, attribute_value, id: nil %>
+      <% end %>
+      <% Array.wrap(@pre_auth.resource_indicators).each do |resource_value| %>
+        <%= hidden_field_tag "resource[]", resource_value, id: nil %>
+      <% end %>
       <%= submit_tag t('doorkeeper.authorizations.buttons.deny'), class: "btn btn-danger btn-lg btn-block" %>
     <% end %>
   </div>

data/config/locales/en.yml

@@ -70,6 +70,7 @@ en:
         title: 'Authorization required'
         prompt: 'Authorize %{client_name} to use your account?'
         able_to: 'This application will be able to:'
+        resources: 'Resources'
       show:
         title: 'Authorization code:'
       form_post:
@@ -108,6 +109,7 @@ en:
           other: 'The code_challenge_method must be one of %{challenge_methods}.'
         server_error: 'The authorization server encountered an unexpected condition which prevented it from fulfilling the request.'
         temporarily_unavailable: 'The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server.'
+        invalid_target: 'The requested resource is invalid, missing, unknown, or malformed.'
 
         # Configuration error messages
         credential_flow_not_configured: 'Resource Owner Password Credentials flow failed due to Doorkeeper.configure.resource_owner_from_credentials being unconfigured.'

data/lib/doorkeeper/client_authentication/credentials.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Doorkeeper
+  module ClientAuthentication
+    Credentials = Struct.new(:uid, :secret) do
+      # Public clients may have their secret blank, but "credentials" are
+      # still present as long as the uid is present.
+      delegate :blank?, to: :uid
+    end
+  end
+end

data/lib/doorkeeper/client_authentication/fallback_method.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Doorkeeper
+  module ClientAuthentication
+    # Used when no registered client authentication method matches the
+    # request. It matches everything and authenticates to nothing, mirroring
+    # the previous behaviour where an unauthenticated request simply yielded
+    # no credentials.
+    class FallbackMethod
+      def self.matches_request?(_request)
+        true
+      end
+
+      def self.authenticate(_request)
+        nil
+      end
+    end
+  end
+end