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:
Maciej Kisiel
GitHub
parent
4e8b6ca17d
commit
c9317fb5b7
1 changed files with 2743 additions and 434 deletions
304
internal/oauthtest/fake_authorization_server.go
Normal file
304
internal/oauthtest/fake_authorization_server.go
Normal file
|
|
@ -0,0 +1,304 @@
|
|||
// 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 oauthtest
|
||||
|
||||
import (
|
||||
"crypto/rand"
|
||||
"crypto/sha256"
|
||||
"encoding/base64"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"fmt"
|
||||
"io"
|
||||
"maps"
|
||||
"net/http"
|
||||
"net/http/httptest"
|
||||
"slices"
|
||||
"testing"
|
||||
|
||||
internaljson "github.com/modelcontextprotocol/go-sdk/internal/json"
|
||||
"github.com/modelcontextprotocol/go-sdk/oauthex"
|
||||
)
|
||||
|
||||
type ClientInfo struct {
|
||||
Secret string
|
||||
RedirectURIs []string
|
||||
}
|
||||
|
||||
type MetadataEndpointConfig struct {
|
||||
// Whether to serve the OAuth Authorization Server Metadata at
|
||||
// /.well-known/oauth-authorization-server + issuerPath.
|
||||
ServeOAuthInsertedEndpoint bool
|
||||
// Whether to serve the OAuth Authorization Server Metadata at
|
||||
// /.well-known/openid-configuration + issuerPath.
|
||||
ServeOpenIDInsertedEndpoint bool
|
||||
// Whether to serve the OAuth Authorization Server Metadata at
|
||||
// issuerPath + /.well-known/openid-configuration.
|
||||
// Should be used when issuerPath is not empty.
|
||||
ServeOpenIDAppendedEndpoint bool
|
||||
}
|
||||
|
||||
type RegistrationConfig struct {
|
||||
// Whether the client ID metadata document is supported.
|
||||
ClientIDMetadataDocumentSupported bool
|
||||
// PreregisteredClients is a map of valid ClientIDs to ClientSecrets.
|
||||
PreregisteredClients map[string]ClientInfo
|
||||
// Whether dynamic client registration is enabled.
|
||||
DynamicClientRegistrationEnabled bool
|
||||
}
|
||||
|
||||
// Config holds configuration for FakeAuthorizationServer.
|
||||
type Config struct {
|
||||
// The optional path component of the issuer URL.
|
||||
// If non-empty, it should start with a "/". It should not end with a "/".
|
||||
// It affects the paths of the server endpoints.
|
||||
IssuerPath string
|
||||
// Configuration of the metadata endpoint.
|
||||
MetadataEndpointConfig *MetadataEndpointConfig
|
||||
// Configuration for client registration.
|
||||
RegistrationConfig *RegistrationConfig
|
||||
}
|
||||
|
||||
// FakeAuthorizationServer is a fake OAuth 2.0 Authorization Server for testing.
|
||||
type FakeAuthorizationServer struct {
|
||||
server *httptest.Server
|
||||
Mux *http.ServeMux
|
||||
config Config
|
||||
clients map[string]ClientInfo
|
||||
codes map[string]codeInfo
|
||||
}
|
||||
|
||||
type codeInfo struct {
|
||||
CodeChallenge string
|
||||
}
|
||||
|
||||
// NewFakeAuthorizationServer creates a new FakeAuthorizationServer.
|
||||
// The server is simple and should not be used outside of testing.
|
||||
// It supports:
|
||||
// - Only the authorization Code Grant
|
||||
// - PKCE verification
|
||||
// - Client tracking & dynamic registration
|
||||
// - Client authentication
|
||||
func NewFakeAuthorizationServer(config Config) *FakeAuthorizationServer {
|
||||
s := &FakeAuthorizationServer{
|
||||
Mux: http.NewServeMux(),
|
||||
config: config,
|
||||
codes: make(map[string]codeInfo),
|
||||
}
|
||||
if config.RegistrationConfig != nil {
|
||||
s.clients = maps.Clone(config.RegistrationConfig.PreregisteredClients)
|
||||
}
|
||||
if s.clients == nil {
|
||||
s.clients = make(map[string]ClientInfo)
|
||||
}
|
||||
|
||||
s.Mux.HandleFunc(s.config.IssuerPath+"/authorize", s.handleAuthorize)
|
||||
s.Mux.HandleFunc(s.config.IssuerPath+"/token", s.handleToken)
|
||||
if config.MetadataEndpointConfig != nil {
|
||||
if config.MetadataEndpointConfig.ServeOAuthInsertedEndpoint {
|
||||
s.Mux.HandleFunc("/.well-known/oauth-authorization-server"+s.config.IssuerPath, s.handleMetadata)
|
||||
}
|
||||
if config.MetadataEndpointConfig.ServeOpenIDInsertedEndpoint {
|
||||
s.Mux.HandleFunc("/.well-known/openid-configuration"+s.config.IssuerPath, s.handleMetadata)
|
||||
}
|
||||
if config.MetadataEndpointConfig.ServeOpenIDAppendedEndpoint && s.config.IssuerPath != "" {
|
||||
s.Mux.HandleFunc(s.config.IssuerPath+"/.well-known/openid-configuration", s.handleMetadata)
|
||||
}
|
||||
} else {
|
||||
// Serve the default OAuth endpoint.
|
||||
s.Mux.HandleFunc("/.well-known/oauth-authorization-server", s.handleMetadata)
|
||||
}
|
||||
if config.RegistrationConfig != nil && config.RegistrationConfig.DynamicClientRegistrationEnabled {
|
||||
s.Mux.HandleFunc(s.config.IssuerPath+"/register", s.handleRegister)
|
||||
}
|
||||
s.server = httptest.NewUnstartedServer(s.Mux)
|
||||
|
||||
return s
|
||||
}
|
||||
|
||||
// Start starts the HTTP server and registers a cleanup function on t to close the server.
|
||||
func (s *FakeAuthorizationServer) Start(t testing.TB) {
|
||||
s.server.Start()
|
||||
t.Cleanup(s.server.Close)
|
||||
}
|
||||
|
||||
// URL returns the base URL of the server (Issuer).
|
||||
func (s *FakeAuthorizationServer) URL() string {
|
||||
return s.server.URL
|
||||
}
|
||||
|
||||
func (s *FakeAuthorizationServer) handleMetadata(w http.ResponseWriter, r *http.Request) {
|
||||
cimdSupported := false
|
||||
var registrationEndpoint string
|
||||
if s.config.RegistrationConfig != nil {
|
||||
cimdSupported = s.config.RegistrationConfig.ClientIDMetadataDocumentSupported
|
||||
if s.config.RegistrationConfig.DynamicClientRegistrationEnabled {
|
||||
registrationEndpoint = s.URL() + s.config.IssuerPath + "/register"
|
||||
}
|
||||
}
|
||||
meta := &oauthex.AuthServerMeta{
|
||||
Issuer: s.URL() + s.config.IssuerPath,
|
||||
AuthorizationEndpoint: s.URL() + s.config.IssuerPath + "/authorize",
|
||||
TokenEndpoint: s.URL() + s.config.IssuerPath + "/token",
|
||||
RegistrationEndpoint: registrationEndpoint,
|
||||
ResponseTypesSupported: []string{"code"},
|
||||
CodeChallengeMethodsSupported: []string{"S256"},
|
||||
ClientIDMetadataDocumentSupported: cimdSupported,
|
||||
TokenEndpointAuthMethodsSupported: []string{"client_secret_post", "client_secret_basic"},
|
||||
}
|
||||
// Set CORS headers for cross-origin client discovery.
|
||||
w.Header().Set("Access-Control-Allow-Origin", "*")
|
||||
w.Header().Set("Access-Control-Allow-Methods", "GET, OPTIONS")
|
||||
w.Header().Set("Access-Control-Allow-Headers", "Content-Type")
|
||||
|
||||
// Handle CORS preflight requests
|
||||
if r.Method == http.MethodOptions {
|
||||
w.WriteHeader(http.StatusNoContent)
|
||||
return
|
||||
}
|
||||
|
||||
// Only GET allowed for metadata retrieval
|
||||
if r.Method != http.MethodGet {
|
||||
http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
|
||||
return
|
||||
}
|
||||
|
||||
w.Header().Set("Content-Type", "application/json")
|
||||
if err := json.NewEncoder(w).Encode(meta); err != nil {
|
||||
http.Error(w, "Failed to encode metadata", http.StatusInternalServerError)
|
||||
return
|
||||
}
|
||||
}
|
||||
|
||||
func (s *FakeAuthorizationServer) handleRegister(w http.ResponseWriter, r *http.Request) {
|
||||
if r.Method != http.MethodPost {
|
||||
http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
|
||||
return
|
||||
}
|
||||
var metadata oauthex.ClientRegistrationMetadata
|
||||
body, err := io.ReadAll(r.Body)
|
||||
if err != nil {
|
||||
http.Error(w, "failed to read request body", http.StatusBadRequest)
|
||||
return
|
||||
}
|
||||
if err := internaljson.Unmarshal(body, &metadata); err != nil {
|
||||
http.Error(w, "failed to parse request", http.StatusBadRequest)
|
||||
return
|
||||
}
|
||||
w.Header().Set("Content-Type", "application/json")
|
||||
w.WriteHeader(http.StatusCreated)
|
||||
clientID := rand.Text()
|
||||
ci := ClientInfo{
|
||||
Secret: rand.Text(),
|
||||
RedirectURIs: metadata.RedirectURIs,
|
||||
}
|
||||
s.clients[clientID] = ci
|
||||
metadata.TokenEndpointAuthMethod = "client_secret_basic"
|
||||
json.NewEncoder(w).Encode(&oauthex.ClientRegistrationResponse{
|
||||
ClientID: clientID,
|
||||
ClientSecret: ci.Secret,
|
||||
ClientRegistrationMetadata: metadata,
|
||||
})
|
||||
}
|
||||
|
||||
func (s *FakeAuthorizationServer) handleAuthorize(w http.ResponseWriter, r *http.Request) {
|
||||
if r.Method != http.MethodGet {
|
||||
http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
|
||||
return
|
||||
}
|
||||
clientID := r.URL.Query().Get("client_id")
|
||||
clientInfo, ok := s.clients[clientID]
|
||||
if !ok {
|
||||
http.Error(w, "unknown client_id", http.StatusBadRequest)
|
||||
return
|
||||
}
|
||||
|
||||
redirectURI := r.URL.Query().Get("redirect_uri")
|
||||
if redirectURI == "" {
|
||||
http.Error(w, "missing redirect_uri", http.StatusBadRequest)
|
||||
return
|
||||
}
|
||||
if !slices.Contains(clientInfo.RedirectURIs, redirectURI) {
|
||||
http.Error(w, "invalid redirect_uri", http.StatusBadRequest)
|
||||
return
|
||||
}
|
||||
codeChallenge := r.URL.Query().Get("code_challenge")
|
||||
if codeChallenge == "" {
|
||||
http.Error(w, "missing code_challenge", http.StatusBadRequest)
|
||||
return
|
||||
}
|
||||
code := rand.Text()
|
||||
s.codes[code] = codeInfo{
|
||||
CodeChallenge: codeChallenge,
|
||||
}
|
||||
|
||||
state := r.URL.Query().Get("state")
|
||||
|
||||
redirectURL := fmt.Sprintf("%s?code=%s&state=%s", redirectURI, code, state)
|
||||
http.Redirect(w, r, redirectURL, http.StatusFound)
|
||||
}
|
||||
|
||||
func (s *FakeAuthorizationServer) handleToken(w http.ResponseWriter, r *http.Request) {
|
||||
if err := r.ParseForm(); err != nil {
|
||||
http.Error(w, "failed to parse form", http.StatusBadRequest)
|
||||
return
|
||||
}
|
||||
if r.Method != http.MethodPost {
|
||||
http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
|
||||
return
|
||||
}
|
||||
if err := s.authenticateClient(r); err != nil {
|
||||
http.Error(w, err.Error(), http.StatusUnauthorized)
|
||||
return
|
||||
}
|
||||
if r.Form.Get("grant_type") != "authorization_code" {
|
||||
http.Error(w, "invalid grant_type", http.StatusBadRequest)
|
||||
return
|
||||
}
|
||||
code := r.Form.Get("code")
|
||||
if code == "" {
|
||||
http.Error(w, "missing code", http.StatusBadRequest)
|
||||
return
|
||||
}
|
||||
codeInfo, ok := s.codes[code]
|
||||
if !ok {
|
||||
http.Error(w, "unknown authorization code", http.StatusBadRequest)
|
||||
return
|
||||
}
|
||||
verifier := r.Form.Get("code_verifier")
|
||||
if verifier == "" {
|
||||
http.Error(w, "missing code_verifier", http.StatusBadRequest)
|
||||
return
|
||||
}
|
||||
sha := sha256.Sum256([]byte(verifier))
|
||||
expectedChallenge := base64.RawURLEncoding.EncodeToString(sha[:])
|
||||
if expectedChallenge != codeInfo.CodeChallenge {
|
||||
http.Error(w, "PKCE verification failed", http.StatusBadRequest)
|
||||
return
|
||||
}
|
||||
|
||||
w.Header().Set("Content-Type", "application/json")
|
||||
json.NewEncoder(w).Encode(map[string]interface{}{
|
||||
"access_token": "test_access_token",
|
||||
"token_type": "Bearer",
|
||||
"expires_in": 3600,
|
||||
})
|
||||
}
|
||||
|
||||
func (s *FakeAuthorizationServer) authenticateClient(r *http.Request) error {
|
||||
clientID, clientSecret, ok := r.BasicAuth()
|
||||
if !ok {
|
||||
clientID = r.Form.Get("client_id")
|
||||
clientSecret = r.Form.Get("client_secret")
|
||||
}
|
||||
|
||||
clientInfo, ok := s.clients[clientID]
|
||||
if !ok || clientInfo.Secret != clientSecret {
|
||||
return errors.New("client not found")
|
||||
}
|
||||
return nil
|
||||
}
|
||||
Loading…
Reference in a new issue