Documentation
¶
Overview ¶
Package server provides OAuth 2.1 protection for the Muster Server.
This package implements ADR 005 (OAuth Protection for Muster Server), allowing the Muster Server to act as an OAuth Resource Server. When enabled, all MCP endpoints require valid access tokens from authenticated clients.
Architecture ¶
The server package integrates with the mcp-oauth library to provide:
- OAuth 2.1 server with mandatory PKCE
- Dynamic client registration (RFC 7591)
- Client ID Metadata Documents (CIMD) per MCP 2025-11-25 spec
- Token validation middleware for protecting MCP endpoints
- Multiple provider support (Dex OIDC, Google OAuth)
- Token storage backends (in-memory, Valkey/Redis)
Integration ¶
The OAuth server wraps the existing aggregator HTTP handler, adding authentication and authorization before requests reach MCP endpoints.
┌─────────────────────────────────────────────────────────────┐ │ Muster Server │ │ │ │ [ OAuth Middleware (Resource Server) ] │ │ Validates Token from Agent │ │ │ │ │ ▼ │ │ [ Aggregator / Tool Handler ] │ │ │ │ │ ▼ │ │ [ OAuth Proxy (Client) ] │ │ Injects Token for Remote MCPs │ └─────────────────────────────────────────────────────────────┘
Usage ¶
To enable OAuth server protection, configure the aggregator with:
aggregator:
oauthServer:
enabled: true
baseUrl: "https://muster.example.com"
provider: "dex"
dex:
issuerUrl: "https://dex.example.com"
clientId: "muster-server"
clientSecret: "${DEX_CLIENT_SECRET}"
Endpoints ¶
When OAuth server is enabled, the following endpoints are exposed:
- /.well-known/oauth-authorization-server - Authorization Server Metadata (RFC 8414)
- /.well-known/oauth-protected-resource - Protected Resource Metadata (RFC 9728)
- /oauth/register - Dynamic Client Registration (RFC 7591)
- /oauth/authorize - OAuth Authorization
- /oauth/token - Token Endpoint
- /oauth/callback - OAuth Callback (from IdP)
- /oauth/revoke - Token Revocation (RFC 7009)
- /mcp - Protected MCP endpoint (requires Bearer token)
Index ¶
- Constants
- func ContextWithAccessToken(ctx context.Context, idToken string) context.Context
- func ContextWithUpstreamAccessToken(ctx context.Context, accessToken string) context.Context
- func GetAccessTokenFromContext(ctx context.Context) (string, bool)
- func GetIDToken(token *oauth2.Token) string
- func GetUpstreamAccessTokenFromContext(ctx context.Context) (string, bool)
- type OAuthHTTPServer
- type UserInfo
Constants ¶
const ( // OAuthProviderDex is the Dex OIDC provider type. OAuthProviderDex = "dex" // OAuthProviderGoogle is the Google OAuth provider type. OAuthProviderGoogle = "google" // DefaultAccessTokenTTL is the configured TTL for access tokens (30 minutes). // This is intentionally set to match the Dex idTokens expiry (30m) so that // capTokenExpiry in mcp-oauth doesn't need to cap it further. If Dex's // idTokens expiry is shorter than this value, capTokenExpiry will // automatically reduce the effective TTL to match the provider's token lifetime. DefaultAccessTokenTTL = 30 * time.Minute // DefaultRefreshTokenTTL is the server-side TTL for refresh tokens. // Derived from pkgoauth.DefaultSessionDuration to keep server and CLI in sync. // Aligned with Dex's absoluteLifetime (720h = 30 days). Note: muster uses a // rolling TTL (reset on each rotation), while Dex's absoluteLifetime is // measured from original issuance and does NOT reset. DefaultRefreshTokenTTL = pkgoauth.DefaultSessionDuration // DefaultIPRateLimit is the default rate limit for requests per IP (requests/second). DefaultIPRateLimit = 10 // DefaultIPBurst is the default burst size for IP rate limiting. DefaultIPBurst = 20 // DefaultUserRateLimit is the default rate limit for authenticated users (requests/second). DefaultUserRateLimit = 100 // DefaultUserBurst is the default burst size for authenticated user rate limiting. DefaultUserBurst = 200 // DefaultMaxClientsPerIP is the default maximum number of clients per IP address. DefaultMaxClientsPerIP = 10 // DefaultReadHeaderTimeout is the default timeout for reading request headers. DefaultReadHeaderTimeout = 10 * time.Second // DefaultWriteTimeout is the default timeout for writing responses. DefaultWriteTimeout = 120 * time.Second // DefaultIdleTimeout is the default idle timeout for keepalive connections. DefaultIdleTimeout = 120 * time.Second // DefaultSessionTrackerTTL is how long session entries are kept before cleanup. // Sessions inactive for longer than this will be removed to prevent memory leaks. DefaultSessionTrackerTTL = 24 * time.Hour // DefaultSessionTrackerCleanupInterval is how often the session tracker cleanup runs. DefaultSessionTrackerCleanupInterval = 1 * time.Hour )
Variables ¶
This section is empty.
Functions ¶
func ContextWithAccessToken ¶
ContextWithAccessToken creates a context with the given OAuth ID token. This is used to pass the user's OAuth ID token for downstream authentication (e.g., to remote MCP servers).
func ContextWithUpstreamAccessToken ¶
ContextWithUpstreamAccessToken creates a context with the upstream IdP's access token. This is used for detecting token refresh - the access token changes on refresh, even when the ID token is preserved. By tracking the access token, we can detect both re-authentication (new ID token) and token refresh (new access token).
func GetAccessTokenFromContext ¶
GetAccessTokenFromContext retrieves the OAuth ID token from the context. Returns the ID token and true if present, or empty string and false if not available.
func GetIDToken ¶
GetIDToken extracts the ID token from an OAuth2 token. OIDC providers include an id_token in the Extra data. Kubernetes OIDC authentication requires the ID token, not the access token.
Types ¶
type OAuthHTTPServer ¶
type OAuthHTTPServer struct {
// contains filtered or unexported fields
}
OAuthHTTPServer wraps an MCP HTTP handler with OAuth 2.1 authentication. It provides both OAuth server functionality (authorization, token issuance) and resource server protection (token validation middleware).
func NewOAuthHTTPServer ¶
func NewOAuthHTTPServer(cfg config.OAuthServerConfig, mcpHandler http.Handler, debug bool) (*OAuthHTTPServer, error)
NewOAuthHTTPServer creates a new OAuth-enabled HTTP server that wraps the provided MCP handler with authentication protection.
func (*OAuthHTTPServer) CreateMux ¶
func (s *OAuthHTTPServer) CreateMux() http.Handler
CreateMux creates an HTTP mux that routes to both OAuth and MCP handlers. The MCP endpoints are protected by the OAuth ValidateToken middleware.
func (*OAuthHTTPServer) GetOAuthHandler ¶
func (s *OAuthHTTPServer) GetOAuthHandler() *oauth.Handler
GetOAuthHandler returns the OAuth handler for testing or direct access.
func (*OAuthHTTPServer) GetOAuthServer ¶
func (s *OAuthHTTPServer) GetOAuthServer() *oauth.Server
GetOAuthServer returns the underlying OAuth server for testing or direct access.
func (*OAuthHTTPServer) GetTokenStore ¶
func (s *OAuthHTTPServer) GetTokenStore() storage.TokenStore
GetTokenStore returns the token store for downstream OAuth passthrough.
Source Files