doorkeeper 6.0.0.rc2 → 6.0.0.rc3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +20 -0
  3. data/README.md +84 -1
  4. data/app/controllers/doorkeeper/authorizations_controller.rb +4 -1
  5. data/lib/doorkeeper/config.rb +40 -1
  6. data/lib/doorkeeper/helpers/controller.rb +3 -0
  7. data/lib/doorkeeper/http_fetcher.rb +164 -28
  8. data/lib/doorkeeper/models/access_token_mixin.rb +89 -2
  9. data/lib/doorkeeper/oauth/authorization/token.rb +5 -2
  10. data/lib/doorkeeper/oauth/authorization_code_request.rb +21 -0
  11. data/lib/doorkeeper/oauth/client.rb +4 -0
  12. data/lib/doorkeeper/oauth/client_id_metadata_document.rb +276 -0
  13. data/lib/doorkeeper/oauth/helpers/uri_checker.rb +5 -2
  14. data/lib/doorkeeper/oauth/metadata_response.rb +6 -3
  15. data/lib/doorkeeper/oauth/pre_authorization.rb +43 -4
  16. data/lib/doorkeeper/oauth/refresh_token_request.rb +29 -4
  17. data/lib/doorkeeper/oauth/token_introspection.rb +14 -2
  18. data/lib/doorkeeper/orm/active_record/redirect_uri_validator.rb +13 -4
  19. data/lib/doorkeeper/orm/active_record/stale_records_cleaner.rb +6 -3
  20. data/lib/doorkeeper/rails/routes/abstract_router.rb +1 -1
  21. data/lib/doorkeeper/rails/routes.rb +5 -1
  22. data/lib/doorkeeper/rake/db.rake +14 -1
  23. data/lib/doorkeeper/revocable_tokens/revocable_refresh_token.rb +13 -1
  24. data/lib/doorkeeper/version.rb +1 -1
  25. data/lib/doorkeeper.rb +1 -0
  26. data/lib/generators/doorkeeper/client_id_metadata_documents_generator.rb +33 -0
  27. data/lib/generators/doorkeeper/refresh_token_revoked_at_generator.rb +43 -0
  28. data/lib/generators/doorkeeper/templates/add_client_id_metadata_materialized_at_to_applications_migration.rb.erb +7 -0
  29. data/lib/generators/doorkeeper/templates/add_refresh_token_revoked_at_to_access_tokens.rb.erb +13 -0
  30. data/lib/generators/doorkeeper/templates/initializer.rb +47 -0
  31. data/lib/generators/doorkeeper/templates/migration.rb.erb +7 -0
  32. metadata +8 -3
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: c6d4350f4bd6db700eb44e19c8078618b64e440bfd1edf8ec51ef306ec1a99a9
4
- data.tar.gz: a284bba8ee06ab1bf53ca43fd8a803320c4d5fe1b2576f24633f3119b23582b0
3
+ metadata.gz: '08827ac1f710ee7d20f7170c7ab4b10bfd937aae4bd91b1500c2cbae15a63274'
4
+ data.tar.gz: ef806a4a2773d1c581344e79f1c101b635ffa033a4965d4592b0da6196299fc5
5
5
  SHA512:
6
- metadata.gz: 33c85db50f78fbef731514c037cda2fbbe40b3b7c3c25e671563781e946c02aed6084ff0a2cc5bae0409e7e2808ab4f30d67639f3274b039ac39cc27a8144e3f
7
- data.tar.gz: 633fbee3c0259e194a1b183f3c959ef90194d721755bcad84ccf0d198173f94d88aed428b615aed3e3c3d83d2b8c01f2b6f317d036f074aa9b0c699180a2e2a8
6
+ metadata.gz: 2da570c7050cb814492a0924e2e67831a24169a181895a0cad1c160e56aa1ef6c2fe8e818e237444116c8d506e157e9c43b5ab82d2029cbc413133c7f3f32cfe
7
+ data.tar.gz: f65a4387ce097f675d3f61b5ee547b92977e02f047fef3ec6ce65afa3f6e7bc2ea325e35b1b94d8df58fcb28cc1d8d4be6d7815a98542878c3569dc32c94dd79
data/CHANGELOG.md CHANGED
@@ -9,6 +9,26 @@ User-visible changes worth mentioning.
9
9
 
10
10
  - [#PR ID] Description of the change.
11
11
 
12
+ ## 6.0.0.rc3
13
+
14
+ - [#1944] Add the `revoke_previous_access_token_on_refresh` option (default `true`): set to `false`, the refresh_token grant revokes only the exchanged refresh token and the previous access token stays usable until it expires. Requires the new `refresh_token_revoked_at` column (`rails generate doorkeeper:refresh_token_revoked_at`).
15
+ - [#1956] Add `use_client_id_metadata_documents`: public clients may use the https URL of their metadata document as `client_id` (draft-ietf-oauth-client-id-metadata-document). Needs `rails generate doorkeeper:client_id_metadata_documents`.
16
+ - [#1959] A custom `access_token_generator` now receives the token's `resource` (RFC 8707), so a JWT generator can set `aud`.
17
+ - [#1960] Ignore the port of `http://localhost` redirect URIs like that of loopback IP literals (RFC 8252 §7.3 / §8.3).
18
+ - [#1962] A client ID metadata document also qualifies when `none` is among its `token_endpoint_auth_methods_supported` (OpenID Connect RP Metadata Choices), with or without `token_endpoint_auth_method`. Such clients still authenticate with `none`, so ChatGPT's token request fails while `private_key_jwt` is among the `client_authentication` methods, unless the application model has a `jwks_uri` column (#1978).
19
+ - [#1964] `rake doorkeeper:db:cleanup:expired_tokens` no longer raises when `access_token_expires_in` is `nil`; tokens with an individual `expires_in` are still removed once expired (#1963).
20
+ - [#1965] Fix: `force_pkce` without the PKCE columns (`rails generate doorkeeper:pkce`) no longer accepts any `code_verifier`. The authorization code flow is now refused with `server_error` until the migration is applied.
21
+ - [#1973] Add `allow_client_id_metadata_document` to limit which clients may use a metadata document. A refused `client_id` is never fetched, and one already known is refused at the authorization and token endpoints, also on refresh.
22
+ - [#1975] Enforce a wall-clock timeout and a byte budget, headers included, on `HttpFetcher`; refuse special-use addresses from the post-RFC 6890 registries, IPv6 literals and unconnectable ports before fetching; accept a leading byte order mark in a fetched document.
23
+ - [#1978] A client ID metadata document's `jwks_uri` is kept when the application model has a `jwks_uri` column. A document preferring `private_key_jwt` then makes a confidential client, which has to authenticate with its key wherever the server offers `private_key_jwt`, and whose tokens stay under `public_client_access_token_expires_in`.
24
+ - [#1979] **[BREAKING]** Refuse the non-standard out-of-band redirect URIs (`urn:ietf:wg:oauth:2.0:oob`, `urn:ietf:wg:oauth:2.0:oob:auto`) by default: when an application is registered, at the authorization endpoint and on the code exchange; `oauth/authorize/native` is no longer drawn. Applications already stored with such a URI are refused with `invalid_redirect_uri` at the authorization endpoint and `invalid_grant` on the code exchange. Set `allow_oob_redirect_uris true` to keep the old behavior.
25
+ - [#1980] Omit `scopes_supported` from the authorization server metadata when no scopes are configured (RFC 8414 §3.2).
26
+ - [#1990] Omit `code_challenge_methods_supported` from the authorization server metadata when the PKCE columns are missing (RFC 8414 §3.2).
27
+ - [#1992] Fix: a router that includes `Doorkeeper::Rails::AbstractRouter` without its own `initialize` no longer raises `NameError` (`AbstractRouter::Mapper`) when built without a mapper.
28
+ - [#1993] Reject a protocol-relative redirect URI (e.g. `//example.com`) at application registration. It parsed with no scheme but a host, so `relative_uri?` accepted it; it is now rejected as `relative_uri` like any other scheme-less reference. The authorization endpoint already refused it (`URIChecker.valid?` requires a scheme), so this only aligns registration validation with that behavior.
29
+ - [#1994] Serve the authorization server metadata document with `Cache-Control: private` instead of `public`: its issuer and endpoint URLs follow the request host, so a shared cache must not reuse one client's copy for another.
30
+ - [#1997] Follow draft-03 of client ID metadata documents: a document naming no token endpoint auth method is a public client (`none`) instead of being refused; `private_key_jwt` among `token_endpoint_auth_methods_supported` alone now makes a confidential client as well, and one declaring it without an https `jwks_uri` is refused where the server offers it; documents whose `grant_types`/`response_types` leave out the authorization code flow, or that carry both `jwks` and `jwks_uri`, are refused; the `issuer` itself is refused as a `client_id`; a warning is logged while no `issuer` is set, as the authorization response must carry `iss`; why a document is refused is logged.
31
+
12
32
  ## 6.0.0.rc2
13
33
 
14
34
  **Please make sure** you read the [Upgrade guides](https://github.com/doorkeeper-gem/doorkeeper/wiki/Migration-from-old-versions)
data/README.md CHANGED
@@ -26,6 +26,7 @@ Supported features:
26
26
  - [Proof Key for Code Exchange by OAuth Public Clients](https://datatracker.ietf.org/doc/html/rfc7636)
27
27
  - [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
28
28
  - [Resource Indicators for OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)
29
+ - [OAuth Client ID Metadata Documents](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-client-id-metadata-document) — opt-in by setting `use_client_id_metadata_documents`; a public client identifies itself with the https URL of its metadata document instead of registering
29
30
 
30
31
  ## Table of Contents
31
32
 
@@ -42,6 +43,8 @@ Supported features:
42
43
  - [Database maintenance](#database-maintenance)
43
44
  - [Resource Indicators](#resource-indicators)
44
45
  - [Refresh Token Scopes](#refresh-token-scopes)
46
+ - [Keeping the Previous Access Token on Refresh](#keeping-the-previous-access-token-on-refresh)
47
+ - [Client ID Metadata Documents](#client-id-metadata-documents)
45
48
  - [Custom Grant Flows](#custom-grant-flows)
46
49
  - [Custom Client Authentication Methods](#custom-client-authentication-methods)
47
50
  - [Example Applications](#example-applications)
@@ -183,7 +186,87 @@ rails db:migrate
183
186
 
184
187
  With the column in place, [token introspection](https://datatracker.ietf.org/doc/html/rfc7662#section-2.2) of a refresh token reports the granted scope rather than the scope of the access token it was issued with, and `reuse_access_token` does not hand a grant of a narrower scope an existing token whose refresh token was granted a wider one.
185
188
 
186
- Without the column, a narrowed refresh narrows the refresh token as well, so the chain can never return to the granted scope (the behavior of Doorkeeper before the column existed), and a `refresh_token_scopes` assigned to an access token is ignored. Rows created before the migration keep that behavior until they are rotated, and so do the [ORM extensions](#extensions) (Sequel, MongoDB) until they add the field.
189
+ Without the column, a narrowed refresh narrows the refresh token as well, so the chain can never return to the granted scope (the behavior of Doorkeeper before the column existed), and a `refresh_token_scopes` assigned to an access token is ignored. Rows created before the migration fall back to the scope of their access token, and rotating them stores that scope in the column, so a chain narrowed before the migration stays narrowed: the wider scope it was granted cannot be recovered automatically, and the resource owner has to authorize the client again. The [ORM extensions](#extensions) (Sequel, MongoDB) keep the behavior without the column until they add the field.
190
+
191
+ ## Keeping the Previous Access Token on Refresh
192
+
193
+ A refresh token is stored on the same `oauth_access_tokens` record as the access token it was issued with, so by default exchanging it revokes both: the previous access token stops working as soon as the old refresh token is revoked (immediately, or on the first use of the new access token when the `previous_refresh_token` column exists). [RFC 6749 §6](https://datatracker.ietf.org/doc/html/rfc6749#section-6) only speaks of revoking the old *refresh* token, and a client that refreshes ahead of expiry, or from several processes, may still have requests in flight with the previous access token.
194
+
195
+ To revoke only the refresh token and let the previous access token live until it expires, add the `refresh_token_revoked_at` column:
196
+
197
+ ```bash
198
+ rails generate doorkeeper:refresh_token_revoked_at
199
+ rails db:migrate
200
+ ```
201
+
202
+ and opt in from the initializer:
203
+
204
+ ```ruby
205
+ Doorkeeper.configure do
206
+ use_refresh_token
207
+ revoke_previous_access_token_on_refresh false
208
+ end
209
+ ```
210
+
211
+ Both are required: the column alone changes nothing, and the option has no effect without the column. No backfill is needed, because a record that is already revoked (`revoked_at`) counts as having its refresh token revoked as well. `AccessToken#refresh_token_revoked?` answers for the refresh token, while `#revoked?` and `#accessible?` keep answering for the access token; [token introspection](https://datatracker.ietf.org/doc/html/rfc7662#section-2.2) reports each of them accordingly, and `reuse_access_token` does not hand out a record whose refresh token is revoked.
212
+
213
+ Things to keep in mind:
214
+
215
+ - Revoking a token through the revocation endpoint, `AccessToken#revoke` or `AccessToken.revoke_all_for` still revokes the whole record. Doorkeeper does not link the records of one refresh chain, so revoking the *current* refresh token does not reach a previous access token that was kept alive; it stays usable until it expires. Keep `access_token_expires_in` short when you enable this.
216
+ - Records whose refresh token was revoked this way keep an empty `revoked_at`, so `doorkeeper:db:cleanup:revoked_tokens` does not see them; `doorkeeper:db:cleanup:expired_tokens` removes them once their access token has expired.
217
+ - Refresh tokens revoked this way stay revoked if you set the option back to `true`. Dropping the column, however, forgets them: revoke those records first (`revoked_at`) if you ever remove it.
218
+ - The [ORM extensions](#extensions) (Sequel, MongoDB) ship their own access token mixins and keep revoking both tokens until they add the field.
219
+
220
+ ## Client ID Metadata Documents
221
+
222
+ Doorkeeper supports [OAuth Client ID Metadata Documents](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-client-id-metadata-document) for public clients: a client such as an MCP client or an agent identifies itself with the `https://` URL of a JSON document describing it, instead of registering with your server first. Doorkeeper fetches the document, keeps what it says as an application row, and the authorization code flow runs as for a registered public client. The specification is still an IETF draft, so the behavior may change with it; Doorkeeper follows draft-03.
223
+
224
+ ### Setup
225
+
226
+ 1. Run the generator to add the `client_id_metadata_materialized_at` column, which tells a row written from a document apart from a registered application (ActiveRecord only). The flow also needs the PKCE columns of `rails generate doorkeeper:pkce`:
227
+
228
+ ```bash
229
+ rails generate doorkeeper:client_id_metadata_documents
230
+ rails db:migrate
231
+ ```
232
+
233
+ 2. Enable the option in your initializer, with the scopes such a client may be granted at most. `none` has to be among the `client_authentication` methods, which it is by default:
234
+
235
+ ```ruby
236
+ # config/initializers/doorkeeper.rb
237
+ Doorkeeper.configure do
238
+ use_client_id_metadata_documents scopes: %w[read]
239
+
240
+ # Without this, any https URL can become a client.
241
+ allow_client_id_metadata_document do |client_id|
242
+ %w[claude.ai chatgpt.com].include?(URI(client_id).host)
243
+ end
244
+ end
245
+ ```
246
+
247
+ `scopes` is a hard cap: a document client never gets more, whatever its document asks for. A document without a `scope` field gets all scopes in the cap; one asking only for scopes outside the cap is refused. Always set it, as anyone can publish a document.
248
+
249
+ Set `issuer` as well: the authorization response to such a client has to carry `iss` (RFC 9207), which Doorkeeper only adds with an issuer, and logs a warning without one.
250
+
251
+ `allow_client_id_metadata_document` decides which `client_id`s are accepted, before anything is fetched. A client it stops accepting is refused from then on, refresh included. Compare the host, not a prefix: `start_with?("https://claude.ai")` also matches `claude.ai.evil.com`. The `issuer` itself is never accepted; refuse the identifiers of resource servers and other authorization servers you trust here.
252
+
253
+ The authorization server metadata at `/.well-known/oauth-authorization-server` advertises `client_id_metadata_document_supported` once the option is on. If a CDN caches that endpoint, purge it after turning the option on: ChatGPT falls back to manual registration without a word when its copy lacks the flag.
254
+
255
+ A client such as ChatGPT authenticates with `private_key_jwt` whenever the server advertises it. Doorkeeper keeps the document's `jwks_uri` on the application when your model has a `jwks_uri` column, the one `private_key_jwt` reads for registered clients as well. No Doorkeeper generator adds it; a client known before gets its `jwks_uri` on the next authorization, when its document is fetched again. A document whose `token_endpoint_auth_methods_supported` lists `private_key_jwt` next to `none`, as ChatGPT's does, makes a confidential client (one listing `private_key_jwt` without `none`, or naming it only as `token_endpoint_auth_method`, is refused, as below): it has to authenticate with its key, and `none` no longer redeems its codes or refresh tokens, or revokes its tokens. Without an https `jwks_uri` such a document is refused, as Doorkeeper verifies assertions against nothing else. Its tokens stay under `public_client_access_token_expires_in`, as anyone can publish a document with keys of their own. Without that column, leave `private_key_jwt` out of `client_authentication`, or the token request of such a client fails with `invalid_client`.
256
+
257
+ ### Behavior
258
+
259
+ - A `client_id` is taken for a document URL when it is `https`, has a path other than `/`, is at most 255 characters long and carries no userinfo, fragment or dot segments. Any other `client_id` is looked up as a registered `uid`.
260
+ - The document must name its own URL as `client_id`, list at least one `redirect_uris` entry, and be a public client: `token_endpoint_auth_method` is `none`, or `token_endpoint_auth_methods_supported` ([OpenID Connect RP Metadata Choices](https://openid.net/specs/openid-connect-rp-metadata-choices-1_0.html)) lists `none` and no shared-secret method, as ChatGPT's does next to its preferred `private_key_jwt`. A document naming neither is a public client too: draft-03 rules out RFC 7591's default of `client_secret_basic` here. A document asking for a shared secret, or with both `jwks` and `jwks_uri`, is refused, as is one whose `grant_types` leave out `authorization_code` or whose `response_types` leave out `code` (absent, they default to those). Redirect URIs your server refuses are dropped, the rest kept; a document left with none is refused. `force_ssl_in_redirect_uri` is on everywhere but development, so the loopback redirects of native clients (RFC 8252 Section 7.3) are dropped unless you let them through:
261
+
262
+ ```ruby
263
+ force_ssl_in_redirect_uri { |uri| !%w[127.0.0.1 ::1 localhost].include?(uri.hostname) }
264
+ ```
265
+
266
+ - These clients get authorization codes only, always with S256 PKCE, and `skip_authorization` does not apply, so the user consents on every authorization, also when a confidential one already holds a token. The consent screen shows the document's host before its `client_name`, as the only verified hint of who is asking.
267
+ - A failed fetch aborts the authorization request, also for a client seen before: new authorizations fail until its host answers again, while issued tokens and refresh keep working, as a transient failure must not invalidate them. A changed document updates the client on the next fetch.
268
+ - A registered application whose `uid` is a URL is used as registered and never fetched. Turning the option off refuses the clients written from documents, but access tokens already issued stay valid until they expire.
269
+ - Fetches are bounded (https only, no redirects, a few seconds and kilobytes, no private or special-use addresses). Failed fetches are not cached, so rate limiting of the authorization endpoint is left to the host application. With `validate_client_before_resource_owner_authentication`, documents are fetched and applications created before anyone signs in, so without an allow hook anyone can create them anonymously.
187
270
 
188
271
  ## Custom Grant Flows
189
272
 
@@ -115,8 +115,11 @@ module Doorkeeper
115
115
  @client_pre_auth ||= OAuth::PreAuthorization.new(Doorkeeper.configuration, pre_auth_params)
116
116
  end
117
117
 
118
+ # Never for a client known only from its metadata document, confidential or not: anyone can publish one.
118
119
  def can_authorize_response?
119
- Doorkeeper.config.custom_access_token_attributes.empty? && pre_auth.client.application.confidential? && matching_token?
120
+ application = pre_auth.client.application
121
+ Doorkeeper.config.custom_access_token_attributes.empty? && application.confidential? &&
122
+ !OAuth::ClientIdMetadataDocument.materialized?(application) && matching_token?
120
123
  end
121
124
 
122
125
  # Active access token issued for the same client and resource owner with
@@ -155,7 +155,7 @@ module Doorkeeper
155
155
  # Choose to use the url path for native autorization codes
156
156
  # Enabling this flag sets the authorization code response route for
157
157
  # native redirect uris to oauth/authorize/<code>. The default is
158
- # oauth/authorize/native?code=<code>.
158
+ # oauth/authorize/native?code=<code>. Needs allow_oob_redirect_uris.
159
159
  # Rationale: https://github.com/doorkeeper-gem/doorkeeper/issues/1143
160
160
  def use_url_path_for_native_authorization
161
161
  @config.instance_variable_set(:@use_url_path_for_native_authorization, true)
@@ -182,6 +182,18 @@ module Doorkeeper
182
182
  @config.instance_variable_set(:@force_pkce, true)
183
183
  end
184
184
 
185
+ # Accept https URLs as the client_id of public clients, per
186
+ # draft-ietf-oauth-client-id-metadata-document. +scopes+ (Strings or
187
+ # Symbols, or a space-separated String) caps what such a client may
188
+ # request; a document naming no scope gets the whole cap. Without a cap,
189
+ # the document's scope applies, else the default scopes. Needs the column
190
+ # added by `rails generate doorkeeper:client_id_metadata_documents`.
191
+ def use_client_id_metadata_documents(scopes: nil)
192
+ scopes = scopes.is_a?(String) ? OAuth::Scopes.from_string(scopes) : scopes&.map(&:to_s)
193
+ @config.instance_variable_set(:@use_client_id_metadata_documents, true)
194
+ @config.instance_variable_set(:@client_id_metadata_document_scopes, scopes)
195
+ end
196
+
185
197
  # Validate the authorization request's client_id and redirect_uri before
186
198
  # authenticating the resource owner, so users are not sent through login
187
199
  # for a request that can only fail (disabled by default)
@@ -319,9 +331,19 @@ module Doorkeeper
319
331
  # Ceiling for the TTL of access tokens issued to public clients (OAuth 2.1 Section 2.4).
320
332
  # Applies to every grant, including refresh_token. nil (the default) means no ceiling.
321
333
  option :public_client_access_token_expires_in, default: nil
334
+ # Whether the refresh_token grant revokes the access token the presented
335
+ # refresh token was issued with (true, the default) or leaves it usable
336
+ # until it expires and revokes only the refresh token (false). Disabling
337
+ # it takes effect only once the `refresh_token_revoked_at` column exists
338
+ # (`rails generate doorkeeper:refresh_token_revoked_at`).
339
+ option :revoke_previous_access_token_on_refresh, default: true
322
340
  option :authorization_code_expires_in, default: 600
323
341
  option :orm, default: :active_record
324
342
  option :native_redirect_uri, default: "urn:ietf:wg:oauth:2.0:oob", deprecated: true
343
+ # Accept the non-standard out-of-band redirect URIs urn:ietf:wg:oauth:2.0:oob
344
+ # and urn:ietf:wg:oauth:2.0:oob:auto and draw the page that shows the code
345
+ # (oauth/authorize/native). Off by default, as OAuth 2.1 has no such flow.
346
+ option :allow_oob_redirect_uris, default: false
325
347
  option :grant_flows, default: %w[authorization_code client_credentials]
326
348
  option :pkce_code_challenge_methods, default: %w[plain S256]
327
349
  option :handle_auth_errors, default: :render
@@ -387,6 +409,16 @@ module Doorkeeper
387
409
  #
388
410
  option :forbid_redirect_uri, default: ->(_uri) { false }
389
411
 
412
+ # Limits which clients may identify themselves by a metadata document
413
+ # (see use_client_id_metadata_documents). Called with the client_id before
414
+ # the document is fetched; a client it refuses is never fetched, and one
415
+ # already known is refused at the authorization and token endpoints, also
416
+ # on refresh. Accepts every client by default.
417
+ #
418
+ # @param allow_client_id_metadata_document [Proc] Block or any object respond to #call
419
+ #
420
+ option :allow_client_id_metadata_document, default: ->(_client_id) { true }
421
+
390
422
  # WWW-Authenticate Realm (default "Doorkeeper").
391
423
  #
392
424
  # @param realm [String] ("Doorkeeper") Authentication realm
@@ -564,6 +596,7 @@ module Doorkeeper
564
596
  end)
565
597
 
566
598
  attr_reader :reuse_access_token,
599
+ :client_id_metadata_document_scopes,
567
600
  :enable_multiple_database_roles,
568
601
  :token_secret_fallback_strategy,
569
602
  :application_secret_fallback_strategy
@@ -641,6 +674,10 @@ module Doorkeeper
641
674
  option_set? :force_pkce
642
675
  end
643
676
 
677
+ def use_client_id_metadata_documents?
678
+ option_set? :use_client_id_metadata_documents
679
+ end
680
+
644
681
  def validate_client_before_resource_owner_authentication?
645
682
  option_set? :validate_client_before_resource_owner_authentication
646
683
  end
@@ -865,6 +902,8 @@ module Doorkeeper
865
902
  end
866
903
 
867
904
  def allow_grant_flow_for_client?(grant_flow, client)
905
+ # A client known from its metadata document gets authorization codes only (RFC 9700 §2.1.2, §2.4).
906
+ return false if OAuth::ClientIdMetadataDocument.materialized?(client) && grant_flow != OAuth::AUTHORIZATION_CODE
868
907
  return true unless option_defined?(:allow_grant_flow_for_client)
869
908
 
870
909
  allow_grant_flow_for_client.call(grant_flow, client)
@@ -83,7 +83,10 @@ module Doorkeeper
83
83
  self.status = error.status
84
84
  end
85
85
 
86
+ # Never for a client known only from its metadata document: anyone can publish one.
86
87
  def skip_authorization?
88
+ return false if OAuth::ClientIdMetadataDocument.materialized?(@pre_auth.client.application)
89
+
87
90
  !!instance_exec(
88
91
  [server.current_resource_owner, @pre_auth.client],
89
92
  &Doorkeeper.config.skip_authorization
@@ -3,6 +3,7 @@
3
3
  require "ipaddr"
4
4
  require "net/http"
5
5
  require "resolv"
6
+ require "timeout"
6
7
  require "uri"
7
8
 
8
9
  module Doorkeeper
@@ -20,12 +21,12 @@ module Doorkeeper
20
21
  # in turn. An exception for authorization servers themselves running on a
21
22
  # loopback interface is intentionally not implemented. These rules follow
22
23
  # the fetch hardening of draft-ietf-oauth-client-id-metadata-document
23
- # (Sections 6.5 / 6.6), which fetches documents from the same kind of
24
+ # (Sections 8.6 / 8.7), which fetches documents from the same kind of
24
25
  # client-chosen URL.
25
26
  #
26
- # The response body is bounded and so is the total time spent reading it:
27
- # a per-read timeout alone does not stop a server that dribbles bytes out
28
- # indefinitely.
27
+ # The response is bounded in size — headers and body alike — and so is
28
+ # the time the whole exchange may take: a per-read timeout alone does not
29
+ # stop a server that dribbles bytes out indefinitely.
29
30
  #
30
31
  # Everything about the response is chosen by whoever hosts the document —
31
32
  # which is whoever supplied the URL — so no failure mode here may escape
@@ -34,12 +35,33 @@ module Doorkeeper
34
35
  OPEN_TIMEOUT = 5
35
36
  READ_TIMEOUT = 5
36
37
 
37
- # draft-ietf-oauth-client-id-metadata-document Section 6.6 recommends a
38
+ # draft-ietf-oauth-client-id-metadata-document Section 8.7 recommends a
38
39
  # maximum response size of 5 kilobytes for a document like this.
39
40
  MAX_RESPONSE_SIZE = 5 * 1024
40
41
 
41
- # Ceiling on the whole exchange, so a body delivered one byte per
42
- # READ_TIMEOUT cannot hold the connection (and the thread) for hours.
42
+ # Net::HTTP reads the status line, every header line and every chunk-size
43
+ # line of a chunked body through its buffered socket with no limit on
44
+ # their length — and before the response object exists, so before
45
+ # anything below could look at it. What a host could push in that phase
46
+ # would be bounded by nothing but its bandwidth and MAX_TOTAL_TIME. The
47
+ # budget is therefore enforced at the socket: every byte read for the
48
+ # exchange counts, and the exchange is abandoned once it has read more
49
+ # than a document and the headers around it could legitimately need.
50
+ MAX_HEADER_SIZE = 8 * 1024
51
+ MAX_EXCHANGE_SIZE = MAX_RESPONSE_SIZE + MAX_HEADER_SIZE
52
+
53
+ # Ceiling on the HTTP exchange — connect, headers and body — so a host
54
+ # answering a byte at a time cannot hold the connection (and the thread
55
+ # reading it) for hours. Net::HTTP has no such setting of its own: its
56
+ # timeouts are per phase, and read_timeout starts over on every
57
+ # successful read, so neither a dribbled header block nor a dribbled body
58
+ # ever trips one. The ceiling is therefore held twice over: the per-phase
59
+ # timeouts are trimmed to what is left of it as the exchange goes on, and
60
+ # a wall clock around the whole exchange catches the phases those
61
+ # timeouts cannot see. The ceiling starts once the host's addresses have
62
+ # been vetted: resolution has to happen first, and is bounded by whatever
63
+ # timeouts the deployment's resolver applies rather than by this
64
+ # constant.
43
65
  MAX_TOTAL_TIME = 10
44
66
 
45
67
  # The document is served as JSON, either "application/json" or an
@@ -51,8 +73,14 @@ module Doorkeeper
51
73
  # in the caller.
52
74
  JSON_MEDIA_TYPE = %r{\Aapplication/([\w.+-]+\+)?json\z}i
53
75
 
54
- # RFC 6890 special-purpose IPv4/IPv6 registries, plus multicast ranges
55
- # (224.0.0.0/4, ff00::/8), which are equally unfit as a document origin.
76
+ # U+FEFF, which RFC 8259 Section 8.1 lets a reader ignore at the start of
77
+ # a JSON text.
78
+ BYTE_ORDER_MARK = "\uFEFF"
79
+
80
+ # Every non-globally-reachable range in the IANA special-purpose address
81
+ # registries RFC 6890 established (including the ranges registered
82
+ # after it: RFC 8215, RFC 9602, RFC 9637, RFC 9780), plus multicast
83
+ # (224.0.0.0/4, ff00::/8), which is equally unfit as a document origin.
56
84
  SPECIAL_USE_RANGES = [
57
85
  "0.0.0.0/8", # "this host on this network"
58
86
  "10.0.0.0/8", # private-use
@@ -78,15 +106,22 @@ module Doorkeeper
78
106
  # range also covers the two entries above.
79
107
  "::/96",
80
108
  "64:ff9b::/96", # IPv4-IPv6 translation
109
+ "64:ff9b:1::/48", # local-use IPv4-IPv6 translation (RFC 8215)
81
110
  "100::/64", # discard-only
111
+ "100:0:0:1::/64", # dummy prefix (RFC 9780)
82
112
  "2001::/23", # IETF protocol assignments (TEREDO, ORCHID, ...)
83
113
  "2001:db8::/32", # documentation
84
114
  "2002::/16", # 6to4
115
+ "3fff::/20", # documentation (RFC 9637)
116
+ "5f00::/16", # SRv6 segment identifiers (RFC 9602)
85
117
  "fc00::/7", # unique-local
86
118
  "fe80::/10", # link-local
87
119
  "ff00::/8", # multicast
88
120
  ].map { |cidr| IPAddr.new(cidr) }.freeze
89
121
 
122
+ # The range a TCP port can occupy; anything else was never connectable.
123
+ PORT_RANGE = (1..65_535)
124
+
90
125
  FetchError = Class.new(StandardError)
91
126
 
92
127
  # A transport failure raised while the connection was still being
@@ -98,6 +133,57 @@ module Doorkeeper
98
133
  ConnectError = Class.new(StandardError)
99
134
  private_constant :ConnectError
100
135
 
136
+ # The buffered socket Net::HTTP reads through, counting what it reads.
137
+ # Only the fill is overridden: net-protocol has kept the buffer's shape
138
+ # across its versions (a fill appends to the unread bytes, a consume
139
+ # advances past them), so the count is taken as the growth of the unread
140
+ # buffer around each fill.
141
+ class BoundedBufferedIO < Net::BufferedIO
142
+ attr_accessor :byte_budget, :host
143
+
144
+ private
145
+
146
+ def rbuf_fill
147
+ before = unread_bytes
148
+ super
149
+ @bytes_read = (@bytes_read || 0) + [unread_bytes - before, 0].max
150
+ return if byte_budget.nil? || @bytes_read <= byte_budget
151
+
152
+ raise FetchError, "the response from #{host} exceeds #{byte_budget} bytes, headers included"
153
+ end
154
+
155
+ def unread_bytes
156
+ @rbuf.bytesize - (@rbuf_offset || 0)
157
+ end
158
+ end
159
+ private_constant :BoundedBufferedIO
160
+
161
+ # Swaps the socket for the counting one as soon as the connection (TLS
162
+ # handshake included) is up: on_connect is the hook Net::HTTP calls right
163
+ # after wrapping the socket and before reading anything from it. Mixed
164
+ # into the one Net::HTTP instance rather than subclassing Net::HTTP, so
165
+ # that whatever Net::HTTP resolves to when a fetch is made — a test
166
+ # double's subclass included — is what gets extended.
167
+ module BoundedExchange
168
+ attr_accessor :byte_budget
169
+
170
+ private
171
+
172
+ def on_connect
173
+ @socket = BoundedBufferedIO.new(
174
+ @socket.io,
175
+ read_timeout: @socket.read_timeout,
176
+ write_timeout: @socket.write_timeout,
177
+ continue_timeout: @socket.continue_timeout,
178
+ debug_output: @socket.debug_output,
179
+ )
180
+ @socket.byte_budget = byte_budget
181
+ @socket.host = address
182
+ super
183
+ end
184
+ end
185
+ private_constant :BoundedExchange
186
+
101
187
  # Everything a host can fail at while answering, so that it surfaces as
102
188
  # a rejected client rather than an exception out of the endpoint.
103
189
  #
@@ -132,9 +218,20 @@ module Doorkeeper
132
218
  # URI.parse("https:foo") yields a URI::HTTPS whose host is nil, so a
133
219
  # caller's is_a?(URI::HTTPS) validation does not guarantee a host —
134
220
  # and Resolv raises ArgumentError, not ResolvError, when handed nil.
135
- raise FetchError, "#{url.inspect} has no host" if uri.host.blank?
136
-
137
- addresses = vetted_addresses_for(uri.host)
221
+ # #hostname, not #host: the two differ for an IPv6 literal, where
222
+ # #host keeps the brackets the URL wrote it in ("[::1]") and nothing
223
+ # downstream — neither the resolver nor the special-use check — reads
224
+ # that as an address. UrlValidator accepts such a URL, so the fetcher
225
+ # has to agree with it about what is fetchable.
226
+ raise FetchError, "#{url.inspect} has no host" if uri.hostname.blank?
227
+ # URI.parse accepts any integer as a port, but Net::HTTP builds the
228
+ # connection address out of it, where a value too large to be a port
229
+ # raises TypeError — not one of the TRANSPORT_ERRORS below. Refusing it
230
+ # here keeps every caller's URL, however it was validated, from turning
231
+ # into an exception out of the endpoint.
232
+ raise FetchError, "#{url.inspect} has an out-of-range port" unless PORT_RANGE.cover?(uri.port)
233
+
234
+ addresses = vetted_addresses_for(uri.hostname)
138
235
  # One deadline covers connection attempts to all addresses in aggregate.
139
236
  deadline = monotonic_now + MAX_TOTAL_TIME
140
237
  # If we attempt to connect to multiple addresses and all of them fail,
@@ -142,15 +239,28 @@ module Doorkeeper
142
239
  # equally valid.
143
240
  last_error = nil
144
241
 
145
- addresses.each do |address|
146
- break if last_error && monotonic_now >= deadline
147
-
148
- return perform_request(uri, address, deadline)
149
- rescue ConnectError => e
150
- last_error = e
242
+ # The deadline trims Net::HTTP's per-phase timeouts, but those only
243
+ # cover the phases Net::HTTP times at all: a status line or header
244
+ # block dribbled a byte at a time keeps resetting read_timeout and
245
+ # never trips it. So the same ceiling is also held as a wall clock
246
+ # around everything from the first connection attempt to the last body
247
+ # byte. No exception class is passed on purpose: Timeout then unwinds
248
+ # the block with an exception no `rescue` inside it can catch, and
249
+ # raises Timeout::Error only once control is back here, where it is
250
+ # one of the TRANSPORT_ERRORS below. The ceiling thus reaches #fetch
251
+ # by exactly one path, with neither the ConnectError handling nor
252
+ # Net::HTTP's own retry able to intercept it.
253
+ Timeout.timeout(MAX_TOTAL_TIME, nil, "the exchange with #{uri.hostname} took too long") do
254
+ addresses.each do |address|
255
+ break if last_error && monotonic_now >= deadline
256
+
257
+ return perform_request(uri, address, deadline)
258
+ rescue ConnectError => e
259
+ last_error = e
260
+ end
151
261
  end
152
262
 
153
- raise FetchError, "could not connect to #{uri.host}: #{last_error.message}"
263
+ raise FetchError, "could not connect to #{uri.hostname}: #{last_error.message}"
154
264
  rescue *TRANSPORT_ERRORS => e
155
265
  raise FetchError, "#{e.class}: #{e.message}"
156
266
  end
@@ -187,7 +297,16 @@ module Doorkeeper
187
297
  remaining = remaining_until(deadline)
188
298
  raise ConnectError, "no time left to connect to #{address}" if remaining <= 0
189
299
 
190
- Net::HTTP.new(uri.host, uri.port).tap do |http|
300
+ # The explicit nil disables the proxy Net::HTTP would otherwise take
301
+ # from the environment (`p_addr` defaults to :ENV, honouring
302
+ # http_proxy and friends). With a proxy configured, #connect opens
303
+ # the TCP connection to the proxy address instead of the one pinned
304
+ # via ipaddr= below, and the proxy resolves the host on its own, so
305
+ # the vetting above could be bypassed to reach an address it refused.
306
+ # The fetch therefore always connects directly.
307
+ Net::HTTP.new(uri.hostname, uri.port, nil).tap do |http|
308
+ http.extend(BoundedExchange)
309
+ http.byte_budget = MAX_EXCHANGE_SIZE
191
310
  http.use_ssl = true
192
311
  http.ipaddr = address
193
312
  # Net::HTTP can use up to the whole `open_timeout` establishing the TCP
@@ -199,9 +318,11 @@ module Doorkeeper
199
318
  # not less than `OPEN_TIMEOUT`.
200
319
  http.open_timeout = [OPEN_TIMEOUT, remaining / 2.0].min
201
320
  http.read_timeout = READ_TIMEOUT
202
- # Disable Net::HTTP internal retries to prevent re-attempting reads
203
- # which will reuse the same timeout params and may exceed the overall
204
- # timeout we're aiming for.
321
+ # Disable Net::HTTP internal retries: a request retried after a
322
+ # Net::ReadTimeout would reuse the same timeouts and push the whole
323
+ # exchange past MAX_TOTAL_TIME. Nothing is lost by turning it off:
324
+ # the connection is never reused, so there is no stale socket for a
325
+ # retry to recover from.
205
326
  http.max_retries = 0
206
327
  end
207
328
  end
@@ -227,10 +348,10 @@ module Doorkeeper
227
348
  # Net::HTTP never follows redirects on its own; a 3xx just fails
228
349
  # the status check below.
229
350
  connection.request(request) do |response|
230
- raise FetchError, "expected 200 OK from #{uri.host}, got #{response.code}" unless response.is_a?(Net::HTTPOK)
351
+ raise FetchError, "expected 200 OK from #{uri.hostname}, got #{response.code}" unless response.is_a?(Net::HTTPOK)
231
352
 
232
- verify_media_type!(response, uri.host)
233
- body = bounded_body(response, connection, uri.host, deadline)
353
+ verify_media_type!(response, uri.hostname)
354
+ body = bounded_body(response, connection, uri.hostname, deadline)
234
355
  end
235
356
  end
236
357
 
@@ -253,7 +374,9 @@ module Doorkeeper
253
374
 
254
375
  # Reads the response in chunks so an oversized (or endlessly dribbled)
255
376
  # body is abandoned instead of buffered in full. Raising here unwinds
256
- # out of Net::HTTP#start, which closes the connection.
377
+ # out of Net::HTTP#start, which closes the connection. (The socket's own
378
+ # budget, MAX_EXCHANGE_SIZE, would catch an oversized body too, headers
379
+ # permitting; this check is the one that names the body.)
257
380
  def bounded_body(response, connection, host, deadline)
258
381
  declared = response["Content-Length"]
259
382
  if declared && declared.to_i > MAX_RESPONSE_SIZE
@@ -278,7 +401,20 @@ module Doorkeeper
278
401
  connection.read_timeout = [connection.read_timeout, remaining_until(deadline)].min
279
402
  end
280
403
 
281
- body
404
+ # RFC 8259 Section 8.1: JSON exchanged between systems is UTF-8. A body
405
+ # that is not is no document, and its bytes would otherwise travel on
406
+ # tagged as UTF-8 — JSON.parse does not check — into every String
407
+ # method that does: ArgumentError out of a regex, or out of the
408
+ # base64url decoder a JWK member goes through.
409
+ body.force_encoding(Encoding::UTF_8)
410
+ raise FetchError, "the document from #{host} is not valid UTF-8" unless body.valid_encoding?
411
+
412
+ # Same section: a sender must not add a byte order mark, but a reader
413
+ # may ignore one. Editors put them on static files without asking, and
414
+ # JSON.parse reads a leading BOM as an unexpected character, which
415
+ # would refuse an otherwise well-formed document over a byte its author
416
+ # never typed.
417
+ body.delete_prefix(BYTE_ORDER_MARK)
282
418
  end
283
419
 
284
420
  def monotonic_now