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

all: client side OAuth support (#785)

Browse source 
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:
Maciej Kisiel 2026-02-27 15:30:13 +01:00 • committed by GitHub
commit c9317fb5b7
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
5 changed files with 2743 additions and 434 deletions
Download patch file Download diff file Expand all files Collapse all files

6
auth/auth.go
View file

@ -25,8 +25,7 @@ type TokenInfo struct {
// session hijacking by ensuring that all requests for a given session
// come from the same user.
UserID string
// TODO: add standard JWT fields
Extra map[string]any
Extra map[string]any
}
// The error that a TokenVerifier should return if the token cannot be verified.
@ -106,6 +105,9 @@ func verify(req *http.Request, verifier TokenVerifier, opts *RequireBearerTokenO
}
return nil, err.Error(), http.StatusInternalServerError
}
if tokenInfo == nil {
return nil, "token validation failed", http.StatusInternalServerError
}
// Check scopes. All must be present.
if opts != nil {

548
auth/authorization_code.go Normal file
View file

@ -0,0 +1,548 @@
// Copyright 2026 The Go MCP SDK Authors. All rights reserved.
// Use of this source code is governed by the license
// that can be found in the LICENSE file.
//go:build mcp_go_client_oauth
package auth
import (
"context"
"crypto/rand"
"errors"
"fmt"
"net/http"
"net/url"
"slices"
"strings"
"github.com/modelcontextprotocol/go-sdk/oauthex"
"golang.org/x/oauth2"
)
// ClientSecretAuthConfig is used to configure client authentication using client_secret.
// Authentication method will be selected based on the authorization server's supported methods,
// according to the following preference order:
// 1. client_secret_post
// 2. client_secret_basic
type ClientSecretAuthConfig struct {
// ClientID is the client ID to be used for client authentication.
ClientID string
// ClientSecret is the client secret to be used for client authentication.
ClientSecret string
}
// ClientIDMetadataDocumentConfig is used to configure the Client ID Metadata Document
// based client registration per
// https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#client-id-metadata-documents.
// See https://client.dev/ for more information.
type ClientIDMetadataDocumentConfig struct {
// URL is the client identifier URL as per
// https://datatracker.ietf.org/doc/html/draft-ietf-oauth-client-id-metadata-document-00#section-3.
URL string
}
// PreregisteredClientConfig is used to configure a pre-registered client per
// https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#preregistration.
// Currently only "client_secret_basic" and "client_secret_post" authentication methods are supported.
type PreregisteredClientConfig struct {
// ClientSecretAuthConfig is the client_secret based configuration to be used for client authentication.
ClientSecretAuthConfig *ClientSecretAuthConfig
}
// DynamicClientRegistrationConfig is used to configure dynamic client registration per
// https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#dynamic-client-registration.
type DynamicClientRegistrationConfig struct {
// Metadata to be used in dynamic client registration request as per
// https://datatracker.ietf.org/doc/html/rfc7591#section-2.
Metadata *oauthex.ClientRegistrationMetadata
}
// AuthorizationResult is the result of an authorization flow.
// It is returned by [AuthorizationCodeHandler].AuthorizationCodeFetcher implementations.
type AuthorizationResult struct {
// Code is the authorization code obtained from the authorization server.
Code string
// State string returned by the authorization server.
State string
}
// AuthorizationArgs is the input to [AuthorizationCodeHandlerConfig].AuthorizationCodeFetcher.
type AuthorizationArgs struct {
// Authorization URL to be opened in a browser for the user to start the authorization process.
URL string
}
// AuthorizationCodeHandlerConfig is the configuration for [AuthorizationCodeHandler].
type AuthorizationCodeHandlerConfig struct {
// Client registration configuration.
// It is attempted in the following order:
// 1. Client ID Metadata Document
// 2. Preregistration
// 3. Dynamic Client Registration
// At least one method must be configured.
ClientIDMetadataDocumentConfig *ClientIDMetadataDocumentConfig
PreregisteredClientConfig *PreregisteredClientConfig
DynamicClientRegistrationConfig *DynamicClientRegistrationConfig
// RedirectURL is a required URL to redirect to after authorization.
// The caller is responsible for handling the redirect out of band.
//
// If Dynamic Client Registration is used:
// - this field is permitted to be empty, in which case it will be set
// to the first redirect URI from
// DynamicClientRegistrationConfig.Metadata.RedirectURIs.
// - if the field is not empty, it must be one of the redirect URIs in
// DynamicClientRegistrationConfig.Metadata.RedirectURIs.
RedirectURL string
// 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)
}
// AuthorizationCodeHandler is an implementation of [OAuthHandler] that uses
// the authorization code flow to obtain access tokens.
type AuthorizationCodeHandler struct {
config *AuthorizationCodeHandlerConfig
// tokenSource is the token source to use for authorization.
tokenSource oauth2.TokenSource
}
var _ OAuthHandler = (*AuthorizationCodeHandler)(nil)
func (h *AuthorizationCodeHandler) isOAuthHandler() {}
func (h *AuthorizationCodeHandler) TokenSource(ctx context.Context) (oauth2.TokenSource, error) {
return h.tokenSource, nil
}
// NewAuthorizationCodeHandler creates a new AuthorizationCodeHandler.
// It performs validation of the configuration and returns an error if it is invalid.
// The passed config is consumed by the handler and should not be modified after.
func NewAuthorizationCodeHandler(config *AuthorizationCodeHandlerConfig) (*AuthorizationCodeHandler, error) {
if config == nil {
return nil, errors.New("config must be provided")
}
if config.ClientIDMetadataDocumentConfig == nil &&
config.PreregisteredClientConfig == nil &&
config.DynamicClientRegistrationConfig == nil {
return nil, errors.New("at least one client registration configuration must be provided")
}
if config.AuthorizationCodeFetcher == nil {
return nil, errors.New("AuthorizationCodeFetcher is required")
}
if config.ClientIDMetadataDocumentConfig != nil && !isNonRootHTTPSURL(config.ClientIDMetadataDocumentConfig.URL) {
return nil, fmt.Errorf("client ID metadata document URL must be a non-root HTTPS URL")
}
preCfg := config.PreregisteredClientConfig
if preCfg != nil {
if preCfg.ClientSecretAuthConfig == nil {
return nil, errors.New("ClientSecretAuthConfig is required for pre-registered client")
}
if preCfg.ClientSecretAuthConfig.ClientID == "" || preCfg.ClientSecretAuthConfig.ClientSecret == "" {
return nil, fmt.Errorf("pre-registered client ID or secret is empty")
}
}
dCfg := config.DynamicClientRegistrationConfig
if dCfg != nil {
if dCfg.Metadata == nil {
return nil, errors.New("Metadata is required for dynamic client registration")
}
if len(dCfg.Metadata.RedirectURIs) == 0 {
return nil, errors.New("Metadata.RedirectURIs is required for dynamic client registration")
}
if config.RedirectURL == "" {
config.RedirectURL = dCfg.Metadata.RedirectURIs[0]
} else if !slices.Contains(dCfg.Metadata.RedirectURIs, config.RedirectURL) {
return nil, fmt.Errorf("RedirectURL %q is not in the list of allowed redirect URIs for dynamic client registration", config.RedirectURL)
}
}
if config.RedirectURL == "" {
// If the RedirectURL was supposed to be set by the dynamic client registration,
// it should have been set by now. Otherwise, it is required.
return nil, errors.New("RedirectURL is required")
}
return &AuthorizationCodeHandler{config: config}, nil
}
func isNonRootHTTPSURL(u string) bool {
pu, err := url.Parse(u)
if err != nil {
return false
}
return pu.Scheme == "https" && pu.Path != ""
}
// Authorize performs the authorization flow.
// It is designed to perform the whole Authorization Code Grant flow.
// On success, [AuthorizationCodeHandler.TokenSource] will return a token source with the fetched token.
func (h *AuthorizationCodeHandler) Authorize(ctx context.Context, req *http.Request, resp *http.Response) error {
defer resp.Body.Close()
wwwChallenges, err := oauthex.ParseWWWAuthenticate(resp.Header[http.CanonicalHeaderKey("WWW-Authenticate")])
if err != nil {
return fmt.Errorf("failed to parse WWW-Authenticate header: %v", err)
}
if resp.StatusCode == http.StatusForbidden && errorFromChallenges(wwwChallenges) != "insufficient_scope" {
// We only want to perform step-up authorization for insufficient_scope errors.
// Returning nil, so that the call is retried immediately and the response
// is handled appropriately by the connection.
// Step-up authorization is defined at
// https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#step-up-authorization-flow
return nil
}
prm, err := h.getProtectedResourceMetadata(ctx, wwwChallenges, req.URL.String())
if err != nil {
return err
}
asm, err := h.getAuthServerMetadata(ctx, prm)
if err != nil {
return err
}
resolvedClientConfig, err := h.handleRegistration(ctx, asm)
if err != nil {
return err
}
scps := scopesFromChallenges(wwwChallenges)
if len(scps) == 0 && len(prm.ScopesSupported) > 0 {
scps = prm.ScopesSupported
}
cfg := &oauth2.Config{
ClientID: resolvedClientConfig.clientID,
ClientSecret: resolvedClientConfig.clientSecret,
Endpoint: oauth2.Endpoint{
AuthURL: asm.AuthorizationEndpoint,
TokenURL: asm.TokenEndpoint,
AuthStyle: resolvedClientConfig.authStyle,
},
RedirectURL: h.config.RedirectURL,
Scopes: scps,
}
authRes, err := h.getAuthorizationCode(ctx, cfg, req.URL.String())
if err != nil {
// Purposefully leaving the error unwrappable so it can be handled by the caller.
return err
}
return h.exchangeAuthorizationCode(ctx, cfg, authRes, prm.Resource)
}
// resourceMetadataURLFromChallenges returns a resource metadata URL from the given "WWW-Authenticate" header challenges,
// or the empty string if there is none.
func resourceMetadataURLFromChallenges(cs []oauthex.Challenge) string {
for _, c := range cs {
if u := c.Params["resource_metadata"]; u != "" {
return u
}
}
return ""
}
// scopesFromChallenges returns the scopes from the given "WWW-Authenticate" header challenges.
// It only looks at challenges with the "Bearer" scheme.
func scopesFromChallenges(cs []oauthex.Challenge) []string {
for _, c := range cs {
if c.Scheme == "bearer" && c.Params["scope"] != "" {
return strings.Fields(c.Params["scope"])
}
}
return nil
}
// errorFromChallenges returns the error from the given "WWW-Authenticate" header challenges.
// It only looks at challenges with the "Bearer" scheme.
func errorFromChallenges(cs []oauthex.Challenge) string {
for _, c := range cs {
if c.Scheme == "bearer" && c.Params["error"] != "" {
return c.Params["error"]
}
}
return ""
}
// getProtectedResourceMetadata returns the protected resource metadata.
// If no metadata was found or the fetched metadata fails security checks,
// it returns an error.
func (h *AuthorizationCodeHandler) getProtectedResourceMetadata(ctx context.Context, wwwChallenges []oauthex.Challenge, mcpServerURL string) (*oauthex.ProtectedResourceMetadata, error) {
var errs []error
// Use MCP server URL as the resource URI per
// https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#canonical-server-uri.
for _, url := range protectedResourceMetadataURLs(resourceMetadataURLFromChallenges(wwwChallenges), mcpServerURL) {
prm, err := oauthex.GetProtectedResourceMetadata(ctx, url.URL, url.Resource, http.DefaultClient)
if err != nil {
errs = append(errs, err)
continue
}
if prm == nil {
errs = append(errs, fmt.Errorf("protected resource metadata is nil"))
continue
}
return prm, nil
}
return nil, fmt.Errorf("failed to get protected resource metadata: %v", errors.Join(errs...))
}
type prmURL struct {
// URL represents a URL where Protected Resource Metadata may be retrieved.
URL string
// Resource represents the corresponding resource URL for [URL].
// It is required to perform validation described in RFC 9728, section 3.3.
Resource string
}
// protectedResourceMetadataURLs returns a list of URLs to try when looking for
// protected resource metadata as mandated by the MCP specification:
// https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#protected-resource-metadata-discovery-requirements
func protectedResourceMetadataURLs(metadataURL, resourceURL string) []prmURL {
var urls []prmURL
if metadataURL != "" {
urls = append(urls, prmURL{
URL: metadataURL,
Resource: resourceURL,
})
}
ru, err := url.Parse(resourceURL)
if err != nil {
return urls
}
mu := *ru
// "At the path of the server's MCP endpoint".
mu.Path = "/.well-known/oauth-protected-resource/" + strings.TrimLeft(ru.Path, "/")
urls = append(urls, prmURL{
URL: mu.String(),
Resource: resourceURL,
})
// "At the root".
mu.Path = "/.well-known/oauth-protected-resource"
ru.Path = ""
urls = append(urls, prmURL{
URL: mu.String(),
Resource: ru.String(),
})
return urls
}
// getAuthServerMetadata returns the authorization server metadata.
// The provided Protected Resource Metadata must not be nil.
// It returns an error if the metadata request fails with non-4xx HTTP status code
// or the fetched metadata fails security checks.
// If no metadata was found, it returns a minimal set of endpoints
// as a fallback to 2025-03-26 spec.
func (h *AuthorizationCodeHandler) getAuthServerMetadata(ctx context.Context, prm *oauthex.ProtectedResourceMetadata) (*oauthex.AuthServerMeta, error) {
var authServerURL string
if len(prm.AuthorizationServers) > 0 {
// Use the first authorization server, similarly to other SDKs.
authServerURL = prm.AuthorizationServers[0]
} else {
// Fallback to 2025-03-26 spec: MCP server base URL acts as Authorization Server.
authURL, err := url.Parse(prm.Resource)
if err != nil {
return nil, fmt.Errorf("failed to parse resource URL: %v", err)
}
authURL.Path = ""
authServerURL = authURL.String()
}
for _, u := range authorizationServerMetadataURLs(authServerURL) {
asm, err := oauthex.GetAuthServerMeta(ctx, u, authServerURL, http.DefaultClient)
if err != nil {
return nil, fmt.Errorf("failed to get authorization server metadata: %w", err)
}
if asm != nil {
return asm, nil
}
}
// Fallback to 2025-03-26 spec: predefined endpoints.
// https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization#fallbacks-for-servers-without-metadata-discovery
asm := &oauthex.AuthServerMeta{
Issuer: authServerURL,
AuthorizationEndpoint: authServerURL + "/authorize",
TokenEndpoint: authServerURL + "/token",
RegistrationEndpoint: authServerURL + "/register",
}
return asm, nil
}
// authorizationServerMetadataURLs returns a list of URLs to try when looking for
// authorization server metadata as mandated by the MCP specification:
// https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#authorization-server-metadata-discovery.
func authorizationServerMetadataURLs(issuerURL string) []string {
var urls []string
baseURL, err := url.Parse(issuerURL)
if err != nil {
return nil
}
if baseURL.Path == "" {
// "OAuth 2.0 Authorization Server Metadata".
baseURL.Path = "/.well-known/oauth-authorization-server"
urls = append(urls, baseURL.String())
// "OpenID Connect Discovery 1.0".
baseURL.Path = "/.well-known/openid-configuration"
urls = append(urls, baseURL.String())
return urls
}
originalPath := baseURL.Path
// "OAuth 2.0 Authorization Server Metadata with path insertion".
baseURL.Path = "/.well-known/oauth-authorization-server/" + strings.TrimLeft(originalPath, "/")
urls = append(urls, baseURL.String())
// "OpenID Connect Discovery 1.0 with path insertion".
baseURL.Path = "/.well-known/openid-configuration/" + strings.TrimLeft(originalPath, "/")
urls = append(urls, baseURL.String())
// "OpenID Connect Discovery 1.0 with path appending".
baseURL.Path = "/" + strings.Trim(originalPath, "/") + "/.well-known/openid-configuration"
urls = append(urls, baseURL.String())
return urls
}
type registrationType int
const (
registrationTypeClientIDMetadataDocument registrationType = iota
registrationTypePreregistered
registrationTypeDynamic
)
type resolvedClientConfig struct {
registrationType registrationType
clientID string
clientSecret string
authStyle oauth2.AuthStyle
}
func selectTokenAuthMethod(supported []string) oauth2.AuthStyle {
prefOrder := []string{
// Preferred in OAuth 2.1 draft: https://www.ietf.org/archive/id/draft-ietf-oauth-v2-1-14.html#name-client-secret.
"client_secret_post",
"client_secret_basic",
}
for _, method := range prefOrder {
if slices.Contains(supported, method) {
return authMethodToStyle(method)
}
}
return oauth2.AuthStyleAutoDetect
}
func authMethodToStyle(method string) oauth2.AuthStyle {
switch method {
case "client_secret_post":
return oauth2.AuthStyleInParams
case "client_secret_basic":
return oauth2.AuthStyleInHeader
case "none":
// "none" is equivalent to "client_secret_post" but without sending client secret.
return oauth2.AuthStyleInParams
default:
// "client_secret_basic" is the default per https://datatracker.ietf.org/doc/html/rfc7591#section-2.
return oauth2.AuthStyleInHeader
}
}
// handleRegistration handles client registration.
// The provided authorization server metadata must be non-nil.
// Support for different registration methods is defined as follows:
// - Client ID Metadata Document: metadata must have
// `ClientIDMetadataDocumentSupported` set to true.
// - Pre-registered client: assumed to be supported.
// - Dynamic client registration: metadata must have
// `RegistrationEndpoint` set to a non-empty value.
func (h *AuthorizationCodeHandler) handleRegistration(ctx context.Context, asm *oauthex.AuthServerMeta) (*resolvedClientConfig, error) {
// 1. Attempt to use Client ID Metadata Document (SEP-991).
cimdCfg := h.config.ClientIDMetadataDocumentConfig
if cimdCfg != nil && asm.ClientIDMetadataDocumentSupported {
return &resolvedClientConfig{
registrationType: registrationTypeClientIDMetadataDocument,
clientID: cimdCfg.URL,
}, nil
}
// 2. Attempt to use pre-registered client configuration.
pCfg := h.config.PreregisteredClientConfig
if pCfg != nil {
authStyle := selectTokenAuthMethod(asm.TokenEndpointAuthMethodsSupported)
return &resolvedClientConfig{
registrationType: registrationTypePreregistered,
clientID: pCfg.ClientSecretAuthConfig.ClientID,
clientSecret: pCfg.ClientSecretAuthConfig.ClientSecret,
authStyle: authStyle,
}, nil
}
// 3. Attempt to use dynamic client registration.
dcrCfg := h.config.DynamicClientRegistrationConfig
if dcrCfg != nil && asm.RegistrationEndpoint != "" {
regResp, err := oauthex.RegisterClient(ctx, asm.RegistrationEndpoint, dcrCfg.Metadata, http.DefaultClient)
if err != nil {
return nil, fmt.Errorf("failed to register client: %w", err)
}
cfg := &resolvedClientConfig{
registrationType: registrationTypeDynamic,
clientID: regResp.ClientID,
clientSecret: regResp.ClientSecret,
authStyle: authMethodToStyle(regResp.TokenEndpointAuthMethod),
}
return cfg, nil
}
return nil, fmt.Errorf("no configured client registration methods are supported by the authorization server")
}
type authResult struct {
*AuthorizationResult
// usedCodeVerifier is the PKCE code verifier used to obtain the authorization code.
// It is preserved for the token exchange step.
usedCodeVerifier string
}
// getAuthorizationCode uses the [AuthorizationCodeHandler.AuthorizationCodeFetcher]
// to obtain an authorization code.
func (h *AuthorizationCodeHandler) getAuthorizationCode(ctx context.Context, cfg *oauth2.Config, resourceURL string) (*authResult, error) {
codeVerifier := oauth2.GenerateVerifier()
state := rand.Text()
authURL := cfg.AuthCodeURL(state,
oauth2.S256ChallengeOption(codeVerifier),
oauth2.SetAuthURLParam("resource", resourceURL),
)
authRes, err := h.config.AuthorizationCodeFetcher(ctx, &AuthorizationArgs{URL: authURL})
if err != nil {
// Purposefully leaving the error unwrappable so it can be handled by the caller.
return nil, err
}
if authRes.State != state {
return nil, fmt.Errorf("state mismatch")
}
return &authResult{
AuthorizationResult: authRes,
usedCodeVerifier: codeVerifier,
}, nil
}
// exchangeAuthorizationCode exchanges the authorization code for a token
// and stores it in a token source.
func (h *AuthorizationCodeHandler) exchangeAuthorizationCode(ctx context.Context, cfg *oauth2.Config, authResult *authResult, resourceURL string) error {
opts := []oauth2.AuthCodeOption{
oauth2.VerifierOption(authResult.usedCodeVerifier),
oauth2.SetAuthURLParam("resource", resourceURL),
}
token, err := cfg.Exchange(ctx, authResult.Code, opts...)
if err != nil {
return fmt.Errorf("token exchange failed: %w", err)
}
h.tokenSource = cfg.TokenSource(ctx, token)
return nil
}

658
auth/authorization_code_test.go Normal file
View file

@ -0,0 +1,658 @@
// Copyright 2026 The Go MCP SDK Authors. All rights reserved.
// Use of this source code is governed by the license
// that can be found in the LICENSE file.
//go:build mcp_go_client_oauth
package auth
import (
"context"
"fmt"
"net/http"
"net/http/httptest"
"net/http/httputil"
"testing"
"github.com/google/go-cmp/cmp"
"github.com/modelcontextprotocol/go-sdk/internal/oauthtest"
"github.com/modelcontextprotocol/go-sdk/oauthex"
"golang.org/x/oauth2"
)
func TestAuthorize(t *testing.T) {
authServer := oauthtest.NewFakeAuthorizationServer(oauthtest.Config{
RegistrationConfig: &oauthtest.RegistrationConfig{
PreregisteredClients: map[string]oauthtest.ClientInfo{
"test_client_id": {
Secret: "test_client_secret",
RedirectURIs: []string{"http://localhost:12345/callback"},
},
},
},
})
authServer.Start(t)
resourceMux := http.NewServeMux()
resourceServer := httptest.NewServer(resourceMux)
t.Cleanup(resourceServer.Close)
resourceURL := resourceServer.URL + "/resource"
resourceMux.Handle("/.well-known/oauth-protected-resource/resource", ProtectedResourceMetadataHandler(&oauthex.ProtectedResourceMetadata{
Resource: resourceURL,
AuthorizationServers: []string{authServer.URL()},
}))
handler, err := NewAuthorizationCodeHandler(&AuthorizationCodeHandlerConfig{
RedirectURL: "http://localhost:12345/callback",
PreregisteredClientConfig: &PreregisteredClientConfig{
ClientSecretAuthConfig: &ClientSecretAuthConfig{
ClientID: "test_client_id",
ClientSecret: "test_client_secret",
},
},
AuthorizationCodeFetcher: func(ctx context.Context, args *AuthorizationArgs) (*AuthorizationResult, error) {
// The fake authorization server will redirect to an URL with code and state.
client := &http.Client{
CheckRedirect: func(req *http.Request, via []*http.Request) error {
return http.ErrUseLastResponse
},
}
resp, err := client.Get(args.URL)
if err != nil {
return nil, fmt.Errorf("failed to visit auth URL: %v", err)
}
defer resp.Body.Close()
dump, err := httputil.DumpResponse(resp, true)
if err != nil {
t.Fatalf("failed to dump response: %v", err)
}
t.Log(string(dump))
location, err := resp.Location()
if err != nil {
return nil, fmt.Errorf("failed to get location header: %v", err)
}
return &AuthorizationResult{
Code: location.Query().Get("code"),
State: location.Query().Get("state"),
}, nil
},
})
if err != nil {
t.Fatalf("NewAuthorizationCodeHandler failed: %v", err)
}
req := httptest.NewRequest(http.MethodGet, resourceURL, nil)
resp := &http.Response{
StatusCode: http.StatusUnauthorized,
Header: make(http.Header),
Body: http.NoBody,
Request: req,
}
resp.Header.Set(
"WWW-Authenticate",
"Bearer resource_metadata="+resourceServer.URL+"/.well-known/oauth-protected-resource/resource",
)
if err := handler.Authorize(context.Background(), req, resp); err != nil {
t.Fatalf("Authorize failed: %v", err)
}
tokenSource, err := handler.TokenSource(t.Context())
if err != nil {
t.Fatalf("Failed to get token source: %v", err)
}
token, err := tokenSource.Token()
if err != nil {
t.Fatalf("Failed to get token: %v", err)
}
if token.AccessToken != "test_access_token" {
t.Errorf("Expected access token 'test_access_token', got '%s'", token.AccessToken)
}
}
func TestAuthorize_ForbiddenUnhandledError(t *testing.T) {
req := httptest.NewRequest(http.MethodGet, "http://example.com/resource", nil)
resp := &http.Response{
StatusCode: http.StatusForbidden,
Header: make(http.Header),
Body: http.NoBody,
Request: req,
}
resp.Header.Set(
"WWW-Authenticate",
"Bearer error=invalid_token",
)
handler := &AuthorizationCodeHandler{} // No config needed for this test.
err := handler.Authorize(t.Context(), req, resp)
if err != nil {
t.Fatalf("Authorize() failed: %v", err)
}
}
func TestNewAuthorizationCodeHandler_Success(t *testing.T) {
simpleHandler := func(ctx context.Context, args *AuthorizationArgs) (*AuthorizationResult, error) {
return nil, nil
}
tests := []struct {
name string
config *AuthorizationCodeHandlerConfig
}{
{
name: "ClientIDMetadataDocumentConfig",
config: &AuthorizationCodeHandlerConfig{
ClientIDMetadataDocumentConfig: &ClientIDMetadataDocumentConfig{URL: "https://example.com/client"},
RedirectURL: "https://example.com/callback",
AuthorizationCodeFetcher: simpleHandler,
},
},
{
name: "PreregisteredClientConfig",
config: &AuthorizationCodeHandlerConfig{
PreregisteredClientConfig: &PreregisteredClientConfig{
ClientSecretAuthConfig: &ClientSecretAuthConfig{
ClientID: "test_client_id",
ClientSecret: "test_client_secret",
},
},
RedirectURL: "https://example.com/callback",
AuthorizationCodeFetcher: simpleHandler,
},
},
{
name: "DynamicClientRegistrationConfig_NoRedirectURL",
config: &AuthorizationCodeHandlerConfig{
DynamicClientRegistrationConfig: &DynamicClientRegistrationConfig{
Metadata: &oauthex.ClientRegistrationMetadata{
RedirectURIs: []string{
"https://example.com/callback",
},
},
},
AuthorizationCodeFetcher: simpleHandler,
},
},
{
name: "DynamicClientRegistrationConfig_WithRedirectURL",
config: &AuthorizationCodeHandlerConfig{
DynamicClientRegistrationConfig: &DynamicClientRegistrationConfig{
Metadata: &oauthex.ClientRegistrationMetadata{
RedirectURIs: []string{
"https://example.com/callback",
},
},
},
RedirectURL: "https://example.com/callback",
AuthorizationCodeFetcher: simpleHandler,
},
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
if _, err := NewAuthorizationCodeHandler(tt.config); err != nil {
t.Fatalf("NewAuthorizationCodeHandler failed: %v", err)
}
})
}
}
func TestNewAuthorizationCodeHandler_Error(t *testing.T) {
validConfig := func() *AuthorizationCodeHandlerConfig {
return &AuthorizationCodeHandlerConfig{
ClientIDMetadataDocumentConfig: &ClientIDMetadataDocumentConfig{URL: "https://example.com/client"},
RedirectURL: "https://example.com/callback",
AuthorizationCodeFetcher: func(ctx context.Context, args *AuthorizationArgs) (*AuthorizationResult, error) {
return nil, nil
},
}
}
// Ensure the base config is valid
if _, err := NewAuthorizationCodeHandler(validConfig()); err != nil {
t.Fatalf("NewAuthorizationCodeHandler failed: %v", err)
}
tests := []struct {
name string
config func() *AuthorizationCodeHandlerConfig
}{
{
name: "NilConfig",
config: func() *AuthorizationCodeHandlerConfig {
return nil
},
},
{
name: "NoRegistrationConfig",
config: func() *AuthorizationCodeHandlerConfig {
cfg := validConfig()
cfg.ClientIDMetadataDocumentConfig = nil
cfg.PreregisteredClientConfig = nil
cfg.DynamicClientRegistrationConfig = nil
return cfg
},
},
{
name: "MissingRedirectURL",
config: func() *AuthorizationCodeHandlerConfig {
cfg := validConfig()
cfg.RedirectURL = ""
return cfg
},
},
{
name: "MissingAuthorizationCodeFetcher",
config: func() *AuthorizationCodeHandlerConfig {
cfg := validConfig()
cfg.AuthorizationCodeFetcher = nil
return cfg
},
},
{
name: "InvalidMetadataURL",
config: func() *AuthorizationCodeHandlerConfig {
cfg := validConfig()
cfg.ClientIDMetadataDocumentConfig.URL = "https://example.com"
return cfg
},
},
{
name: "InvalidPreregistered_MissingSecretConfig",
config: func() *AuthorizationCodeHandlerConfig {
cfg := validConfig()
cfg.PreregisteredClientConfig = &PreregisteredClientConfig{}
return cfg
},
},
{
name: "InvalidPreregistered_EmptyID",
config: func() *AuthorizationCodeHandlerConfig {
cfg := validConfig()
cfg.PreregisteredClientConfig = &PreregisteredClientConfig{
ClientSecretAuthConfig: &ClientSecretAuthConfig{
ClientSecret: "secret",
},
}
return cfg
},
},
{
name: "InvalidPreregistered_EmptySecret",
config: func() *AuthorizationCodeHandlerConfig {
cfg := validConfig()
cfg.PreregisteredClientConfig = &PreregisteredClientConfig{
ClientSecretAuthConfig: &ClientSecretAuthConfig{
ClientID: "test_client_id",
},
}
return cfg
},
},
{
name: "InvalidDynamic_MissingMetadata",
config: func() *AuthorizationCodeHandlerConfig {
cfg := validConfig()
cfg.DynamicClientRegistrationConfig = &DynamicClientRegistrationConfig{}
return cfg
},
},
{
name: "InvalidDynamic_InconsistentRedirectURI",
config: func() *AuthorizationCodeHandlerConfig {
cfg := validConfig()
cfg.DynamicClientRegistrationConfig = &DynamicClientRegistrationConfig{
Metadata: &oauthex.ClientRegistrationMetadata{
RedirectURIs: []string{"https://example.com/callback1"},
},
}
cfg.RedirectURL = "https://example.com/callback2"
return cfg
},
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
_, err := NewAuthorizationCodeHandler(tt.config())
if err == nil {
t.Errorf("NewAuthorizationCodeHandler() = nil, want error")
}
})
}
}
func TestGetProtectedResourceMetadata(t *testing.T) {
handler := &AuthorizationCodeHandler{} // No config needed for this method
pathForChallenge := "/protected-resource"
tests := []struct {
name string
challengesProvided bool
prmPath string
resourcePath string
wantError bool
}{
{
name: "FromChallenges",
challengesProvided: true,
prmPath: pathForChallenge,
resourcePath: "/resource",
wantError: false,
},
{
name: "FallbackToEndpoint",
challengesProvided: false,
prmPath: "/.well-known/oauth-protected-resource/resource",
resourcePath: "/resource",
wantError: false,
},
{
name: "FallbackToRoot",
challengesProvided: false,
prmPath: "/.well-known/oauth-protected-resource",
resourcePath: "",
wantError: false,
},
{
name: "NoMetadata",
challengesProvided: false,
prmPath: "/incorrect",
wantError: true,
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
mux := http.NewServeMux()
server := httptest.NewServer(mux)
t.Cleanup(server.Close)
resourceURL := server.URL + tt.resourcePath
metadata := &oauthex.ProtectedResourceMetadata{
Resource: resourceURL,
ScopesSupported: []string{"read", "write"},
}
mux.Handle(tt.prmPath, ProtectedResourceMetadataHandler(metadata))
var challenges []oauthex.Challenge
if tt.challengesProvided {
challenges = []oauthex.Challenge{
{
Scheme: "Bearer",
Params: map[string]string{
"resource_metadata": server.URL + pathForChallenge,
},
},
}
}
got, err := handler.getProtectedResourceMetadata(t.Context(), challenges, resourceURL)
if err != nil {
if !tt.wantError {
t.Fatalf("getProtectedResourceMetadata() error = %v, want nil", err)
}
return
}
if got == nil {
t.Fatal("getProtectedResourceMetadata() got nil, want metadata")
}
if diff := cmp.Diff(metadata, got); diff != "" {
t.Errorf("getProtectedResourceMetadata() metadata mismatch (-want +got):\n%s", diff)
}
})
}
}
func TestGetAuthServerMetadata(t *testing.T) {
handler := &AuthorizationCodeHandler{} // No config needed for this method
tests := []struct {
name string
authorizationAtMCPServer bool
issuerPath string
endpointConfig *oauthtest.MetadataEndpointConfig
}{
{
name: "OAuthEndpoint_Root",
authorizationAtMCPServer: false,
issuerPath: "",
endpointConfig: &oauthtest.MetadataEndpointConfig{
ServeOAuthInsertedEndpoint: true,
},
},
{
name: "OpenIDEndpoint_Root",
authorizationAtMCPServer: false,
issuerPath: "",
endpointConfig: &oauthtest.MetadataEndpointConfig{
ServeOpenIDInsertedEndpoint: true,
},
},
{
name: "OAuthEndpoint_Path",
authorizationAtMCPServer: false,
issuerPath: "/oauth",
endpointConfig: &oauthtest.MetadataEndpointConfig{
ServeOAuthInsertedEndpoint: true,
},
},
{
name: "OpenIDEndpoint_Path",
authorizationAtMCPServer: false,
issuerPath: "/openid",
endpointConfig: &oauthtest.MetadataEndpointConfig{
ServeOpenIDInsertedEndpoint: true,
},
},
{
name: "OpenIDAppendedEndpoint_Path",
authorizationAtMCPServer: false,
issuerPath: "/openid",
endpointConfig: &oauthtest.MetadataEndpointConfig{
ServeOpenIDAppendedEndpoint: true,
},
},
{
name: "FallbackToMCPServer",
authorizationAtMCPServer: true,
},
{
name: "NoMetadata",
issuerPath: "",
endpointConfig: &oauthtest.MetadataEndpointConfig{
// All metadata endpoints disabled.
ServeOAuthInsertedEndpoint: false,
ServeOpenIDInsertedEndpoint: false,
},
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
s := oauthtest.NewFakeAuthorizationServer(oauthtest.Config{
IssuerPath: tt.issuerPath,
MetadataEndpointConfig: tt.endpointConfig,
})
s.Start(t)
issuerURL := s.URL() + tt.issuerPath
resourceURL := "https://example.com/resource"
authServers := []string{issuerURL}
if tt.authorizationAtMCPServer {
resourceURL = issuerURL
authServers = nil
}
prm := &oauthex.ProtectedResourceMetadata{
Resource: resourceURL,
AuthorizationServers: authServers,
}
got, err := handler.getAuthServerMetadata(t.Context(), prm)
if err != nil {
t.Fatalf("getAuthServerMetadata() error = %v, want nil", err)
}
if got == nil {
t.Fatal("getAuthServerMetadata() got nil, want metadata")
}
if got.Issuer != issuerURL {
t.Errorf("getAuthServerMetadata() issuer = %q, want %q", got.Issuer, issuerURL)
}
})
}
}
func TestSelectTokenAuthMethod(t *testing.T) {
tests := []struct {
name string
supported []string
want oauth2.AuthStyle
}{
{
name: "PostPreferredOverBasic",
supported: []string{"client_secret_basic", "client_secret_post"},
want: oauth2.AuthStyleInParams,
},
{
name: "BasicChosenIfPostNotSupported",
supported: []string{"private_key_jwt", "client_secret_basic"},
want: oauth2.AuthStyleInHeader,
},
{
name: "NoneSupported",
supported: []string{"private_key_jwt"},
want: oauth2.AuthStyleAutoDetect,
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
got := selectTokenAuthMethod(tt.supported)
if got != tt.want {
t.Errorf("selectTokenAuthMethod() = %v, want %v", got, tt.want)
}
})
}
}
func TestHandleRegistration(t *testing.T) {
tests := []struct {
name string
serverConfig *oauthtest.RegistrationConfig
handlerConfig *AuthorizationCodeHandlerConfig
asm *oauthex.AuthServerMeta
want *resolvedClientConfig
wantError bool
}{
{
name: "ClientIDMetadataDocument",
serverConfig: &oauthtest.RegistrationConfig{
ClientIDMetadataDocumentSupported: true,
},
handlerConfig: &AuthorizationCodeHandlerConfig{
ClientIDMetadataDocumentConfig: &ClientIDMetadataDocumentConfig{URL: "https://client.example.com"},
},
want: &resolvedClientConfig{
registrationType: registrationTypeClientIDMetadataDocument,
clientID: "https://client.example.com",
},
},
{
name: "Preregistered",
serverConfig: &oauthtest.RegistrationConfig{
PreregisteredClients: map[string]oauthtest.ClientInfo{
"pre_client_id": {
Secret: "pre_client_secret",
},
},
},
handlerConfig: &AuthorizationCodeHandlerConfig{
PreregisteredClientConfig: &PreregisteredClientConfig{
ClientSecretAuthConfig: &ClientSecretAuthConfig{
ClientID: "pre_client_id",
ClientSecret: "pre_client_secret",
},
},
},
want: &resolvedClientConfig{
registrationType: registrationTypePreregistered,
clientID: "pre_client_id",
clientSecret: "pre_client_secret",
authStyle: oauth2.AuthStyleInParams,
},
},
{
name: "NoneSupported",
handlerConfig: &AuthorizationCodeHandlerConfig{
ClientIDMetadataDocumentConfig: &ClientIDMetadataDocumentConfig{URL: "https://client.example.com"},
},
wantError: true,
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
s := oauthtest.NewFakeAuthorizationServer(oauthtest.Config{RegistrationConfig: tt.serverConfig})
s.Start(t)
handler := &AuthorizationCodeHandler{config: tt.handlerConfig}
asm, err := handler.getAuthServerMetadata(t.Context(), &oauthex.ProtectedResourceMetadata{
AuthorizationServers: []string{s.URL()},
})
if err != nil {
t.Fatalf("getAuthServerMetadata() error = %v, want nil", err)
}
got, err := handler.handleRegistration(t.Context(), asm)
if err != nil {
if !tt.wantError {
t.Fatalf("handleRegistration() unexpected error = %v", err)
}
return
}
if got.registrationType != tt.want.registrationType {
t.Errorf("handleRegistration() registrationType = %v, want %v", got.registrationType, tt.want.registrationType)
}
if got.clientID != tt.want.clientID {
t.Errorf("handleRegistration() clientID = %q, want %q", got.clientID, tt.want.clientID)
}
if got.clientSecret != tt.want.clientSecret {
t.Errorf("handleRegistration() clientSecret = %q, want %q", got.clientSecret, tt.want.clientSecret)
}
if got.authStyle != tt.want.authStyle {
t.Errorf("handleRegistration() authStyle = %v, want %v", got.authStyle, tt.want.authStyle)
}
})
}
}
func TestDynamicRegistration(t *testing.T) {
s := oauthtest.NewFakeAuthorizationServer(oauthtest.Config{
RegistrationConfig: &oauthtest.RegistrationConfig{
DynamicClientRegistrationEnabled: true,
},
})
s.Start(t)
handler := &AuthorizationCodeHandler{config: &AuthorizationCodeHandlerConfig{
DynamicClientRegistrationConfig: &DynamicClientRegistrationConfig{
Metadata: &oauthex.ClientRegistrationMetadata{},
},
}}
asm, err := handler.getAuthServerMetadata(t.Context(), &oauthex.ProtectedResourceMetadata{
AuthorizationServers: []string{s.URL()},
})
if err != nil {
t.Fatalf("getAuthServerMetadata() error = %v, want nil", err)
}
got, err := handler.handleRegistration(t.Context(), asm)
if err != nil {
t.Fatalf("handleRegistration() error = %v, want nil", err)
}
if got.registrationType != registrationTypeDynamic {
t.Errorf("handleRegistration() registrationType = %v, want %v", got.registrationType, registrationTypeDynamic)
}
if got.clientID == "" {
t.Errorf("handleRegistration() clientID = %q, want non-empty", got.clientID)
}
if got.clientSecret == "" {
t.Errorf("handleRegistration() clientSecret = %q, want non-empty", got.clientSecret)
}
if got.authStyle != oauth2.AuthStyleInHeader {
t.Errorf("handleRegistration() authStyle = %v, want %v", got.authStyle, oauth2.AuthStyleInHeader)
}
}

137
auth/client.go
View file

@ -2,122 +2,41 @@
// Use of this source code is governed by an MIT-style
// license that can be found in the LICENSE file.
//go:build mcp_go_client_oauth
package auth
import (
"bytes"
"errors"
"io"
"context"
"net/http"
"sync"
"golang.org/x/oauth2"
)
// An OAuthHandler conducts an OAuth flow and returns a [oauth2.TokenSource] if the authorization
// is approved, or an error if not.
// The handler receives the HTTP request and response that triggered the authentication flow.
// To obtain the protected resource metadata, call [oauthex.GetProtectedResourceMetadataFromHeader].
type OAuthHandler func(req *http.Request, res *http.Response) (oauth2.TokenSource, error)
// OAuthHandler is an interface for handling OAuth flows.
//
// If a transport wishes to support OAuth 2 authorization, it should support
// being configured with an OAuthHandler. It should call the handler's
// TokenSource method whenever it sends an HTTP request to set the
// Authorization header. If a request fails with a 401 or 403, it should call
// Authorize, and if that returns nil, it should retry the request. It should
// not call Authorize after the second failure. See
// [github.com/modelcontextprotocol/go-sdk/mcp.StreamableClientTransport]
// for an example.
type OAuthHandler interface {
isOAuthHandler()
// HTTPTransport is an [http.RoundTripper] that follows the MCP
// OAuth protocol when it encounters a 401 Unauthorized response.
type HTTPTransport struct {
handler OAuthHandler
mu sync.Mutex // protects opts.Base
opts HTTPTransportOptions
}
// NewHTTPTransport returns a new [*HTTPTransport].
// The handler is invoked when an HTTP request results in a 401 Unauthorized status.
// It is called only once per transport. Once a TokenSource is obtained, it is used
// for the lifetime of the transport; subsequent 401s are not processed.
func NewHTTPTransport(handler OAuthHandler, opts *HTTPTransportOptions) (*HTTPTransport, error) {
if handler == nil {
return nil, errors.New("handler cannot be nil")
}
t := &HTTPTransport{
handler: handler,
}
if opts != nil {
t.opts = *opts
}
if t.opts.Base == nil {
t.opts.Base = http.DefaultTransport
}
return t, nil
}
// HTTPTransportOptions are options to [NewHTTPTransport].
type HTTPTransportOptions struct {
// Base is the [http.RoundTripper] to use.
// If nil, [http.DefaultTransport] is used.
Base http.RoundTripper
}
func (t *HTTPTransport) RoundTrip(req *http.Request) (*http.Response, error) {
t.mu.Lock()
base := t.opts.Base
t.mu.Unlock()
var (
// If haveBody is set, the request has a nontrivial body, and we need avoid
// reading (or closing) it multiple times. In that case, bodyBytes is its
// content.
haveBody bool
bodyBytes []byte
)
if req.Body != nil && req.Body != http.NoBody {
// if we're setting Body, we must mutate first.
req = req.Clone(req.Context())
haveBody = true
var err error
bodyBytes, err = io.ReadAll(req.Body)
if err != nil {
return nil, err
}
// Now that we've read the request body, http.RoundTripper requires that we
// close it.
req.Body.Close() // ignore error
req.Body = io.NopCloser(bytes.NewReader(bodyBytes))
}
resp, err := base.RoundTrip(req)
if err != nil {
return nil, err
}
if resp.StatusCode != http.StatusUnauthorized {
return resp, nil
}
if _, ok := base.(*oauth2.Transport); ok {
// We failed to authorize even with a token source; give up.
return resp, nil
}
resp.Body.Close()
// Try to authorize.
t.mu.Lock()
defer t.mu.Unlock()
// If we don't have a token source, get one by following the OAuth flow.
// (We may have obtained one while t.mu was not held above.)
// TODO: We hold the lock for the entire OAuth flow. This could be a long
// time. Is there a better way?
if _, ok := t.opts.Base.(*oauth2.Transport); !ok {
ts, err := t.handler(req, resp)
if err != nil {
return nil, err
}
t.opts.Base = &oauth2.Transport{Base: t.opts.Base, Source: ts}
}
// If we don't have a body, the request is reusable, though it will be cloned
// by the base. However, if we've had to read the body, we must clone.
if haveBody {
req = req.Clone(req.Context())
req.Body = io.NopCloser(bytes.NewReader(bodyBytes))
}
return t.opts.Base.RoundTrip(req)
// 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
}

135
auth/client_private.go Normal file
View file

@ -0,0 +1,135 @@
// Copyright 2025 The Go MCP SDK Authors. All rights reserved.
// Use of this source code is governed by an MIT-style
// license that can be found in the LICENSE file.
//go:build mcp_go_client_oauth
package auth
import (
"bytes"
"errors"
"io"
"net/http"
"sync"
"golang.org/x/oauth2"
)
// An OAuthHandlerLegacy conducts an OAuth flow and returns a [oauth2.TokenSource] if the authorization
// is approved, or an error if not.
// The handler receives the HTTP request and response that triggered the authentication flow.
// To obtain the protected resource metadata, call [oauthex.GetProtectedResourceMetadataFromHeader].
//
// Deprecated: Please use the new [OAuthHandler] abstraction that is built
// into the streamable transport. This struct will be removed in v1.5.0.
type OAuthHandlerLegacy func(req *http.Request, res *http.Response) (oauth2.TokenSource, error)
// HTTPTransport is an [http.RoundTripper] that follows the MCP
// OAuth protocol when it encounters a 401 Unauthorized response.
//
// Deprecated: Please use the new [OAuthHandler] abstraction that is built
// into the streamable transport. This struct will be removed in v1.5.0.
type HTTPTransport struct {
handler OAuthHandlerLegacy
mu sync.Mutex // protects opts.Base
opts HTTPTransportOptions
}
// NewHTTPTransport returns a new [*HTTPTransport].
// The handler is invoked when an HTTP request results in a 401 Unauthorized status.
// It is called only once per transport. Once a TokenSource is obtained, it is used
// for the lifetime of the transport; subsequent 401s are not processed.
//
// Deprecated: Please use the new [OAuthHandler] abstraction that is built
// into the streamable transport. This struct will be removed in v1.5.0.
func NewHTTPTransport(handler OAuthHandlerLegacy, opts *HTTPTransportOptions) (*HTTPTransport, error) {
if handler == nil {
return nil, errors.New("handler cannot be nil")
}
t := &HTTPTransport{
handler: handler,
}
if opts != nil {
t.opts = *opts
}
if t.opts.Base == nil {
t.opts.Base = http.DefaultTransport
}
return t, nil
}
// HTTPTransportOptions are options to [NewHTTPTransport].
//
// Deprecated: Please use the new [OAuthHandler] abstraction that is built
// into the streamable transport. This struct will be removed in v1.5.0.
type HTTPTransportOptions struct {
// Base is the [http.RoundTripper] to use.
// If nil, [http.DefaultTransport] is used.
Base http.RoundTripper
}
func (t *HTTPTransport) RoundTrip(req *http.Request) (*http.Response, error) {
t.mu.Lock()
base := t.opts.Base
t.mu.Unlock()
var (
// If haveBody is set, the request has a nontrivial body, and we need avoid
// reading (or closing) it multiple times. In that case, bodyBytes is its
// content.
haveBody bool
bodyBytes []byte
)
if req.Body != nil && req.Body != http.NoBody {
// if we're setting Body, we must mutate first.
req = req.Clone(req.Context())
haveBody = true
var err error
bodyBytes, err = io.ReadAll(req.Body)
if err != nil {
return nil, err
}
// Now that we've read the request body, http.RoundTripper requires that we
// close it.
req.Body.Close() // ignore error
req.Body = io.NopCloser(bytes.NewReader(bodyBytes))
}
resp, err := base.RoundTrip(req)
if err != nil {
return nil, err
}
if resp.StatusCode != http.StatusUnauthorized {
return resp, nil
}
if _, ok := base.(*oauth2.Transport); ok {
// We failed to authorize even with a token source; give up.
return resp, nil
}
resp.Body.Close()
// Try to authorize.
t.mu.Lock()
defer t.mu.Unlock()
// If we don't have a token source, get one by following the OAuth flow.
// (We may have obtained one while t.mu was not held above.)
// TODO: We hold the lock for the entire OAuth flow. This could be a long
// time. Is there a better way?
if _, ok := t.opts.Base.(*oauth2.Transport); !ok {
ts, err := t.handler(req, resp)
if err != nil {
return nil, err
}
t.opts.Base = &oauth2.Transport{Base: t.opts.Base, Source: ts}
}
// If we don't have a body, the request is reusable, though it will be cloned
// by the base. However, if we've had to read the body, we must clone.
if haveBody {
req = req.Clone(req.Context())
req.Body = io.NopCloser(bytes.NewReader(bodyBytes))
}
return t.opts.Base.RoundTrip(req)
}