Skip to content

Commit 33a2bbf

Browse files
committed
Let a provider customize the HTTP client the OAuth flow uses
## Motivation and Context `MCP::Client::OAuth::Flow` takes an `http_client_factory:`, but `MCP::Client::HTTP` builds the flow itself and passes none, so an application using `oauth:` could not add middleware to the requests the flow makes: Protected Resource Metadata and authorization server metadata discovery, dynamic client registration, and every token request. The block that customizes the transport's Faraday connection does not help, because that connection is bound to the MCP server URL and carries the `headers:` meant for that server, and the authorization server is a different origin. The TypeScript SDK hands the transport's `fetch` to `auth()` and the Python SDK sends the provider's requests through the transport's httpx client, so both let an application instrument these requests; this SDK did not. (#558) Providers now take `http_client_customizer:`, a callable invoked with the Faraday connection the flow builds for its own requests, next to the other callables a provider already holds. It runs after the SDK's defaults (`Accept: application/json`, no redirect following) and between two middlewares of the SDK's own: `Flow::RequestedURLStamp`, registered before the customizer is invoked, records the URL the flow asked for on the request environment, and `Flow::RequestedOriginGuard`, registered last, sees what the customizer's middleware did to the request after that record. A request that would leave that origin, by following a redirect or rewriting the URL, or that arrives without the record, is refused with `Flow::DestinationMismatchError` before it reaches the adapter. The record lives on the environment rather than in `env.request.context`, which stays the application's to fill or replace. The error is an `ArgumentError` rather than an `AuthorizationError` so neither discovery nor the transport's refresh fallback can absorb a configuration mistake. The boundary resembles the one the Python SDK keeps for its own requests, which follows a redirect only within the origin; this flow follows none itself. `Flow.build_http_client` assembles that connection and `Flow.new(http_client_factory:)` keeps replacing it whole. Following done inside an adapter cannot be seen by any guard, so the documentation keeps that, `Accept-Encoding`, and `raise_error` off the list of things a customizer may add, and notes that a recording middleware sees client credentials and tokens. Fixes #558. ## How Has This Been Tested? New tests in `test/mcp/client/oauth/flow_test.rb`, `test/mcp/client/oauth/http_oauth_test.rb`, and the three provider test files. Against the library before this change, every one of them fails, on the unknown keyword or on the missing reader. ## Breaking Changes None. The customizer is opt-in, and the guard cannot fire on the SDK's own middleware-free connection.
1 parent 41fbf05 commit 33a2bbf

14 files changed

Lines changed: 859 additions & 26 deletions

‎docs/_client/authorization.md‎

Lines changed: 41 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,8 @@ Optional keyword arguments:
9595
- `scope`: Space-separated scopes to request when the server's `WWW-Authenticate` does not specify one.
9696
- `authorization_request_validator`: Callable invoked with an `MCP::Client::OAuth::AuthorizationRequest` before any authorization request is built.
9797
Returning a falsy value abandons the flow with `Flow::AuthorizationRefusedError`. See [Reviewing the authorization request](#reviewing-the-authorization-request).
98+
- `http_client_customizer`: Callable invoked with the Faraday connection the SDK builds for the OAuth flow's own requests, after its defaults and before its origin guard.
99+
See [Customizing the OAuth HTTP Client](#customizing-the-oauth-http-client).
98100
- `storage`: Object responding to `tokens`, `save_tokens(t)`, `client_information`, `save_client_information(info)`. Defaults to `MCP::Client::OAuth::InMemoryStorage`,
99101
which keeps credentials in process memory only. Persisted `client_information` is stamped with an `"issuer"` member binding it to the authorization server that
100102
issued it (SEP-2352): when the server's authorization server changes, the SDK discards the stale registration and its tokens and re-registers automatically
@@ -207,7 +209,7 @@ Keyword arguments:
207209
- `private_key`, `signing_algorithm`: Required with `private_key_jwt` - the key (a PEM string
208210
or `OpenSSL::PKey::PKey`, never written to `storage`) signs the client assertion with `"ES256"`
209211
or `"RS256"`; `client_secret` must not be set, because the private key is the credential.
210-
- `scope`, `storage`, `authorization_request_validator`: Optional, same meaning as on `Provider`.
212+
- `scope`, `storage`, `authorization_request_validator`, `http_client_customizer`: Optional, same meaning as on `Provider`.
211213

212214
### Cross-App Access (JWT Bearer) Grant
213215

@@ -244,7 +246,39 @@ Keyword arguments:
244246
- `assertion_provider`: Required. Callable invoked as `call(audience:, resource:)` and returning the ID-JAG assertion.
245247
`audience` is the MCP authorization server's validated issuer identifier; `resource` is the canonical MCP server URL (RFC 8707).
246248
Passing both through to `IDJAGTokenExchange.request` covers the common case.
247-
- `scope`, `storage`, `authorization_request_validator`: Optional, same meaning as on `Provider`.
249+
- `scope`, `storage`, `authorization_request_validator`, `http_client_customizer`: Optional, same meaning as on `Provider`.
250+
251+
### Customizing the OAuth HTTP Client
252+
253+
The requests the OAuth flow makes (Protected Resource Metadata discovery on the MCP server's origin, authorization server metadata discovery,
254+
dynamic client registration, and every token request the flow sends, whether the first exchange, a refresh, or a step-up) go over a Faraday connection of their own,
255+
not over the transport's connection: the transport's is bound to the MCP server URL and carries the `headers:` and the customizer block meant for that server.
256+
To add middleware to the OAuth flow's connection, or to swap its adapter, pass `http_client_customizer:` to the provider:
257+
258+
```ruby
259+
provider = MCP::Client::OAuth::ClientCredentialsProvider.new(
260+
client_id: "my-service",
261+
client_secret: ENV.fetch("MCP_CLIENT_SECRET"),
262+
http_client_customizer: ->(faraday) { faraday.use MyApp::Middleware::HttpRecorder },
263+
)
264+
```
265+
266+
The callable receives the `Faraday::Connection` after the SDK has applied its defaults and registered the middleware that records the requested URL,
267+
and before the SDK registers its origin guard, the same position the transport's customizer block has on the MCP server connection.
268+
It may be invoked more than once, and from more than one thread at a time, so keep it free of side effects and safe to run concurrently;
269+
today it runs once per authorization attempt, but that is not a promise.
270+
A few constraints follow from the checks described below:
271+
272+
- Do not add redirect-following middleware. Every destination check runs against the URL as written, so a request that middleware added by the customizer would send
273+
to a different origin after the SDK has recorded the requested URL, whether by following a `3xx` or by rewriting the URL, is refused with `Flow::DestinationMismatchError`
274+
before it reaches the adapter, as is a request that reaches the guard without that record. Middleware inserted ahead of the record with `builder.insert(0, ...)`
275+
that rewrites the URL first or rebuilds the environment is outside the guard, as is following done inside an adapter, so leave both off.
276+
- Leave `Accept-Encoding` unset. The response cap below is measured on decoded bytes, and claiming the header turns Net::HTTP's decoding off.
277+
- Do not add Faraday's `raise_error` middleware. The flow reads statuses itself, both to tell an absent metadata document from a failed request
278+
and to turn a token endpoint error into `Flow::InvalidGrantError`.
279+
- With an adapter that does not stream through `on_data`, the response cap is applied once the body has been buffered rather than as it arrives.
280+
- A middleware that records requests sees the client credentials on token requests (`Authorization: Basic`, `client_secret`, `client_assertion`), refresh tokens,
281+
and the access tokens in token responses; redact them before they reach a log.
248282

249283
### Communication Security
250284

@@ -276,8 +310,11 @@ The range check compares IP literals and does not resolve hostnames, so it canno
276310
such as `https://vault.corp.internal/`. Resolving names here would not close that gap either, because the address the SDK looked up need not be the one
277311
the HTTP client connects to a moment later. The same-origin rule is what protects the `resource_metadata` URL, which is the only one of these a server supplies directly.
278312

279-
If you replace the OAuth HTTP client through `MCP::Client::OAuth::Flow.new(http_client_factory:)`, do not add redirect-following middleware. Every check above runs against
280-
the URL as written, so a connection that follows a `3xx` on its own would reach hosts these rules just refused.
313+
On the connection the SDK builds, a middleware that would send a request to a different origin, by following a `3xx` or by rewriting the URL, is refused before the request
314+
goes out (see [Customizing the OAuth HTTP Client](#customizing-the-oauth-http-client)). A connection supplied through `MCP::Client::OAuth::Flow.new(http_client_factory:)`
315+
replaces that one, the provider's `http_client_customizer` and the guard included, so do not add redirect-following middleware to it: every check above runs against
316+
the URL as written, and a connection that follows a `3xx` on its own would reach hosts these rules just refused.
317+
A factory that wants to keep them can return `MCP::Client::OAuth::Flow.build_http_client(customizer)`, the connection the SDK builds for itself.
281318

282319
The SDK also bounds what those endpoints may return. A discovery, dynamic client registration, token, or token exchange response is refused once it passes 4 MiB,
283320
measured as the body arrives rather than after it has been buffered, so a compressed body that expands past the limit is refused partway through the expansion.

‎docs/_client/transports.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -248,6 +248,9 @@ http_transport = MCP::Client::HTTP.new(url: "https://api.example.com/mcp") do |f
248248
end
249249
```
250250

251+
The block customizes only the connection to the MCP server. The connection the OAuth flow uses for its own requests is customized through
252+
the provider's `http_client_customizer:` keyword instead; see [Customizing the OAuth HTTP Client](/client/authorization/#customizing-the-oauth-http-client).
253+
251254
{: .note }
252255
> Answers to server-to-client requests (a pong, an elicitation result) are POSTed from inside
253256
> the SSE streaming callback of another response, re-entering the connection on the same thread.

‎lib/mcp/client/oauth/bounded_body.rb‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ def initialize(max_bytes: MAX_RESPONSE_BYTES)
2626
# Faraday `on_data` streaming callback. The chunks arrive decompressed: the default `Net::HTTP` adapter negotiates
2727
# `Accept-Encoding` itself and reads the body through `Net::HTTPResponse#inflater`, so a small compressed body
2828
# that expands past the cap is refused partway through the expansion rather than after it. That holds only while
29-
# the connection leaves `Accept-Encoding` to the adapter; see `Flow#default_http_client`.
29+
# the connection leaves `Accept-Encoding` to the adapter; see `Flow.build_http_client`.
3030
def on_data
3131
proc do |chunk, _received_bytes, _env|
3232
@buffer << chunk

‎lib/mcp/client/oauth/client_credentials_provider.rb‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,8 @@ module OAuth
4242
# an `InMemoryStorage`. The `client_id` / `client_secret` are written
4343
# into it so the token exchange reads them through the same path as
4444
# a pre-registered authorization-code client.
45+
# - `http_client_customizer` - Callable invoked with the `Faraday::Connection` the flow builds for
46+
# its own requests; see `StorageBackedProvider#http_client_customizer`.
4547
class ClientCredentialsProvider
4648
include StorageBackedProvider
4749

@@ -61,7 +63,8 @@ def initialize(
6163
signing_algorithm: nil,
6264
scope: nil,
6365
storage: nil,
64-
authorization_request_validator: nil
66+
authorization_request_validator: nil,
67+
http_client_customizer: nil
6568
)
6669
if blank?(client_id)
6770
raise InvalidCredentialsError, "client_id is required for the client_credentials grant."
@@ -99,12 +102,15 @@ def initialize(
99102
client_information["client_secret"] = client_secret
100103
end
101104

105+
http_client_customizer = validated_http_client_customizer(http_client_customizer)
106+
102107
@client_id = client_id
103108
@private_key = private_key
104109
@signing_algorithm = signing_algorithm
105110
@scope = scope
106111
@storage = storage || InMemoryStorage.new
107112
@authorization_request_validator = authorization_request_validator
113+
@http_client_customizer = http_client_customizer
108114
@storage.save_client_information(client_information)
109115
end
110116

‎lib/mcp/client/oauth/cross_app_access_provider.rb‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,8 @@ module OAuth
2525
# the Protected Resource Metadata do not specify one.
2626
# - `storage` - Object responding to `tokens`, `save_tokens(tokens)`, `client_information`, and `save_client_information(info)`.
2727
# Defaults to an `InMemoryStorage`.
28+
# - `http_client_customizer` - Callable invoked with the `Faraday::Connection` the flow builds for its own requests;
29+
# see `StorageBackedProvider#http_client_customizer`.
2830
#
2931
# https://github.com/modelcontextprotocol/modelcontextprotocol/issues/990
3032
class CrossAppAccessProvider
@@ -35,7 +37,7 @@ class InvalidConfigurationError < ArgumentError; end
3537

3638
attr_reader :scope, :storage
3739

38-
def initialize(client_id:, client_secret:, assertion_provider:, scope: nil, storage: nil, authorization_request_validator: nil)
40+
def initialize(client_id:, client_secret:, assertion_provider:, scope: nil, storage: nil, authorization_request_validator: nil, http_client_customizer: nil)
3941
if blank?(client_id)
4042
raise InvalidConfigurationError, "client_id is required for the jwt-bearer grant."
4143
end
@@ -48,10 +50,13 @@ def initialize(client_id:, client_secret:, assertion_provider:, scope: nil, stor
4850
raise InvalidConfigurationError, "assertion_provider must be callable as `call(audience:, resource:)` and return the ID-JAG assertion."
4951
end
5052

53+
http_client_customizer = validated_http_client_customizer(http_client_customizer)
54+
5155
@assertion_provider = assertion_provider
5256
@scope = scope
5357
@storage = storage || InMemoryStorage.new
5458
@authorization_request_validator = authorization_request_validator
59+
@http_client_customizer = http_client_customizer
5560
@storage.save_client_information(
5661
"client_id" => client_id,
5762
"client_secret" => client_secret,

‎lib/mcp/client/oauth/flow.rb‎

Lines changed: 102 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,98 @@ class InvalidGrantError < AuthorizationError; end
4040
# or authorization server metadata failure by rescuing a class rather than by matching the message text.
4141
class AuthorizationRefusedError < AuthorizationError; end
4242

43+
# Raised by `RequestedOriginGuard` when middleware added through the provider's `http_client_customizer`
44+
# would send a request to an origin other than the one the flow validated, or has dropped the record of
45+
# the URL the flow asked for. An `ArgumentError` because the middleware is a configuration mistake,
46+
# and deliberately outside `AuthorizationError`, which discovery treats as "nothing published"
47+
# and `MCP::Client::HTTP` treats on a failed refresh as a reason to run the interactive flow.
48+
class DestinationMismatchError < ArgumentError; end
49+
50+
# Faraday middleware registered on the connection `build_http_client` assembles before the customizer
51+
# is invoked, so with the usual `use` it sits ahead of the customizer's middleware and sees the URL exactly
52+
# as the flow requested it, which it records on the request environment for `RequestedOriginGuard`.
53+
# The guard covers what happens to a request after that record; middleware inserted ahead of it with
54+
# `builder.insert(0, ...)` that rewrites the URL before it or rebuilds the environment is outside the guard.
55+
# The record lives on the environment, not in `env.request.context`: that slot belongs to the application,
56+
# which may fill it on the connection or replace it from a middleware of its own. Only the first URL seen
57+
# on an environment is recorded: a middleware inserted ahead of this one that re-enters the stack after
58+
# a `3xx` with the same environment, or with its `dup`, which shares the record, cannot replace it with
59+
# the redirected URL.
60+
class RequestedURLStamp
61+
KEY = :mcp_oauth_requested_url
62+
63+
def initialize(app)
64+
@app = app
65+
end
66+
67+
def call(env)
68+
env[KEY] ||= env.url.to_s
69+
@app.call(env)
70+
end
71+
end
72+
73+
# Faraday middleware registered last on that connection, so it sees `env.url` after any customizer-added
74+
# middleware has rewritten it or followed a redirect. A request that would leave the origin the flow asked
75+
# for is refused before it reaches the adapter, since every destination check ran against the URL as
76+
# written; a same-origin change stays with the server those checks admitted. The record survives
77+
# the `env.dup` that redirect-following middleware performs, and a request that arrives without it is
78+
# refused as well, so a middleware that rebuilds the environment fails closed rather than open.
79+
# The origin boundary resembles the one the Python SDK keeps for its own auth requests, which follows
80+
# a redirect itself only within the origin; this flow follows none.
81+
class RequestedOriginGuard
82+
def initialize(app)
83+
@app = app
84+
end
85+
86+
def call(env)
87+
requested = env[RequestedURLStamp::KEY]
88+
unless requested
89+
raise DestinationMismatchError,
90+
"Request to #{Discovery.canonicalize_origin_and_path(env.url.to_s).inspect} carries no record of " \
91+
"the URL the flow asked for; middleware that rebuilds the request environment is refused."
92+
end
93+
94+
unless Discovery.same_origin?(env.url.to_s, requested)
95+
raise DestinationMismatchError,
96+
"Request to #{Discovery.canonicalize_origin_and_path(requested).inspect} would be sent to " \
97+
"#{Discovery.canonicalize_origin_and_path(env.url.to_s).inspect}, on a different origin; " \
98+
"middleware that follows redirects or rewrites URLs is refused."
99+
end
100+
101+
@app.call(env)
102+
end
103+
end
104+
private_constant :RequestedURLStamp, :RequestedOriginGuard
105+
106+
class << self
107+
# Builds the connection the flow uses for its own requests: the SDK's defaults, `RequestedURLStamp`,
108+
# then `customizer` (a provider's `http_client_customizer`, called with the `Faraday::Connection`),
109+
# then `RequestedOriginGuard` last so it sees what the customizer's middleware does to each request
110+
# after the stamp recorded it. Every request on the connection passes through both, so a caller using
111+
# it directly is held to the same origin rule.
112+
#
113+
# Deliberately built without redirect-following middleware. Every destination check in this class runs
114+
# against the URL as written, before the request goes out, so a connection that transparently followed
115+
# a `3xx` would let a server reach a host the checks just refused. The guard turns following at
116+
# the middleware level into a refusal; following inside an adapter stays invisible, so a customizer must
117+
# not enable it.
118+
#
119+
# `Accept-Encoding` is deliberately left unset. `Net::HTTP::GenericRequest` negotiates it and decodes
120+
# the response only while the caller has not claimed that header; assigning it turns `decode_content` off,
121+
# which would silently move `BoundedBody`'s cap onto compressed bytes and let a small body expand past it
122+
# after the check.
123+
def build_http_client(customizer = nil)
124+
require "faraday"
125+
126+
Faraday.new do |faraday|
127+
faraday.headers["Accept"] = "application/json"
128+
faraday.use(RequestedURLStamp)
129+
customizer&.call(faraday)
130+
faraday.use(RequestedOriginGuard)
131+
end
132+
end
133+
end
134+
43135
def initialize(provider:, http_client_factory: nil)
44136
@provider = provider
45137
@http_client_factory = http_client_factory || -> { default_http_client }
@@ -1191,22 +1283,18 @@ def http_client
11911283
@http_client ||= @http_client_factory.call
11921284
end
11931285

1194-
# Deliberately built without redirect-following middleware. Every destination check in
1195-
# this class runs against the URL as written, before the request goes out, so a connection
1196-
# that transparently followed a `3xx` would let a server reach a host the checks just refused.
1197-
# A caller passing `http_client_factory:` takes on that responsibility: add redirect following here
1198-
# and the guards above only cover the first hop.
1199-
#
1200-
# `Accept-Encoding` is deliberately left unset. `Net::HTTP::GenericRequest` negotiates it and decodes
1201-
# the response only while the caller has not claimed that header; assigning it turns `decode_content` off,
1202-
# which would silently move `BoundedBody`'s cap onto compressed bytes and let a small body expand past it
1203-
# after the check.
1286+
# A connection supplied through `http_client_factory:` replaces this one, the provider's customizer and
1287+
# `RequestedOriginGuard` included, so that caller takes on the redirect responsibility described on
1288+
# `build_http_client`; `bounded_request` caps its responses all the same.
12041289
def default_http_client
1205-
require "faraday"
1290+
self.class.build_http_client(provider_http_client_customizer)
1291+
end
12061292

1207-
Faraday.new do |faraday|
1208-
faraday.headers["Accept"] = "application/json"
1209-
end
1293+
# `nil` for a provider that predates the hook or leaves it unset.
1294+
def provider_http_client_customizer
1295+
return unless @provider.respond_to?(:http_client_customizer)
1296+
1297+
@provider.http_client_customizer
12101298
end
12111299

12121300
def response_body_string(response)

‎lib/mcp/client/oauth/id_jag_token_exchange.rb‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -95,7 +95,7 @@ def parse_id_jag(response)
9595
assertion
9696
end
9797

98-
# `Accept-Encoding` is deliberately left unset, for the same reason as `Flow#default_http_client`:
98+
# `Accept-Encoding` is deliberately left unset, for the same reason as `Flow.build_http_client`:
9999
# claiming that header turns Net::HTTP's `decode_content` off and would move `BoundedBody`'s cap
100100
# onto compressed bytes.
101101
def default_http_client

0 commit comments

Comments
 (0)