modelcontextprotocol/ruby-sdk
Watch
1
0
Fork
You've already forked ruby-sdk
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge pull request #454 from koic/cross_app_access

Browse source 
Support SEP-990 Cross-App Access via ID-JAG and the jwt-bearer Grant
This commit is contained in:
Koichi ITO 2026-07-16 00:58:08 +09:00 • committed by GitHub
commit 5533a6df92
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
10 changed files with 529 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

37
README.md
View file

@ -2505,6 +2505,43 @@ Keyword arguments:
- `token_endpoint_auth_method`: `"client_secret_basic"` (default) or `"client_secret_post"`. `"none"` is rejected with `ClientCredentialsProvider::InvalidCredentialsError`.
- `scope`, `storage`: Optional, same meaning as on `Provider`.
##### Cross-App Access (JWT Bearer) Grant
For enterprise MCP deployments where an identity provider (IdP) governs authorization (SEP-990), use `MCP::Client::OAuth::CrossAppAccessProvider` instead of `Provider`.
The client exchanges an IdP-issued ID token for an Identity Assertion Authorization Grant (ID-JAG) at the IdP via RFC 8693 token exchange, then presents the ID-JAG
to the MCP authorization server with the RFC 7523 `jwt-bearer` grant, authenticating with `client_secret_basic`. There is no authorization request, PKCE, DCR, or `offline_access`.
Mirrors `CrossAppAccessProvider` and `requestJwtAuthorizationGrant` in the TypeScript SDK.
`MCP::Client::OAuth::IDJAGTokenExchange.request` performs the RFC 8693 exchange at the IdP token endpoint. Wrap it in a callable so the same provider can plug into
an enterprise secret store or a test double without changing the transport wiring.
```ruby
provider = MCP::Client::OAuth::CrossAppAccessProvider.new(
client_id: "my-mcp-client",
client_secret: ENV.fetch("MCP_CLIENT_SECRET"),
assertion_provider: ->(audience:, resource:) {
MCP::Client::OAuth::IDJAGTokenExchange.request(
token_endpoint: "https://idp.example.com/token",
id_token: ENV.fetch("IDP_ID_TOKEN"),
client_id: "my-idp-client",
audience: audience,
resource: resource,
)
},
# scope: "mcp:read mcp:write" (optional; used when neither WWW-Authenticate nor PRM specify one)
)
transport = MCP::Client::HTTP.new(url: "https://api.example.com/mcp", oauth: provider)
```
Keyword arguments:
- `client_id`, `client_secret`: Required. The `jwt-bearer` grant authenticates with `client_secret_basic` at the MCP authorization server.
- `assertion_provider`: Required. Callable invoked as `call(audience:, resource:)` and returning the ID-JAG assertion.
`audience` is the MCP authorization server's validated issuer identifier; `resource` is the canonical MCP server URL (RFC 8707).
Passing both through to `IDJAGTokenExchange.request` covers the common case.
- `scope`, `storage`: Optional, same meaning as on `Provider`.
##### Communication Security
When `oauth:` is set, the MCP transport URL and every OAuth-facing URL (PRM, Authorization Server metadata, `authorization_endpoint`, `token_endpoint`, `registration_endpoint`,

25
conformance/client.rb
View file

@ -87,6 +87,27 @@ def build_client_credentials_provider(context)
end
end
# Builds a SEP-990 Cross-App Access provider: the harness injects an IdP ID token plus the IdP token endpoint
# via context; the assertion provider exchanges them for an ID-JAG (RFC 8693), which the flow then presents to
# the MCP authorization server with the jwt-bearer grant.
def build_cross_app_access_provider(context)
assertion_provider = ->(audience:, resource:) do
MCP::Client::OAuth::IDJAGTokenExchange.request(
token_endpoint: context["idp_token_endpoint"],
id_token: context["idp_id_token"],
client_id: context["idp_client_id"],
audience: audience,
resource: resource,
)
end
MCP::Client::OAuth::CrossAppAccessProvider.new(
client_id: context["client_id"],
client_secret: context["client_secret"],
assertion_provider: assertion_provider,
)
end
# Builds an OAuth provider that drives the authorization code + PKCE + DCR flow
# non-interactively against the conformance test's auth server. The conformance
# `/authorize` endpoint redirects synchronously to `redirect_uri` with
@ -129,7 +150,9 @@ def build_oauth_provider(context, scenario:)
end
def build_provider_for(scenario, context)
if scenario.start_with?("auth/client-credentials")
if context["idp_id_token"]
build_cross_app_access_provider(context)
elsif scenario.start_with?("auth/client-credentials")
build_client_credentials_provider(context)
else
build_oauth_provider(context, scenario: scenario)

4
conformance/expected_failures.yml
View file

@ -1,4 +1,2 @@
server: []
client:
# TODO: Remaining OAuth/auth scenarios not yet implemented in Ruby client.
- auth/cross-app-access-complete-flow
client: []

5
lib/mcp/client/oauth.rb
View file

@ -8,12 +8,15 @@ require_relative "oauth/storage_backed_provider"
require_relative "oauth/jwt_client_assertion"
require_relative "oauth/provider"
require_relative "oauth/client_credentials_provider"
require_relative "oauth/id_jag_token_exchange"
require_relative "oauth/cross_app_access_provider"
module MCP
class Client
# OAuth client support for the MCP Authorization spec (PRM discovery,
# Authorization Server metadata discovery, Dynamic Client Registration,
# OAuth 2.1 Authorization Code + PKCE, and the client_credentials grant).
# OAuth 2.1 Authorization Code + PKCE, the client_credentials grant,
# and the SEP-990 Enterprise Managed Authorization jwt-bearer grant).
# https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization
module OAuth
end

80
lib/mcp/client/oauth/cross_app_access_provider.rb Normal file
View 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

35
lib/mcp/client/oauth/flow.rb
View file

@ -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
View 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

94
test/mcp/client/oauth/cross_app_access_provider_test.rb Normal file
View file

@ -0,0 +1,94 @@
# frozen_string_literal: true
require "test_helper"
require "mcp/client/oauth"
module MCP
class Client
module OAuth
class CrossAppAccessProviderTest < Minitest::Test
def build_provider(assertion_provider: ->(**) { "id-jag" })
CrossAppAccessProvider.new(
client_id: "xaa-client",
client_secret: "xaa-secret",
assertion_provider: assertion_provider,
)
end
def test_initialize_stores_credentials_with_basic_auth_method
provider = build_provider
info = provider.client_information
assert_equal("xaa-client", info["client_id"])
assert_equal("xaa-secret", info["client_secret"])
assert_equal("client_secret_basic", info["token_endpoint_auth_method"])
end
def test_authorization_flow_is_jwt_bearer
assert_equal(:jwt_bearer, build_provider.authorization_flow)
end
def test_jwt_bearer_assertion_passes_audience_and_resource_through
received = nil
provider = build_provider(
assertion_provider: ->(audience:, resource:) {
received = { audience: audience, resource: resource }
"id-jag-assertion"
},
)
assertion = provider.jwt_bearer_assertion(
audience: "https://auth.example.com",
resource: "https://srv.example.com/mcp",
)
assert_equal("id-jag-assertion", assertion)
assert_equal(
{ audience: "https://auth.example.com", resource: "https://srv.example.com/mcp" },
received,
)
end
def test_initialize_rejects_missing_client_id
assert_raises(CrossAppAccessProvider::InvalidConfigurationError) do
CrossAppAccessProvider.new(
client_id: " ",
client_secret: "xaa-secret",
assertion_provider: ->(**) { "id-jag" },
)
end
end
def test_initialize_rejects_missing_client_secret
# SEP-990 authenticates the jwt-bearer grant with client_secret_basic.
assert_raises(CrossAppAccessProvider::InvalidConfigurationError) do
CrossAppAccessProvider.new(
client_id: "xaa-client",
client_secret: nil,
assertion_provider: ->(**) { "id-jag" },
)
end
end
def test_initialize_rejects_non_callable_assertion_provider
assert_raises(CrossAppAccessProvider::InvalidConfigurationError) do
CrossAppAccessProvider.new(
client_id: "xaa-client",
client_secret: "xaa-secret",
assertion_provider: "not callable",
)
end
end
def test_token_helpers_delegate_to_storage
provider = build_provider
provider.save_tokens("access_token" => "xaa-token")
assert_equal("xaa-token", provider.access_token)
provider.clear_tokens!
assert_nil(provider.tokens)
end
end
end
end
end

47
test/mcp/client/oauth/flow_test.rb
View file

@ -253,6 +253,53 @@ module MCP
end
end
def test_run_uses_jwt_bearer_grant_for_cross_app_access_provider
# SEP-990: the ID-JAG assertion (obtained out of band, typically via IdP token exchange) is presented at
# the token endpoint with client_secret_basic; no PKCE, redirect, or DCR is involved.
received = nil
provider = CrossAppAccessProvider.new(
client_id: "xaa-client",
client_secret: "xaa-secret",
assertion_provider: ->(audience:, resource:) {
received = { audience: audience, resource: resource }
"id-jag-assertion"
},
)
result = Flow.new(provider: provider).run!(server_url: @server_url, resource_metadata_url: @prm_url)
assert_equal(:authorized, result)
assert_equal("test-token-from-flow", provider.access_token)
# The assertion audience is the validated AS issuer; the resource is the canonical MCP server URL.
assert_equal({ audience: @auth_base, resource: "https://srv.example.com/mcp" }, received)
assert_not_requested(:post, "#{@auth_base}/register")
assert_requested(:post, "#{@auth_base}/token") do |req|
form = URI.decode_www_form(req.body).to_h
expected_basic = "Basic " + Base64.strict_encode64("xaa-client:xaa-secret")
form["grant_type"] == "urn:ietf:params:oauth:grant-type:jwt-bearer" &&
form["assertion"] == "id-jag-assertion" &&
form["resource"] == "https://srv.example.com/mcp" &&
!form.key?("code") &&
!form.key?("code_verifier") &&
req.headers["Authorization"] == expected_basic
end
end
def test_run_jwt_bearer_raises_when_assertion_provider_returns_nothing
provider = CrossAppAccessProvider.new(
client_id: "xaa-client",
client_secret: "xaa-secret",
assertion_provider: ->(audience:, resource:) {},
)
error = assert_raises(Flow::AuthorizationError) do
Flow.new(provider: provider).run!(server_url: @server_url, resource_metadata_url: @prm_url)
end
assert_match(/returned no ID-JAG/, error.message)
assert_not_requested(:post, "#{@auth_base}/token")
end
def test_run_uses_authorization_code_grant_for_default_provider
# A standard `Provider` declares `authorization_flow == :authorization_code`,
# so `Flow` runs the interactive grant regardless of what `client_metadata[:grant_types]` happens to list.

107
test/mcp/client/oauth/id_jag_token_exchange_test.rb Normal file
View file

@ -0,0 +1,107 @@
# frozen_string_literal: true
require "test_helper"
require "webmock/minitest"
require "faraday"
require "mcp/client/oauth"
module MCP
class Client
module OAuth
class IDJAGTokenExchangeTest < Minitest::Test
def setup
WebMock.enable!
@token_endpoint = "https://idp.example.com/token"
end
def teardown
WebMock.reset!
end
def request_exchange
IDJAGTokenExchange.request(
token_endpoint: @token_endpoint,
id_token: "idp-id-token",
client_id: "idp-client",
audience: "https://auth.example.com",
resource: "https://srv.example.com/mcp",
)
end
def test_request_sends_rfc8693_token_exchange_parameters
stub_request(:post, @token_endpoint).to_return(
status: 200,
headers: { "Content-Type" => "application/json" },
body: JSON.generate(
access_token: "id-jag-assertion",
issued_token_type: "urn:ietf:params:oauth:token-type:id-jag",
token_type: "N_A",
),
)
assertion = request_exchange
assert_equal("id-jag-assertion", assertion)
assert_requested(:post, @token_endpoint) do |req|
form = URI.decode_www_form(req.body).to_h
form["grant_type"] == "urn:ietf:params:oauth:grant-type:token-exchange" &&
form["subject_token"] == "idp-id-token" &&
form["subject_token_type"] == "urn:ietf:params:oauth:token-type:id_token" &&
form["requested_token_type"] == "urn:ietf:params:oauth:token-type:id-jag" &&
form["audience"] == "https://auth.example.com" &&
form["resource"] == "https://srv.example.com/mcp" &&
form["client_id"] == "idp-client"
end
end
def test_request_rejects_response_without_id_jag_token_type
# A plain access token is not an ID-JAG; presenting it as a
# jwt-bearer assertion would fail confusingly downstream.
stub_request(:post, @token_endpoint).to_return(
status: 200,
headers: { "Content-Type" => "application/json" },
body: JSON.generate(
access_token: "ordinary-token",
issued_token_type: "urn:ietf:params:oauth:token-type:access_token",
),
)
error = assert_raises(IDJAGTokenExchange::ExchangeError) { request_exchange }
assert_match(/did not issue an ID-JAG/, error.message)
end
def test_request_rejects_missing_access_token
stub_request(:post, @token_endpoint).to_return(
status: 200,
headers: { "Content-Type" => "application/json" },
body: JSON.generate(issued_token_type: "urn:ietf:params:oauth:token-type:id-jag"),
)
error = assert_raises(IDJAGTokenExchange::ExchangeError) { request_exchange }
assert_match(/missing `access_token`/, error.message)
end
def test_request_raises_on_non_2xx_response
stub_request(:post, @token_endpoint).to_return(status: 400, body: JSON.generate(error: "invalid_grant"))
error = assert_raises(IDJAGTokenExchange::ExchangeError) { request_exchange }
assert_match(/status 400/, error.message)
end
def test_request_raises_on_unparseable_response
stub_request(:post, @token_endpoint).to_return(status: 200, body: "not json")
error = assert_raises(IDJAGTokenExchange::ExchangeError) { request_exchange }
assert_match(/Failed to parse/, error.message)
end
def test_request_raises_on_non_object_json_response
stub_request(:post, @token_endpoint).to_return(status: 200, body: "[]")
error = assert_raises(IDJAGTokenExchange::ExchangeError) { request_exchange }
assert_match(/not a JSON object/, error.message)
end
end
end
end
end