Skip to content

Commit 14b4f7c

Browse files
committed
Validate the RFC 9207 iss Authorization Response Parameter per SEP-2468
## Motivation and Context SEP-2468 (modelcontextprotocol/modelcontextprotocol#2468, merged for the 2026-07-28 spec release) recommends that authorization servers include the RFC 9207 `iss` parameter in authorization responses and requires MCP clients to validate a present `iss` against the expected issuer before redeeming the authorization code. This mitigates mix-up attacks in multi-IdP setups, where an attacker-controlled authorization server could otherwise capture a code minted by an honest server. This mirrors the TypeScript SDK's approach (typescript-sdk#2272, with typescript-sdk#1957 as the reference implementation), adapted to the Ruby provider contract: - `Provider`'s `callback_handler` may now return `[code, state, iss]` in addition to the existing `[code, state]`. The 3-element form opts into validation; returning `iss = nil` asserts the caller inspected the authorization response and found no `iss`. - `Flow#run!` validates the issuer after the `state` check and before `exchange_authorization_code`, implementing the RFC 9207 Section 2.4 rules: a present `iss` must equal the AS metadata `issuer` exactly (the value `ensure_issuer_matches!` already pinned to the discovery URL); a nil `iss` from a 3-element callback is rejected when the AS metadata advertises `authorization_response_iss_parameter_supported: true`; a legacy 2-element callback skips the check, so every existing integration keeps working. On any violation the flow aborts with `AuthorizationError` before the code reaches a token endpoint. - The conformance client now returns the 3-element form, plumbing `iss` through from the redirect URL. Resolves #386. ## How Has This Been Tested? New tests in `test/mcp/client/oauth/flow_test.rb`: - a matching `iss` completes the flow and persists tokens - a mismatched `iss` raises `AuthorizationError` and never contacts the token endpoint (`assert_not_requested` on the token POST) - a nil `iss` with `authorization_response_iss_parameter_supported: true` raises without contacting the token endpoint (fail closed) - a legacy 2-element callback completes even when the AS advertises `iss` support (backward compatibility) - a nil `iss` without the advertisement completes - a mismatched `iss` is rejected even without the advertisement (validate-when-present is unconditional) `bundle exec rake` (tests, RuboCop, and conformance baseline with the 3-element conformance callback) passes. ## Breaking Changes None. The 2-element `callback_handler` contract continues to work unchanged; issuer validation activates only when a callback opts in by returning the 3-element form.
1 parent b7bd9bb commit 14b4f7c

5 files changed

Lines changed: 163 additions & 5 deletions

File tree

‎README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2118,7 +2118,9 @@ Required keyword arguments to `Provider.new`:
21182118
an explicit value always wins.
21192119
- `redirect_uri`: String. Must use HTTPS or be a loopback URL (`localhost`, `127.0.0.0/8`, `::1`); other values raise `Provider::InsecureRedirectURIError`.
21202120
- `redirect_handler`: Callable invoked with the fully-built authorization `URI`. Typically opens the user's browser.
2121-
- `callback_handler`: Callable that returns `[code, state]` after the user is redirected back to `redirect_uri`.
2121+
- `callback_handler`: Callable that returns `[code, state]` or `[code, state, iss]` after the user is redirected back to `redirect_uri`. Returning the 3-element form
2122+
(with `iss` set to the RFC 9207 `iss` parameter from the redirect, or `nil` when absent) opts into SEP-2468 issuer validation: a present `iss` must match
2123+
the authorization server's issuer, and a missing one is rejected when the server advertises `authorization_response_iss_parameter_supported`.
21222124

21232125
Optional keyword arguments:
21242126

‎conformance/client.rb‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -95,7 +95,9 @@ def build_oauth_provider(context, scenario:)
9595

9696
callback_handler = -> do
9797
query = URI.decode_www_form(callback_holder.fetch(:url).query).to_h
98-
[query["code"], query["state"]]
98+
# The 3-element form opts into SEP-2468 / RFC 9207 `iss` validation;
99+
# `query["iss"]` is nil when the authorization response carried no `iss`.
100+
[query["code"], query["state"], query["iss"]]
99101
end
100102

101103
MCP::Client::OAuth::Provider.new(

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

Lines changed: 45 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -74,13 +74,20 @@ def run!(server_url:, resource_metadata_url: nil, scope: nil)
7474
)
7575

7676
@provider.redirect_handler.call(authorization_url)
77-
code, returned_state = Array(@provider.callback_handler.call)
77+
callback_result = Array(@provider.callback_handler.call)
78+
code, returned_state, returned_iss = callback_result
7879
raise AuthorizationError, "Authorization callback did not return an authorization code." unless code
7980

8081
unless states_match?(returned_state, state)
8182
raise AuthorizationError, "OAuth state mismatch (CSRF protection)."
8283
end
8384

85+
validate_authorization_response_issuer!(
86+
as_metadata: as_metadata,
87+
iss: returned_iss,
88+
iss_provided: callback_result.length >= 3,
89+
)
90+
8491
tokens = exchange_authorization_code(
8592
as_metadata: as_metadata,
8693
client_info: client_info,
@@ -534,6 +541,43 @@ def safe_canonicalize_url(url, label:)
534541
raise AuthorizationError, "#{label} #{url.inspect} is not a valid URI: #{e.message}."
535542
end
536543

544+
# Validates the RFC 9207 `iss` authorization response parameter against the issuer of the authorization server
545+
# the flow is talking to, per SEP-2468 (mix-up attack mitigation in multi-IdP setups):
546+
#
547+
# - When the callback supplied a non-empty `iss`, it MUST equal the AS metadata `issuer` exactly (simple string comparison,
548+
# no normalization, per RFC 9207 Section 2.4); on mismatch the flow aborts before the authorization code is ever sent to
549+
# a token endpoint.
550+
# - When the callback returned a 3-element `[code, state, iss]` whose `iss` is nil (asserting it inspected the authorization response
551+
# and found no `iss`) and the AS metadata advertises `authorization_response_iss_parameter_supported: true`, the missing parameter
552+
# is treated as an attack per RFC 9207 Section 2.4 and the flow aborts.
553+
# - A legacy 2-element `[code, state]` callback skips the check: the caller never looked for `iss`, so its absence carries no signal.
554+
#
555+
# `as_metadata["issuer"]` has already been byte-compared against the discovery URL by `ensure_issuer_matches!`,
556+
# so it is the RFC 9207 anchor value. `iss` is not a secret; a plain `==` suffices.
557+
#
558+
# - https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2468
559+
# - https://www.rfc-editor.org/rfc/rfc9207
560+
def validate_authorization_response_issuer!(as_metadata:, iss:, iss_provided:)
561+
expected = as_metadata["issuer"]
562+
563+
if iss && !iss.to_s.empty?
564+
return if iss.to_s == expected.to_s
565+
566+
raise AuthorizationError,
567+
"Authorization response `iss` does not match the authorization server issuer " \
568+
"(expected #{expected.inspect}, got #{iss.inspect}) (RFC 9207); " \
569+
"refusing to exchange the authorization code."
570+
end
571+
572+
return unless iss_provided
573+
return unless as_metadata["authorization_response_iss_parameter_supported"] == true
574+
575+
raise AuthorizationError,
576+
"Authorization server advertises `authorization_response_iss_parameter_supported` but " \
577+
"the authorization response carried no `iss` parameter (RFC 9207 Section 2.4); " \
578+
"refusing to exchange the authorization code."
579+
end
580+
537581
# Constant-time comparison for the OAuth `state` parameter to prevent timing-based discovery
538582
# of the expected value.
539583
# `OpenSSL.fixed_length_secure_compare` would be ideal, but it is not available on Ruby 2.7

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

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,13 @@ module OAuth
2121
# - `redirect_handler` - Callable invoked with the fully-built authorization
2222
# URL (a `URI`). Implementations typically open the user's browser.
2323
# - `callback_handler` - Callable invoked after `redirect_handler`. Returns
24-
# `[code, state]` where `code` is the authorization code and `state` is
25-
# the `state` parameter received on the redirect URI.
24+
# `[code, state]` or `[code, state, iss]`, where `code` is the authorization code,
25+
# `state` is the `state` parameter received on the redirect URI, and `iss` is
26+
# the RFC 9207 `iss` parameter (or nil when the authorization response carried none).
27+
# Returning the 3-element form opts into SEP-2468 issuer validation: a present `iss`
28+
# must match the authorization server's issuer, and a nil `iss` is
29+
# rejected when the AS advertises `authorization_response_iss_parameter_supported`.
30+
# The 2-element form skips the check for backward compatibility.
2631
#
2732
# Optional keyword arguments:
2833
# - `scope` - String of space-separated scopes to request when the server's

‎test/mcp/client/oauth/flow_test.rb‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -985,6 +985,111 @@ def test_run_raises_when_dcr_response_lacks_client_id
985985
assert_match(/client_id/i, error.message)
986986
end
987987

988+
# Builds a provider whose callback returns the given `iss` shape:
989+
# `:omitted` keeps the legacy 2-element `[code, state]` form, any other value (including nil) returns
990+
# the 3-element `[code, state, iss]` form that opts into SEP-2468 / RFC 9207 issuer validation.
991+
def build_iss_validation_provider(callback_iss: :omitted)
992+
state_holder = {}
993+
callback_handler = if callback_iss == :omitted
994+
-> { ["test-auth-code", state_holder[:state]] }
995+
else
996+
-> { ["test-auth-code", state_holder[:state], callback_iss] }
997+
end
998+
999+
Provider.new(
1000+
client_metadata: {
1001+
redirect_uris: ["http://localhost:0/callback"],
1002+
grant_types: ["authorization_code"],
1003+
response_types: ["code"],
1004+
token_endpoint_auth_method: "none",
1005+
},
1006+
redirect_uri: "http://localhost:0/callback",
1007+
redirect_handler: ->(url) {
1008+
state_holder[:state] = URI.decode_www_form(url.query).to_h.fetch("state")
1009+
},
1010+
callback_handler: callback_handler,
1011+
)
1012+
end
1013+
1014+
# Re-stubs the AS metadata with `authorization_response_iss_parameter_supported: true`.
1015+
def stub_as_metadata_with_iss_support
1016+
stub_request(:get, @as_metadata_url).to_return(
1017+
status: 200,
1018+
headers: { "Content-Type" => "application/json" },
1019+
body: JSON.generate(
1020+
issuer: @auth_base,
1021+
authorization_endpoint: "#{@auth_base}/authorize",
1022+
token_endpoint: "#{@auth_base}/token",
1023+
registration_endpoint: "#{@auth_base}/register",
1024+
response_types_supported: ["code"],
1025+
grant_types_supported: ["authorization_code"],
1026+
code_challenge_methods_supported: ["S256"],
1027+
token_endpoint_auth_methods_supported: ["none"],
1028+
authorization_response_iss_parameter_supported: true,
1029+
),
1030+
)
1031+
end
1032+
1033+
def test_run_completes_when_authorization_response_iss_matches_issuer
1034+
provider = build_iss_validation_provider(callback_iss: @auth_base)
1035+
1036+
result = Flow.new(provider: provider).run!(server_url: @server_url, resource_metadata_url: @prm_url)
1037+
1038+
assert_equal(:authorized, result)
1039+
assert_equal("test-token-from-flow", provider.access_token)
1040+
end
1041+
1042+
def test_run_aborts_before_code_exchange_when_authorization_response_iss_mismatches
1043+
provider = build_iss_validation_provider(callback_iss: "https://evil.example.com")
1044+
1045+
error = assert_raises(Flow::AuthorizationError) do
1046+
Flow.new(provider: provider).run!(server_url: @server_url, resource_metadata_url: @prm_url)
1047+
end
1048+
1049+
# Per RFC 9207, the client MUST NOT send the authorization code to a token endpoint after an `iss` mismatch.
1050+
assert_match(/`iss` does not match/, error.message)
1051+
assert_not_requested(:post, "#{@auth_base}/token")
1052+
end
1053+
1054+
def test_run_aborts_when_iss_is_missing_but_as_advertises_iss_support
1055+
stub_as_metadata_with_iss_support
1056+
provider = build_iss_validation_provider(callback_iss: nil)
1057+
1058+
error = assert_raises(Flow::AuthorizationError) do
1059+
Flow.new(provider: provider).run!(server_url: @server_url, resource_metadata_url: @prm_url)
1060+
end
1061+
1062+
assert_match(/carried no `iss`/, error.message)
1063+
assert_not_requested(:post, "#{@auth_base}/token")
1064+
end
1065+
1066+
def test_run_completes_with_legacy_two_element_callback_even_when_as_advertises_iss_support
1067+
stub_as_metadata_with_iss_support
1068+
provider = build_iss_validation_provider
1069+
1070+
result = Flow.new(provider: provider).run!(server_url: @server_url, resource_metadata_url: @prm_url)
1071+
1072+
assert_equal(:authorized, result)
1073+
end
1074+
1075+
def test_run_completes_when_iss_is_missing_and_as_does_not_advertise_iss_support
1076+
provider = build_iss_validation_provider(callback_iss: nil)
1077+
1078+
result = Flow.new(provider: provider).run!(server_url: @server_url, resource_metadata_url: @prm_url)
1079+
1080+
assert_equal(:authorized, result)
1081+
end
1082+
1083+
def test_run_validates_present_iss_even_when_as_does_not_advertise_iss_support
1084+
provider = build_iss_validation_provider(callback_iss: "https://evil.example.com")
1085+
1086+
assert_raises(Flow::AuthorizationError) do
1087+
Flow.new(provider: provider).run!(server_url: @server_url, resource_metadata_url: @prm_url)
1088+
end
1089+
1090+
assert_not_requested(:post, "#{@auth_base}/token")
1091+
end
1092+
9881093
def test_run_skips_dcr_when_client_information_already_stored
9891094
stub_request(:post, "#{@auth_base}/register").to_raise(StandardError.new("DCR should not be called."))
9901095

0 commit comments

Comments
 (0)