Documentation
¶
Index ¶
- func ContextWithScopes(ctx context.Context, scopes []string) context.Context
- func ContextWithSessionID(ctx context.Context, sessionID string) context.Context
- func ContextWithUserInfo(ctx context.Context, userInfo *providers.UserInfo) context.Context
- func DPoPMiddleware(replayCache server.DPoPReplayCache, nonceProvider server.DPoPNonceProvider, ...) func(http.Handler) http.Handler
- func InterstitialAppName(ctx context.Context) string
- func InterstitialRedirectURL(ctx context.Context) string
- func ScopesFromContext(ctx context.Context) ([]string, bool)
- func SessionIDFromContext(ctx context.Context) (string, bool)
- func UserInfoFromContext(ctx context.Context) (*providers.UserInfo, bool)
- type Handler
- func (h *Handler) DPoPMiddleware() func(http.Handler) http.Handler
- func (h *Handler) RegisterAuthorizationServerMetadataRoutes(mux *http.ServeMux)
- func (h *Handler) RegisterOAuthRoutes(mux *http.ServeMux, opts OAuthRoutesOptions)
- func (h *Handler) RegisterProtectedResourceMetadataRoutes(mux *http.ServeMux, mcpPath string)
- func (h *Handler) ServeAuthorization(w http.ResponseWriter, r *http.Request)
- func (h *Handler) ServeAuthorizationServerMetadata(w http.ResponseWriter, r *http.Request)
- func (h *Handler) ServeCallback(w http.ResponseWriter, r *http.Request)
- func (h *Handler) ServeClientManagement(w http.ResponseWriter, r *http.Request)
- func (h *Handler) ServeClientRegistration(w http.ResponseWriter, r *http.Request)
- func (h *Handler) ServeJWKS(w http.ResponseWriter, r *http.Request)
- func (h *Handler) ServeOpenIDConfiguration(w http.ResponseWriter, r *http.Request)
- func (h *Handler) ServePreflightRequest(w http.ResponseWriter, r *http.Request)
- func (h *Handler) ServeProtectedResourceMetadata(w http.ResponseWriter, r *http.Request)
- func (h *Handler) ServeToken(w http.ResponseWriter, r *http.Request)
- func (h *Handler) ServeTokenIntrospection(w http.ResponseWriter, r *http.Request)
- func (h *Handler) ServeTokenRevocation(w http.ResponseWriter, r *http.Request)
- func (h *Handler) ServeUserInfo(w http.ResponseWriter, r *http.Request)
- func (h *Handler) ValidateToken(next http.Handler) http.Handler
- type OAuthRoutesOptions
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ContextWithScopes ¶
ContextWithScopes carries the scopes granted to the access token on the current request. Set by Handler.ValidateToken from the token's metadata.
func ContextWithSessionID ¶
ContextWithSessionID creates a context carrying a stable session identifier derived from the OAuth refresh token family. This allows consumers to associate per-session state with the current authenticated request.
func ContextWithUserInfo ¶
ContextWithUserInfo creates a context with the given user info. This is useful for testing code that depends on authenticated user context.
WARNING: This function should ONLY be used for testing. In production, user info should ONLY be set by the ValidateToken middleware after proper token validation. Using this function to bypass authentication in production code is a security vulnerability.
Note: if userInfo is nil, UserInfoFromContext will return (nil, true). Callers should check both the ok value and nil-ness of the returned userInfo.
func DPoPMiddleware ¶ added in v0.2.150
func DPoPMiddleware(replayCache server.DPoPReplayCache, nonceProvider server.DPoPNonceProvider, trustedProxies []*net.IPNet) func(http.Handler) http.Handler
DPoPMiddleware returns an http.Handler middleware that enforces DPoP proof validation when the request carries an "Authorization: DPoP <token>" header (RFC 9449 §7).
Requests with "Authorization: Bearer <token>" are passed through unchanged. Requests with no Authorization header are also passed through; authentication is the responsibility of the next handler.
nonceProvider is optional: when non-nil, every DPoP proof must carry a currently-valid server-issued nonce (RFC 9449 §8). On failure the middleware responds 401 with error=use_dpop_nonce and a DPoP-Nonce response header.
trustedProxies lists CIDRs whose X-Forwarded-Proto and X-Forwarded-Host headers are trusted for htu reconstruction. Pass nil when the server is directly exposed.
When replayCache is nil the middleware falls back to an in-process cache and logs a warning. In multi-pod deployments this silently degrades to per-pod replay protection; pass a shared cache via WithDPoPReplayCache to avoid this. Prefer Handler.DPoPMiddleware when using handler.Handler — it reads the cache from the server so split-wiring is impossible.
func InterstitialAppName ¶
InterstitialAppName extracts the application name from the request context. This is used by custom interstitial handlers to get the human-readable app name. Returns empty string if not found in context.
func InterstitialRedirectURL ¶
InterstitialRedirectURL extracts the OAuth redirect URL from the request context. This is used by custom interstitial handlers to get the redirect URL. Returns empty string if not found in context.
func ScopesFromContext ¶
ScopesFromContext returns the scopes granted to the access token on the current request. The bool is false when no scopes are present in the context.
func SessionIDFromContext ¶
SessionIDFromContext retrieves the session identifier from the request context. Returns the session ID and true if present and non-empty, or ("", false) otherwise.
Types ¶
type Handler ¶
type Handler struct {
// contains filtered or unexported fields
}
Handler is a thin HTTP adapter for the OAuth Server. It handles HTTP requests and delegates to the Server for business logic.
func (*Handler) DPoPMiddleware ¶ added in v0.2.169
DPoPMiddleware returns an http.Handler middleware that enforces DPoP proof validation, reading the replay cache, nonce provider, and trusted proxy CIDRs from the server. This eliminates the split-wiring problem of the package-level DPoPMiddleware function: both the issuance path and the resource path share the same cache instance automatically.
func (*Handler) RegisterAuthorizationServerMetadataRoutes ¶
RegisterAuthorizationServerMetadataRoutes registers all Authorization Server Metadata discovery routes. This supports multi-tenant deployments with path-based issuers per MCP 2025-11-25.
For issuer URLs with path components (e.g., https://auth.example.com/tenant1), registers:
- Path insertion OAuth: /.well-known/oauth-authorization-server/tenant1
- Path insertion OIDC: /.well-known/openid-configuration/tenant1
- Path appending OIDC: /tenant1/.well-known/openid-configuration
For issuer URLs without path components (e.g., https://auth.example.com), registers:
- Standard OAuth: /.well-known/oauth-authorization-server
- Standard OIDC: /.well-known/openid-configuration
Example usage:
// Single-tenant: Configure issuer without path
config := &ServerConfig{
Issuer: "https://auth.example.com",
}
// Registers: /.well-known/oauth-authorization-server
// /.well-known/openid-configuration
handler.RegisterAuthorizationServerMetadataRoutes(mux)
// Multi-tenant: Configure issuer with path
config := &ServerConfig{
Issuer: "https://auth.example.com/tenant1",
}
// Registers: /.well-known/oauth-authorization-server/tenant1
// /.well-known/openid-configuration/tenant1
// /tenant1/.well-known/openid-configuration
// (plus standard endpoints for backward compatibility)
handler.RegisterAuthorizationServerMetadataRoutes(mux)
func (*Handler) RegisterOAuthRoutes ¶
func (h *Handler) RegisterOAuthRoutes(mux *http.ServeMux, opts OAuthRoutesOptions)
RegisterOAuthRoutes registers the OAuth flow endpoints on mux and, when opts.IncludeMetadata is true (the default), also registers the Protected Resource Metadata and Authorization Server Metadata routes via the two existing Register*Routes helpers.
Routes registered (all under /oauth, paths fixed by the Config endpoint builders):
- /oauth/authorize, /oauth/callback, /oauth/token, /oauth/revoke, /oauth/register — always registered.
- /oauth/introspect — only when Config.EnableIntrospectionEndpoint is true. ServeTokenIntrospection does not self-gate on that flag, so registering it unconditionally would expose an endpoint the operator disabled in config.
A customizable prefix was considered and rejected — [Config.AuthorizationEndpoint], [Config.TokenEndpoint], and the other metadata builders hardcode the /oauth prefix when constructing the issuer-scoped URLs that appear in metadata. A custom prefix would make the routes register at one URL while metadata advertised a different one. Consumers needing a custom prefix must wire the individual Serve* methods by hand, at which point they also need to override metadata advertisement.
Replaces the five-line `mux.HandleFunc("/oauth/...", handler.Serve...)` block every consumer writes today:
handler.RegisterOAuthRoutes(mux, oauth.OAuthRoutesOptions{
MCPPath: "/mcp",
IncludeMetadata: true,
})
func (*Handler) RegisterProtectedResourceMetadataRoutes ¶
RegisterProtectedResourceMetadataRoutes registers all Protected Resource Metadata discovery routes. It registers the root endpoint and optional sub-path endpoints based on configuration.
Route registration is done for:
- Root endpoint: /.well-known/oauth-protected-resource (always registered)
- Explicit mcpPath endpoint if provided (backward compatibility)
- All paths from ResourceMetadataByPath configuration (MCP 2025-11-25)
Security: This function validates all paths to prevent path traversal attacks and DoS through excessively long paths. Invalid paths are logged and skipped.
Example usage:
// Legacy single-path registration handler.RegisterProtectedResourceMetadataRoutes(mux, "/mcp") // With per-path configuration (new in MCP 2025-11-25) // Configure in server.Config.ResourceMetadataByPath, then: handler.RegisterProtectedResourceMetadataRoutes(mux, "") // This registers routes for all configured paths automatically
func (*Handler) ServeAuthorization ¶
func (h *Handler) ServeAuthorization(w http.ResponseWriter, r *http.Request)
ServeAuthorization handles OAuth authorization requests
func (*Handler) ServeAuthorizationServerMetadata ¶
func (h *Handler) ServeAuthorizationServerMetadata(w http.ResponseWriter, r *http.Request)
ServeAuthorizationServerMetadata serves RFC 8414 Authorization Server Metadata
func (*Handler) ServeCallback ¶
func (h *Handler) ServeCallback(w http.ResponseWriter, r *http.Request)
ServeCallback handles the OAuth provider callback
func (*Handler) ServeClientManagement ¶ added in v0.2.145
func (h *Handler) ServeClientManagement(w http.ResponseWriter, r *http.Request)
ServeClientManagement handles RFC 7592 client management requests:
GET /oauth/register/{client_id} — read registration
PUT /oauth/register/{client_id} — replace + rotate registration token
DELETE /oauth/register/{client_id} — remove client
func (*Handler) ServeClientRegistration ¶
func (h *Handler) ServeClientRegistration(w http.ResponseWriter, r *http.Request)
ServeClientRegistration handles dynamic client registration (RFC 7591)
func (*Handler) ServeJWKS ¶
func (h *Handler) ServeJWKS(w http.ResponseWriter, r *http.Request)
ServeJWKS publishes the public half of the access-token signing key as a JSON Web Key Set per RFC 7517. Returns 404 when the server is configured for opaque-mode access tokens — the endpoint exists but advertising nothing is the honest response.
Cache-Control is set to one hour: keys rotate manually (operator changes AccessTokenSigningKeyID and restarts), and verifiers caching for an hour is the conventional middle ground between churn and freshness.
func (*Handler) ServeOpenIDConfiguration ¶
func (h *Handler) ServeOpenIDConfiguration(w http.ResponseWriter, r *http.Request)
ServeOpenIDConfiguration handles OpenID Connect Discovery 1.0 requests. Returns the same metadata as the AS-metadata endpoint per RFC 8414 §5.
func (*Handler) ServePreflightRequest ¶
func (h *Handler) ServePreflightRequest(w http.ResponseWriter, r *http.Request)
ServePreflightRequest handles CORS preflight (OPTIONS) requests. Required for non-simple requests (POST with JSON, custom headers, etc.).
func (*Handler) ServeProtectedResourceMetadata ¶
func (h *Handler) ServeProtectedResourceMetadata(w http.ResponseWriter, r *http.Request)
ServeProtectedResourceMetadata serves RFC 9728 Protected Resource Metadata with support for path-specific metadata discovery per MCP 2025-11-25.
The handler extracts the resource path from the request URL and looks up path-specific configuration in ResourceMetadataByPath. If a match is found, path-specific metadata is returned; otherwise, default server-wide metadata is used.
Path matching uses longest-prefix matching. For example, given paths "/mcp/files" and "/mcp/files/admin", a request for "/mcp/files/admin/users" would match "/mcp/files/admin".
func (*Handler) ServeToken ¶
func (h *Handler) ServeToken(w http.ResponseWriter, r *http.Request)
ServeToken handles the OAuth token endpoint
func (*Handler) ServeTokenIntrospection ¶
func (h *Handler) ServeTokenIntrospection(w http.ResponseWriter, r *http.Request)
ServeTokenIntrospection handles the RFC 7662 token introspection endpoint This allows resource servers to validate access tokens Security: Requires client authentication to prevent token scanning attacks
func (*Handler) ServeTokenRevocation ¶
func (h *Handler) ServeTokenRevocation(w http.ResponseWriter, r *http.Request)
ServeTokenRevocation handles the RFC 7009 token revocation endpoint
func (*Handler) ServeUserInfo ¶
func (h *Handler) ServeUserInfo(w http.ResponseWriter, r *http.Request)
ServeUserInfo handles the OIDC UserInfo endpoint (OIDC Core 1.0 §5.3). Accepts GET and POST. The Handler.ValidateToken middleware authenticates the bearer access token and stashes the resolved providers.UserInfo and granted scopes in the request context; this handler renders the claims gated by those scopes.
The `openid` scope is REQUIRED to access the endpoint. The `sub` claim is always returned. `profile`, `email`, and `groups` scopes gate the corresponding claim groups.
type OAuthRoutesOptions ¶
type OAuthRoutesOptions struct {
// MCPPath is forwarded to RegisterProtectedResourceMetadataRoutes for
// backward compatibility with single-path consumers. Kept because a few
// examples still pass it, but prefer configuring
// [Config.ResourceMetadataByPath] instead — when that map is non-empty,
// MCPPath is ignored (with a single warn log at registration time so the
// conflict is visible).
MCPPath string
// IncludeMetadata controls whether the two discovery bundles
// (Protected Resource Metadata per RFC 9728 and Authorization Server
// Metadata per RFC 8414) are registered alongside the OAuth flow
// endpoints. Default true — this is what every consumer today does by
// hand.
IncludeMetadata bool
}
OAuthRoutesOptions controls the bundle registered by Handler.RegisterOAuthRoutes.
Source Files