Support SEP-990 Cross-App Access via ID-JAG and the jwt-bearer Grant
## Motivation and Context The MCP Enterprise Managed Authorization extension (SEP-990, modelcontextprotocol/modelcontextprotocol#990, accepted/final, published in the ext-auth repository) lets enterprise identity providers govern MCP authorization: the client exchanges an IdP-issued ID token for an Identity Assertion Authorization Grant (ID-JAG) via RFC 8693 token exchange at the IdP, then presents the ID-JAG to the MCP authorization server with the RFC 7523 `jwt-bearer` grant, authenticating with `client_secret_basic`. The `auth/cross-app-access-complete-flow` conformance scenario exercises the complete flow and previously failed its two core checks (the Ruby client ran the authorization-code flow instead). This mirrors the merged TypeScript SDK implementation (`requestJwtAuthorizationGrant` / `CrossAppAccessProvider` in typescript-sdk; the Python SDK tracks the same work in the open python-sdk#1721), adapted to this SDK's provider design: - New `MCP::Client::OAuth::IDJAGTokenExchange.request` performs the RFC 8693 exchange at the IdP token endpoint (`subject_token_type` id_token, `requested_token_type` id-jag, `audience` = the MCP authorization server's issuer, `resource` = the canonical MCP server URL) and validates that the response's `issued_token_type` is an ID-JAG before returning the assertion. The ID-JAG itself is treated as opaque, as in the TypeScript SDK. - New `MCP::Client::OAuth::CrossAppAccessProvider` declares `authorization_flow :jwt_bearer` and takes the assertion from a callable (`call(audience:, resource:)`), so the common `IDJAGTokenExchange` case, enterprise secret stores, and tests all plug in the same way (the TypeScript provider's assertion callback works identically). The MCP AS credentials are stored as `client_secret_basic` client information. - `Flow` dispatches `:jwt_bearer` alongside `:client_credentials`: discovery, issuer validation, and endpoint security checks are shared with `run!`, then `run_jwt_bearer!` requests the assertion with the validated issuer as the audience and posts the `jwt-bearer` grant through the existing `post_to_token_endpoint`. - The conformance client builds a `CrossAppAccessProvider` when the harness injects `idp_id_token` (exchanging it at `idp_token_endpoint` with `idp_client_id`, like the TypeScript and Python conformance clients), and `auth/cross-app-access-complete-flow` is removed from `conformance/expected_failures.yml`. ## How Has This Been Tested? - New `test/mcp/client/oauth/id_jag_token_exchange_test.rb` asserts the exact RFC 8693 form parameters on the wire and the response validation: a non-ID-JAG `issued_token_type` is rejected, as are a missing `access_token`, non-2xx responses, unparseable bodies, and non-object JSON. - New `test/mcp/client/oauth/cross_app_access_provider_test.rb` covers the provider surface: stored `client_secret_basic` credentials, the `:jwt_bearer` flow declaration, audience/resource passthrough to the assertion callable, constructor validation (missing client_id, missing client_secret, non-callable assertion provider), and storage delegation. - New tests in `test/mcp/client/oauth/flow_test.rb` run the full grant against WebMock stubs: the token request carries `grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer`, the assertion, the RFC 8707 `resource`, and HTTP Basic credentials, with no DCR and no authorization-code machinery; the assertion callable receives the validated issuer as `audience` and the canonical server URL as `resource`; an empty assertion aborts before the token endpoint is contacted. ## Breaking Changes None. `IDJAGTokenExchange` and `CrossAppAccessProvider` are new, and the `Flow` dispatch only activates for providers that declare `authorization_flow :jwt_bearer`.
This commit is contained in:
Koichi ITO
parent
e85f6d0632
commit
145a6b6230
3 changed files with 529 additions and 6 deletions
80
lib/mcp/client/oauth/cross_app_access_provider.rb
Normal file
80
lib/mcp/client/oauth/cross_app_access_provider.rb
Normal file
|
|
@ -0,0 +1,80 @@
|
|||
# frozen_string_literal: true
|
||||
|
||||
module MCP
|
||||
class Client
|
||||
module OAuth
|
||||
# OAuth client configuration for the MCP Enterprise Managed Authorization extension (SEP-990, "Cross-App Access"):
|
||||
# the client obtains an Identity Assertion Authorization Grant (ID-JAG) from an enterprise identity provider and
|
||||
# presents it to the MCP authorization server with the RFC 7523 `jwt-bearer` grant, authenticating with
|
||||
# `client_secret_basic`. Handed to `MCP::Client::HTTP` via the `oauth:` keyword, the same as `Provider`.
|
||||
#
|
||||
# Mirrors `CrossAppAccessProvider` in the TypeScript SDK: the assertion is supplied by a callable so it can come
|
||||
# from `IDJAGTokenExchange` (the common case), an enterprise secret store, or a test double.
|
||||
#
|
||||
# Required keyword arguments:
|
||||
#
|
||||
# - `client_id` - String identifying the pre-registered confidential client at the MCP authorization server.
|
||||
# - `client_secret` - String shared secret for `client_secret_basic`.
|
||||
# - `assertion_provider` - Callable invoked as `call(audience:, resource:)`, returning the ID-JAG assertion to
|
||||
# present. `audience` is the authorization server's issuer identifier and `resource` is the canonical MCP server URL;
|
||||
# pass both through to `IDJAGTokenExchange.request` when exchanging an IdP ID token.
|
||||
#
|
||||
# Optional keyword arguments:
|
||||
#
|
||||
# - `scope` - String of space-separated scopes to request when the server's `WWW-Authenticate` and
|
||||
# the Protected Resource Metadata do not specify one.
|
||||
# - `storage` - Object responding to `tokens`, `save_tokens(tokens)`, `client_information`, and `save_client_information(info)`.
|
||||
# Defaults to an `InMemoryStorage`.
|
||||
#
|
||||
# https://github.com/modelcontextprotocol/modelcontextprotocol/issues/990
|
||||
class CrossAppAccessProvider
|
||||
include StorageBackedProvider
|
||||
|
||||
# Raised when the provider is constructed without the pieces the `jwt-bearer` grant needs.
|
||||
class InvalidConfigurationError < ArgumentError; end
|
||||
|
||||
attr_reader :scope, :storage
|
||||
|
||||
def initialize(client_id:, client_secret:, assertion_provider:, scope: nil, storage: nil)
|
||||
if blank?(client_id)
|
||||
raise InvalidConfigurationError, "client_id is required for the jwt-bearer grant."
|
||||
end
|
||||
|
||||
if blank?(client_secret)
|
||||
raise InvalidConfigurationError, "client_secret is required: SEP-990 authenticates the jwt-bearer grant with client_secret_basic."
|
||||
end
|
||||
|
||||
unless assertion_provider.respond_to?(:call)
|
||||
raise InvalidConfigurationError, "assertion_provider must be callable as `call(audience:, resource:)` and return the ID-JAG assertion."
|
||||
end
|
||||
|
||||
@assertion_provider = assertion_provider
|
||||
@scope = scope
|
||||
@storage = storage || InMemoryStorage.new
|
||||
@storage.save_client_information(
|
||||
"client_id" => client_id,
|
||||
"client_secret" => client_secret,
|
||||
"token_endpoint_auth_method" => "client_secret_basic",
|
||||
)
|
||||
end
|
||||
|
||||
# See `Provider#authorization_flow`.
|
||||
def authorization_flow
|
||||
:jwt_bearer
|
||||
end
|
||||
|
||||
# Returns the ID-JAG assertion to present at the MCP authorization server. Called by `Flow#run_jwt_bearer!` with the audience
|
||||
# and resource resolved during discovery.
|
||||
def jwt_bearer_assertion(audience:, resource:)
|
||||
@assertion_provider.call(audience: audience, resource: resource)
|
||||
end
|
||||
|
||||
private
|
||||
|
||||
def blank?(value)
|
||||
value.nil? || (value.is_a?(String) && value.strip.empty?)
|
||||
end
|
||||
end
|
||||
end
|
||||
end
|
||||
end
|
||||
|
|
@ -51,8 +51,11 @@ module MCP
|
|||
|
||||
as_metadata = authorization_server_metadata(authorization_server: authorization_server, legacy: prm.nil?)
|
||||
|
||||
if provider_authorization_flow == :client_credentials
|
||||
case provider_authorization_flow
|
||||
when :client_credentials
|
||||
return run_client_credentials!(as_metadata: as_metadata, prm: prm, resource: resource, scope: scope)
|
||||
when :jwt_bearer
|
||||
return run_jwt_bearer!(as_metadata: as_metadata, prm: prm, resource: resource, scope: scope)
|
||||
end
|
||||
|
||||
ensure_pkce_supported!(as_metadata)
|
||||
|
|
@ -154,6 +157,36 @@ module MCP
|
|||
"refusing to send them to the current authorization server (SEP-2352)."
|
||||
end
|
||||
|
||||
# Runs the RFC 7523 `jwt-bearer` grant for the SEP-990 Enterprise Managed Authorization extension:
|
||||
# the provider supplies an ID-JAG assertion (typically obtained from an enterprise IdP via `IDJAGTokenExchange`),
|
||||
# which is presented at the token endpoint with `client_secret_basic` authentication. Shares the same discovery
|
||||
# and security checks as `run!`; like `client_credentials`, there is no PKCE, redirect, or authorization request.
|
||||
# The assertion's audience is the issuer identifier that `ensure_issuer_matches!` validated.
|
||||
# https://github.com/modelcontextprotocol/modelcontextprotocol/issues/990
|
||||
def run_jwt_bearer!(as_metadata:, prm:, resource:, scope:)
|
||||
client_info = @provider.client_information
|
||||
unless client_info.is_a?(Hash) && client_info_required_value(client_info, "client_id")
|
||||
raise AuthorizationError, "Cannot run the jwt-bearer grant: the provider has no stored `client_id`."
|
||||
end
|
||||
|
||||
assertion = @provider.jwt_bearer_assertion(audience: as_metadata["issuer"], resource: resource)
|
||||
if assertion.nil? || assertion.to_s.empty?
|
||||
raise AuthorizationError, "The provider's assertion_provider returned no ID-JAG assertion."
|
||||
end
|
||||
|
||||
form = {
|
||||
"grant_type" => "urn:ietf:params:oauth:grant-type:jwt-bearer",
|
||||
"assertion" => assertion,
|
||||
}
|
||||
effective_scope = resolve_scope(scope: scope, prm: prm)
|
||||
form["scope"] = effective_scope if effective_scope
|
||||
form["resource"] = resource if resource
|
||||
|
||||
tokens = post_to_token_endpoint(as_metadata: as_metadata, client_info: client_info, form: form)
|
||||
@provider.save_tokens(tokens)
|
||||
:authorized
|
||||
end
|
||||
|
||||
# Exchanges the saved `refresh_token` for a fresh access token (RFC 6749 Section 6).
|
||||
# Re-discovers PRM and AS metadata so we always pick up a moved token endpoint, and re-runs the audience / issuer / security
|
||||
# checks before talking to it.
|
||||
|
|
|
|||
101
lib/mcp/client/oauth/id_jag_token_exchange.rb
Normal file
101
lib/mcp/client/oauth/id_jag_token_exchange.rb
Normal file
|
|
@ -0,0 +1,101 @@
|
|||
# frozen_string_literal: true
|
||||
|
||||
require "json"
|
||||
require "uri"
|
||||
|
||||
module MCP
|
||||
class Client
|
||||
module OAuth
|
||||
# RFC 8693 token exchange against an enterprise identity provider, turning an IdP-issued ID token into
|
||||
# an Identity Assertion Authorization Grant (ID-JAG) per the MCP Enterprise Managed Authorization extension (SEP-990).
|
||||
# The returned ID-JAG is an opaque assertion the client then presents to the MCP authorization server with
|
||||
# the RFC 7523 `jwt-bearer` grant (see `CrossAppAccessProvider`).
|
||||
# Mirrors `requestJwtAuthorizationGrant` in the TypeScript SDK.
|
||||
#
|
||||
# - https://github.com/modelcontextprotocol/modelcontextprotocol/issues/990
|
||||
# - https://www.rfc-editor.org/rfc/rfc8693
|
||||
module IDJAGTokenExchange
|
||||
# Raised when the identity provider's token exchange fails or returns something other than an ID-JAG.
|
||||
class ExchangeError < StandardError; end
|
||||
|
||||
GRANT_TYPE = "urn:ietf:params:oauth:grant-type:token-exchange"
|
||||
ID_TOKEN_TYPE = "urn:ietf:params:oauth:token-type:id_token"
|
||||
ID_JAG_TOKEN_TYPE = "urn:ietf:params:oauth:token-type:id-jag"
|
||||
|
||||
class << self
|
||||
# Exchanges `id_token` for an ID-JAG at the IdP's token endpoint and returns the assertion string.
|
||||
#
|
||||
# @param token_endpoint [String] The identity provider's token endpoint.
|
||||
# @param id_token [String] The IdP-issued ID token (the subject token).
|
||||
# @param client_id [String] The client's identifier at the IdP.
|
||||
# @param audience [String] The MCP authorization server's issuer identifier.
|
||||
# @param resource [String] The canonical MCP server URL (RFC 8707).
|
||||
# @param http_client [Object, nil] Faraday-compatible client; built lazily by default.
|
||||
def request(token_endpoint:, id_token:, client_id:, audience:, resource:, http_client: nil)
|
||||
http_client ||= default_http_client
|
||||
|
||||
response = begin
|
||||
http_client.post(token_endpoint) do |req|
|
||||
req.headers["Content-Type"] = "application/x-www-form-urlencoded"
|
||||
req.headers["Accept"] = "application/json"
|
||||
req.body = URI.encode_www_form(
|
||||
"grant_type" => GRANT_TYPE,
|
||||
"subject_token" => id_token,
|
||||
"subject_token_type" => ID_TOKEN_TYPE,
|
||||
"requested_token_type" => ID_JAG_TOKEN_TYPE,
|
||||
"audience" => audience,
|
||||
"resource" => resource,
|
||||
"client_id" => client_id,
|
||||
)
|
||||
end
|
||||
rescue Faraday::Error => e
|
||||
raise ExchangeError, "Token exchange request to #{token_endpoint} failed: #{e.class}: #{e.message}."
|
||||
end
|
||||
|
||||
if response.status < 200 || response.status >= 300
|
||||
raise ExchangeError, "Identity provider token exchange returned status #{response.status}."
|
||||
end
|
||||
|
||||
parse_id_jag(response)
|
||||
end
|
||||
|
||||
private
|
||||
|
||||
def parse_id_jag(response)
|
||||
body = response.body.is_a?(String) ? response.body : response.body.to_s
|
||||
parsed = begin
|
||||
JSON.parse(body)
|
||||
rescue JSON::ParserError => e
|
||||
raise ExchangeError, "Failed to parse token exchange response: #{e.message}."
|
||||
end
|
||||
|
||||
unless parsed.is_a?(Hash)
|
||||
raise ExchangeError, "Token exchange response is not a JSON object (got #{parsed.class})."
|
||||
end
|
||||
|
||||
issued_token_type = parsed["issued_token_type"]
|
||||
unless issued_token_type == ID_JAG_TOKEN_TYPE
|
||||
raise ExchangeError,
|
||||
"Token exchange did not issue an ID-JAG " \
|
||||
"(expected issued_token_type #{ID_JAG_TOKEN_TYPE.inspect}, got #{issued_token_type.inspect})."
|
||||
end
|
||||
|
||||
assertion = parsed["access_token"]
|
||||
if assertion.nil? || assertion.to_s.empty?
|
||||
raise ExchangeError, "Token exchange response is missing `access_token`."
|
||||
end
|
||||
|
||||
assertion
|
||||
end
|
||||
|
||||
def default_http_client
|
||||
require "faraday"
|
||||
Faraday.new do |faraday|
|
||||
faraday.headers["Accept"] = "application/json"
|
||||
end
|
||||
end
|
||||
end
|
||||
end
|
||||
end
|
||||
end
|
||||
end
|
||||
Loading…
Reference in a new issue