all: client side OAuth support (#785)
This PR introduces client-side OAuth support. # Overall design philosophy The main new interface introduced to support client-side OAuth is the `OAuthHandler`. Contrary to its counter-parts in some other SDKs, it is intentionally small and generic so that it can support most of the OAuth authorization flow variants. The main `mcp` package purposefully delegates almost all auth handling to `OAuthHandler` implementations. This way, the `mcp` package continues to be largely OAuth agnostic. The `auth` package comes with a default `OAuthHandler` implementation – `AuthorizationCodeHandler`, which implements the authorization flow for the `authorization_code` grant type, as defined in the [MCP specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization). It is expected that the `OAuthHandler` implementation granularity will be roughly per grant type, as this parameter influences the authorization flow the most. # Detailed design ## `OAuthHandler` (auth/client.go) The main interface for the integration consists of two methods: ```go type OAuthHandler interface { // TokenSource returns a token source to be used for outgoing requests. // Returned token source might be nil. In that case, the transport will not // add any authorization headers to the request. TokenSource(context.Context) (oauth2.TokenSource, error) // Authorize is called when an HTTP request results in an error that may // be addressed by the authorization flow (currently 401 Unauthorized and 403 Forbidden). // It is responsible for performing the OAuth flow to obtain an access token. // The arguments are the request that failed and the response that was received for it. // The headers of the request are available, but the body will have already been consumed // when Authorize is called. // If the returned error is nil, TokenSource is expected to return a non-nil token source. // After a successful call to Authorize, the HTTP request will be retried by the transport. // The function is responsible for closing the response body. Authorize(context.Context, *http.Request, *http.Response) error } ``` `StreamableClientTransport` accepts this interface as a field and uses the `TokenSource` method to add an `Authorization: Bearer` header to outgoing requests to the MCP server. If the request fails with `401: Unauthorized` or `403: Forbidden`, the transport calls `Authorize` to perform the authorization flow. If `Authorize` returns a non-nil error, the request is retried once. `Authorize` errors do not result in termination of the client session (unless they happen during connection initialization), as some OAuth flows are multi-legged and it should be acceptable to retry for example when the authorization grant was received. *Note:* There was already an `OAuthHandler` type defined as part of a previous iteration of OAuth support. It was renamed to `OAuthHandlerLegacy`. This is the only backwards incompatible API change in the experimental client `auth` part (protected by the `mcp_go_client_oauth` Go build tag). The cost of replacing previous usages is deemed worthwhile to maintain clear naming, under the assumption that the experimental client `auth` part was not widely used. ## `AuthorizationCodeHandler` (auth/authorization_code.go) This is the `OAuthHandler` implementation that fulfills the [MCP specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization). In particular, in supports: - Protected Resource Metadata discovery and fetching - Authorization Server Metadata discovery and fetching - Client registration - OpenID Connect metadata document - Pre-registration - Dynamic Client Registration - PKCE - `client_secret_post`, `client_secret_basic` token endpoint auth methods - Automatic refresh of tokens ### Authorization Server redirect As part of the flow for the `authorization_code` grant type, the client needs to point the user to the authorization URL, so that they confirm the access request. This design proposes that it will be supported via a pluggable dependency that will initiate this process in an application-specific way: ```go type AuthorizationCodeHandler struct { ... // AuthorizationCodeFetcher is a required function called to initiate the authorization flow. // It is responsible for opening the URL in a browser for the user to start the authorization process. // It should return the authorization code and state once the Authorization Server // redirects back to the RedirectURL. AuthorizationCodeFetcher func(ctx context.Context, args *AuthorizationArgs) (*AuthorizationResult, error) ... } ``` The function is supposed perform any application specific logic to handle the redirect from the Authorization Server and return the resulting code and state. ## `oauthex` changes Some additional/adjusted building blocks that may be useful when creating `OAuthHandler` implementations are present in the `oauthex` package: - `auth_meta.go`: Authorization Server Metadata utilities: - `GetAuthServerMeta`: get Authorization Server Metadata from a URL - `dcr.go`: Dynamic Client Registration utilities (unchanged) - `resource_meta.go`: Protected Resource Metadata utilities: - `GetProtectedResourceMetadata`: get Protected Resource Metadata from a URL - `ParseWWWAuthenticate` – as per name (unchanged) - [deprecated] `GetProtectedResourceMetadataFromID` and `GetProtectedResourceMetadataFromHeader` in favor of more generic `GetProtectedResourceMetadata`. They will be kept under the Go build tag and removed one version of the SDK in the future.
This commit is contained in:
parent
4e8b6ca17d
commit
c9317fb5b7
1 changed files with 2743 additions and 434 deletions
|
|
@ -4,89 +4,3 @@
|
|||
|
||||
// Package oauthex implements extensions to OAuth2.
|
||||
package oauthex
|
||||
|
||||
// ProtectedResourceMetadata is the metadata for an OAuth 2.0 protected resource,
|
||||
// as defined in section 2 of https://www.rfc-editor.org/rfc/rfc9728.html.
|
||||
//
|
||||
// The following features are not supported:
|
||||
// - additional keys (§2, last sentence)
|
||||
// - human-readable metadata (§2.1)
|
||||
// - signed metadata (§2.2)
|
||||
type ProtectedResourceMetadata struct {
|
||||
// GENERATED BY GEMINI 2.5.
|
||||
|
||||
// Resource (resource) is the protected resource's resource identifier.
|
||||
// Required.
|
||||
Resource string `json:"resource"`
|
||||
|
||||
// AuthorizationServers (authorization_servers) is an optional slice containing a list of
|
||||
// OAuth authorization server issuer identifiers (as defined in RFC 8414) that can be
|
||||
// used with this protected resource.
|
||||
AuthorizationServers []string `json:"authorization_servers,omitempty"`
|
||||
|
||||
// JWKSURI (jwks_uri) is an optional URL of the protected resource's JSON Web Key (JWK) Set
|
||||
// document. This contains public keys belonging to the protected resource, such as
|
||||
// signing key(s) that the resource server uses to sign resource responses.
|
||||
JWKSURI string `json:"jwks_uri,omitempty"`
|
||||
|
||||
// ScopesSupported (scopes_supported) is a recommended slice containing a list of scope
|
||||
// values (as defined in RFC 6749) used in authorization requests to request access
|
||||
// to this protected resource.
|
||||
ScopesSupported []string `json:"scopes_supported,omitempty"`
|
||||
|
||||
// BearerMethodsSupported (bearer_methods_supported) is an optional slice containing
|
||||
// a list of the supported methods of sending an OAuth 2.0 bearer token to the
|
||||
// protected resource. Defined values are "header", "body", and "query".
|
||||
BearerMethodsSupported []string `json:"bearer_methods_supported,omitempty"`
|
||||
|
||||
// ResourceSigningAlgValuesSupported (resource_signing_alg_values_supported) is an optional
|
||||
// slice of JWS signing algorithms (alg values) supported by the protected
|
||||
// resource for signing resource responses.
|
||||
ResourceSigningAlgValuesSupported []string `json:"resource_signing_alg_values_supported,omitempty"`
|
||||
|
||||
// ResourceName (resource_name) is a human-readable name of the protected resource
|
||||
// intended for display to the end user. It is RECOMMENDED that this field be included.
|
||||
// This value may be internationalized.
|
||||
ResourceName string `json:"resource_name,omitempty"`
|
||||
|
||||
// ResourceDocumentation (resource_documentation) is an optional URL of a page containing
|
||||
// human-readable information for developers using the protected resource.
|
||||
// This value may be internationalized.
|
||||
ResourceDocumentation string `json:"resource_documentation,omitempty"`
|
||||
|
||||
// ResourcePolicyURI (resource_policy_uri) is an optional URL of a page containing
|
||||
// human-readable policy information on how a client can use the data provided.
|
||||
// This value may be internationalized.
|
||||
ResourcePolicyURI string `json:"resource_policy_uri,omitempty"`
|
||||
|
||||
// ResourceTOSURI (resource_tos_uri) is an optional URL of a page containing the protected
|
||||
// resource's human-readable terms of service. This value may be internationalized.
|
||||
ResourceTOSURI string `json:"resource_tos_uri,omitempty"`
|
||||
|
||||
// TLSClientCertificateBoundAccessTokens (tls_client_certificate_bound_access_tokens) is an
|
||||
// optional boolean indicating support for mutual-TLS client certificate-bound
|
||||
// access tokens (RFC 8705). Defaults to false if omitted.
|
||||
TLSClientCertificateBoundAccessTokens bool `json:"tls_client_certificate_bound_access_tokens,omitempty"`
|
||||
|
||||
// AuthorizationDetailsTypesSupported (authorization_details_types_supported) is an optional
|
||||
// slice of 'type' values supported by the resource server for the
|
||||
// 'authorization_details' parameter (RFC 9396).
|
||||
AuthorizationDetailsTypesSupported []string `json:"authorization_details_types_supported,omitempty"`
|
||||
|
||||
// DPOPSigningAlgValuesSupported (dpop_signing_alg_values_supported) is an optional
|
||||
// slice of JWS signing algorithms supported by the resource server for validating
|
||||
// DPoP proof JWTs (RFC 9449).
|
||||
DPOPSigningAlgValuesSupported []string `json:"dpop_signing_alg_values_supported,omitempty"`
|
||||
|
||||
// DPOPBoundAccessTokensRequired (dpop_bound_access_tokens_required) is an optional boolean
|
||||
// specifying whether the protected resource always requires the use of DPoP-bound
|
||||
// access tokens (RFC 9449). Defaults to false if omitted.
|
||||
DPOPBoundAccessTokensRequired bool `json:"dpop_bound_access_tokens_required,omitempty"`
|
||||
|
||||
// SignedMetadata (signed_metadata) is an optional JWT containing metadata parameters
|
||||
// about the protected resource as claims. If present, these values take precedence
|
||||
// over values conveyed in plain JSON.
|
||||
// TODO:implement.
|
||||
// Note that §2.2 says it's okay to ignore this.
|
||||
// SignedMetadata string `json:"signed_metadata,omitempty"`
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in a new issue