Support OAuth client_credentials grant in OAuth client
## Motivation and Context The MCP authorization specification and SEP-1046 allow confidential clients to obtain tokens through the OAuth 2.1 `client_credentials` grant: a machine-to-machine flow with no user, no browser redirect, and no authorization code. The Ruby SDK previously supported only the interactive authorization-code flow, so it could not authenticate against a server that requires `client_credentials`. This makes the `auth/client-credentials-basic` conformance scenario pass and is removed from the expected failures list. Following the TypeScript SDK (`ClientCredentialsProvider`) and the Python SDK (`ClientCredentialsOAuthProvider`), the grant gets its own provider class rather than overloading the authorization-code provider. The change adds: - `MCP::Client::OAuth::ClientCredentialsProvider`, a dedicated provider for the grant. `client_id` and `client_secret` are mandatory (the grant is for confidential clients), `token_endpoint_auth_method` is `client_secret_basic` (default) or `client_secret_post` -- `none` is rejected because an unauthenticated `client_credentials` request is meaningless. It has no redirect arguments, so a credentials-only client never supplies the redirect URI / handlers that grant has no use for. - `MCP::Client::OAuth::StorageBackedProvider`, an internal module that shares the token / client-information persistence between the two provider classes so `Flow` can treat any provider uniformly. - `Provider#authorization_flow` (`:authorization_code`) and `ClientCredentialsProvider#authorization_flow` (`:client_credentials`). `Flow#run!` dispatches on this rather than inspecting `client_metadata[:grant_types]`, which is protocol metadata for the authorization server, not an SDK control signal. - `run_client_credentials!` shares the same PRM / AS metadata discovery and Communication Security checks as the interactive flow, then exchanges `grant_type=client_credentials` at the token endpoint via the existing `post_to_token_endpoint` (which already applies `client_secret_basic`). There is no PKCE, redirect, or `offline_access` augmentation, because the grant does not issue a refresh token (OAuth 2.1 Section 4.3.3). - `conformance/client.rb` builds a `ClientCredentialsProvider` for the `auth/client-credentials-*` scenarios, reusing the harness-injected `client_id` / `client_secret`. ## How Has This Been Tested? New `ClientCredentialsProvider` tests cover: credentials are stored as client information; `authorization_flow` is `:client_credentials`; `client_secret_post` is accepted; missing `client_id` / `client_secret` and `token_endpoint_auth_method: "none"` are rejected; and the token helpers delegate to storage. New `Flow` tests cover: a `client_credentials` provider exchanges `grant_type=client_credentials` with HTTP Basic auth, saves the token, and never contacts the authorization or registration endpoint; the requested scope is taken from PRM `scopes_supported`; and a standard `Provider` runs the authorization-code grant regardless of what its `client_metadata[:grant_types]` lists. A `Provider` test asserts `authorization_flow` is `:authorization_code`. Conformance: `auth/client-credentials-basic` now passes 7/7 with no failures. ## Breaking Changes None. `ClientCredentialsProvider` is a new class; the existing `Provider` keeps its required `redirect_uri` / `redirect_handler` / `callback_handler` arguments and its behaviour is unchanged. Existing interactive clients are unaffected.
This commit is contained in:
Koichi ITO
parent
9193745291
commit
2289db84f8
5 changed files with 445 additions and 47 deletions
|
|
@ -4,13 +4,15 @@ require_relative "oauth/discovery"
|
|||
require_relative "oauth/flow"
|
||||
require_relative "oauth/in_memory_storage"
|
||||
require_relative "oauth/pkce"
|
||||
require_relative "oauth/storage_backed_provider"
|
||||
require_relative "oauth/provider"
|
||||
require_relative "oauth/client_credentials_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).
|
||||
# OAuth 2.1 Authorization Code + PKCE, and the client_credentials grant).
|
||||
# https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization
|
||||
module OAuth
|
||||
end
|
||||
|
|
|
|||
89
lib/mcp/client/oauth/client_credentials_provider.rb
Normal file
89
lib/mcp/client/oauth/client_credentials_provider.rb
Normal file
|
|
@ -0,0 +1,89 @@
|
|||
# frozen_string_literal: true
|
||||
|
||||
module MCP
|
||||
class Client
|
||||
module OAuth
|
||||
# OAuth client configuration for the OAuth 2.1 `client_credentials` grant
|
||||
# (machine-to-machine, no user and no browser redirect). Handed to
|
||||
# `MCP::Client::HTTP` via the `oauth:` keyword, the same as `Provider`.
|
||||
# The interactive Authorization Code flow lives in `Provider`;
|
||||
# this class exists so a credentials-only client never has to supply
|
||||
# the redirect arguments that grant has no use for, mirroring the dedicated
|
||||
# `ClientCredentialsProvider` in the TypeScript SDK and
|
||||
# `ClientCredentialsOAuthProvider` in the Python SDK.
|
||||
#
|
||||
# Required keyword arguments:
|
||||
#
|
||||
# - `client_id` - String identifying the pre-registered confidential client.
|
||||
# - `client_secret` - String shared secret. The `client_credentials` grant
|
||||
# is for confidential clients, so a credential is mandatory.
|
||||
#
|
||||
# Optional keyword arguments:
|
||||
#
|
||||
# - `token_endpoint_auth_method` - `"client_secret_basic"` (default) or
|
||||
# `"client_secret_post"`. `"none"` is rejected: an unauthenticated
|
||||
# `client_credentials` request is meaningless.
|
||||
# - `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`. The `client_id` / `client_secret` are written
|
||||
# into it so the token exchange reads them through the same path as
|
||||
# a pre-registered authorization-code client.
|
||||
class ClientCredentialsProvider
|
||||
include StorageBackedProvider
|
||||
|
||||
# Raised when the credentials required for the `client_credentials` grant are
|
||||
# missing or the requested client authentication method cannot carry them.
|
||||
class InvalidCredentialsError < ArgumentError; end
|
||||
|
||||
SUPPORTED_AUTH_METHODS = ["client_secret_basic", "client_secret_post"].freeze
|
||||
|
||||
attr_reader :scope, :storage
|
||||
|
||||
def initialize(
|
||||
client_id:,
|
||||
client_secret:,
|
||||
token_endpoint_auth_method: "client_secret_basic",
|
||||
scope: nil,
|
||||
storage: nil
|
||||
)
|
||||
if blank?(client_id)
|
||||
raise InvalidCredentialsError, "client_id is required for the client_credentials grant."
|
||||
end
|
||||
|
||||
unless SUPPORTED_AUTH_METHODS.include?(token_endpoint_auth_method)
|
||||
raise InvalidCredentialsError,
|
||||
"token_endpoint_auth_method must be one of #{SUPPORTED_AUTH_METHODS.inspect} for the " \
|
||||
"client_credentials grant (got #{token_endpoint_auth_method.inspect}); an unauthenticated " \
|
||||
"client_credentials request is not allowed."
|
||||
end
|
||||
|
||||
if blank?(client_secret)
|
||||
raise InvalidCredentialsError,
|
||||
"client_secret is required for the client_credentials grant with #{token_endpoint_auth_method}."
|
||||
end
|
||||
|
||||
@scope = scope
|
||||
@storage = storage || InMemoryStorage.new
|
||||
@storage.save_client_information(
|
||||
"client_id" => client_id,
|
||||
"client_secret" => client_secret,
|
||||
"token_endpoint_auth_method" => token_endpoint_auth_method,
|
||||
)
|
||||
end
|
||||
|
||||
# See `Provider#authorization_flow`.
|
||||
def authorization_flow
|
||||
:client_credentials
|
||||
end
|
||||
|
||||
private
|
||||
|
||||
def blank?(value)
|
||||
value.nil? || (value.is_a?(String) && value.strip.empty?)
|
||||
end
|
||||
end
|
||||
end
|
||||
end
|
||||
end
|
||||
|
|
@ -54,6 +54,11 @@ module MCP
|
|||
as_metadata = fetch_authorization_server_metadata(issuer_url: authorization_server)
|
||||
ensure_issuer_matches!(expected: authorization_server, returned: as_metadata["issuer"])
|
||||
ensure_secure_endpoints!(as_metadata)
|
||||
|
||||
if provider_authorization_flow == :client_credentials
|
||||
return run_client_credentials!(as_metadata: as_metadata, prm: prm, resource: resource, scope: scope)
|
||||
end
|
||||
|
||||
ensure_pkce_supported!(as_metadata)
|
||||
|
||||
client_info = ensure_client_registered(as_metadata: as_metadata)
|
||||
|
|
@ -92,14 +97,46 @@ module MCP
|
|||
: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.
|
||||
# Runs the OAuth 2.1 `client_credentials` grant (machine-to-machine, no user interaction) and persists
|
||||
# the resulting token. Shares the same discovery and security checks as `run!`; the only difference is
|
||||
# the grant exchanged at the token endpoint. There is no PKCE, redirect, or authorization request,
|
||||
# and no `offline_access` augmentation because the grant does not issue a refresh token (OAuth 2.1 Section 4.3.3).
|
||||
# The pre-registered `client_id` / `client_secret` come from the provider's stored `client_information`.
|
||||
# https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization
|
||||
def run_client_credentials!(as_metadata:, prm:, resource:, scope:)
|
||||
client_info = client_credentials_client_info
|
||||
|
||||
form = { "grant_type" => "client_credentials" }
|
||||
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
|
||||
|
||||
# Reads the pre-registered credentials for the `client_credentials` grant directly from the provider's stored
|
||||
# `client_information`, rather than going through `ensure_client_registered` (which targets the authorization-code
|
||||
# flow and reaches for `Provider`-only methods like `client_metadata` and `client_id_metadata_document_url`).
|
||||
# The grant is for confidential clients, so a missing `client_id` is a clean configuration error, not a fallback
|
||||
# to dynamic registration.
|
||||
def client_credentials_client_info
|
||||
info = @provider.client_information
|
||||
unless info.is_a?(Hash) && client_info_required_value(info, "client_id")
|
||||
raise AuthorizationError,
|
||||
"Cannot run the client_credentials grant: the provider has no stored `client_id`."
|
||||
end
|
||||
|
||||
info
|
||||
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.
|
||||
#
|
||||
# Returns `:refreshed` on success. Raises `AuthorizationError` when
|
||||
# the provider has no refresh token, no client information, or when
|
||||
# the token endpoint refuses the refresh request.
|
||||
# Returns `:refreshed` on success. Raises `AuthorizationError` when the provider has no refresh token, no client information,
|
||||
# or when the token endpoint refuses the refresh request.
|
||||
# https://www.rfc-editor.org/rfc/rfc6749#section-6
|
||||
def refresh!(server_url:, resource_metadata_url: nil)
|
||||
refresh_token = read_token("refresh_token")
|
||||
|
|
@ -110,8 +147,7 @@ module MCP
|
|||
|
||||
# A CIMD-configured provider stores no `client_information` on purpose
|
||||
# (the CIMD URL is re-resolved against the live AS metadata on every flow).
|
||||
# Allow refresh to proceed in that case so the `refresh_token` obtained via
|
||||
# the CIMD flow remains usable.
|
||||
# Allow refresh to proceed in that case so the `refresh_token` obtained via the CIMD flow remains usable.
|
||||
have_cimd_url = !@provider.client_id_metadata_document_url.nil?
|
||||
|
||||
unless have_stored_client_info || have_cimd_url
|
||||
|
|
@ -484,6 +520,18 @@ module MCP
|
|||
Array(grant_types).include?("refresh_token")
|
||||
end
|
||||
|
||||
# The OAuth flow the provider drives. Dispatching on the provider's
|
||||
# declared flow keeps `Flow` from second-guessing intent by parsing
|
||||
# `client_metadata[:grant_types]` (which is protocol metadata for the
|
||||
# authorization server, not an SDK control signal). A provider that
|
||||
# predates this method is treated as the interactive authorization-code
|
||||
# flow it was the only option for.
|
||||
def provider_authorization_flow
|
||||
return :authorization_code unless @provider.respond_to?(:authorization_flow)
|
||||
|
||||
@provider.authorization_flow
|
||||
end
|
||||
|
||||
def build_authorization_url(as_metadata:, client_id:, scope:, state:, code_challenge:, resource:)
|
||||
authorization_endpoint = as_metadata["authorization_endpoint"]
|
||||
unless authorization_endpoint
|
||||
|
|
|
|||
|
|
@ -3,9 +3,11 @@
|
|||
module MCP
|
||||
class Client
|
||||
module OAuth
|
||||
# Pluggable OAuth client configuration handed to `MCP::Client::HTTP` via
|
||||
# the `oauth:` keyword. Inspired by the OAuthClientProvider in the TypeScript SDK
|
||||
# and httpx.Auth-based provider in the Python SDK.
|
||||
# Pluggable OAuth client configuration for the OAuth 2.1 Authorization Code + PKCE flow,
|
||||
# handed to `MCP::Client::HTTP` via the `oauth:` keyword.
|
||||
# Inspired by the OAuthClientProvider in the TypeScript SDK and the httpx.Auth-based provider
|
||||
# in the Python SDK. For the non-interactive machine-to-machine `client_credentials` grant,
|
||||
# use `ClientCredentialsProvider` instead.
|
||||
#
|
||||
# Required keyword arguments:
|
||||
# - `client_metadata` - Hash sent to the authorization server's Dynamic Client
|
||||
|
|
@ -36,6 +38,8 @@ module MCP
|
|||
# DCR `client_metadata` MUST NOT include `client_id`, while the CIMD document MUST include `client_id` set
|
||||
# to the URL, `client_name`, and `redirect_uris` covering `redirect_uri`.
|
||||
class Provider
|
||||
include StorageBackedProvider
|
||||
|
||||
# Raised when `Provider#initialize` is called with a `redirect_uri` that
|
||||
# is neither HTTPS nor a loopback `http://` URL, per the MCP
|
||||
# authorization spec's Communication Security requirement.
|
||||
|
|
@ -102,28 +106,11 @@ module MCP
|
|||
@client_id_metadata_document_url = client_id_metadata_document_url
|
||||
end
|
||||
|
||||
def access_token
|
||||
tokens&.dig("access_token") || tokens&.dig(:access_token)
|
||||
end
|
||||
|
||||
def tokens
|
||||
@storage.tokens
|
||||
end
|
||||
|
||||
def save_tokens(tokens)
|
||||
@storage.save_tokens(tokens)
|
||||
end
|
||||
|
||||
def client_information
|
||||
@storage.client_information
|
||||
end
|
||||
|
||||
def save_client_information(info)
|
||||
@storage.save_client_information(info)
|
||||
end
|
||||
|
||||
def clear_tokens!
|
||||
@storage.save_tokens(nil)
|
||||
# Identifies the OAuth flow this provider drives.
|
||||
# `Flow` dispatches on this rather than inspecting `client_metadata[:grant_types]`,
|
||||
# which is protocol metadata for the authorization server, not an SDK control signal.
|
||||
def authorization_flow
|
||||
:authorization_code
|
||||
end
|
||||
end
|
||||
end
|
||||
|
|
|
|||
43
lib/mcp/client/oauth/storage_backed_provider.rb
Normal file
43
lib/mcp/client/oauth/storage_backed_provider.rb
Normal file
|
|
@ -0,0 +1,43 @@
|
|||
# frozen_string_literal: true
|
||||
|
||||
module MCP
|
||||
class Client
|
||||
module OAuth
|
||||
# Shared token/credential persistence for the OAuth provider classes
|
||||
# (`Provider` for the authorization-code flow and `ClientCredentialsProvider`
|
||||
# for the client_credentials flow). The two grants differ in how they authenticate,
|
||||
# but both read and write the same two pieces of state through a `storage` object:
|
||||
# the token response and the client information. This module supplies that delegation
|
||||
# so the `Flow` orchestrator can treat any provider uniformly.
|
||||
#
|
||||
# Including classes must set `@storage` to an object responding to `tokens`,
|
||||
# `save_tokens(tokens)`, `client_information`, and `save_client_information(info)`
|
||||
# (see `InMemoryStorage`).
|
||||
module StorageBackedProvider
|
||||
def access_token
|
||||
tokens&.dig("access_token") || tokens&.dig(:access_token)
|
||||
end
|
||||
|
||||
def tokens
|
||||
@storage.tokens
|
||||
end
|
||||
|
||||
def save_tokens(tokens)
|
||||
@storage.save_tokens(tokens)
|
||||
end
|
||||
|
||||
def client_information
|
||||
@storage.client_information
|
||||
end
|
||||
|
||||
def save_client_information(info)
|
||||
@storage.save_client_information(info)
|
||||
end
|
||||
|
||||
def clear_tokens!
|
||||
@storage.save_tokens(nil)
|
||||
end
|
||||
end
|
||||
end
|
||||
end
|
||||
end
|
||||
Loading…
Reference in a new issue