auth

Documentation

Overview

Package auth defines interfaces and structures for handling authentication and authorization within the MCP server, focusing initially on OAuth 2.1 JWTs.

Package auth provides interfaces, implementations, and hooks for handling authentication and authorization within the MCP server.

Package auth provides interfaces and structures for handling authentication and authorization within the MCP server. This file implements a TokenValidator based on JWTs and JWKS.

Index

• func ContextWithPrincipal(ctx context.Context, principal Principal) context.Context
• func ContextWithToken(ctx context.Context, token string) context.Context
• func NewAuthenticationHook(config AuthHookConfig) (hooks.BeforeHandleMessageHook, error)
• func TokenFromContext(ctx context.Context) (string, bool)
• type AllowAllPermissionChecker
  • func (c *AllowAllPermissionChecker) CheckPermission(ctx context.Context, principal Principal, method string, params interface{}) error
• type AuthHookConfig
• type JWKSConfig
• type JWKSTokenValidator
  • func NewJWKSTokenValidator(config JWKSConfig, client *http.Client) (*JWKSTokenValidator, error)
  • func (v *JWKSTokenValidator) ValidateToken(ctx context.Context, tokenString string) (Principal, error)
• type PermissionChecker
• type Principal
  • func PrincipalFromContext(ctx context.Context) (Principal, bool)
• type TokenValidator

Functions

func ContextWithPrincipal

func ContextWithPrincipal(ctx context.Context, principal Principal) context.Context

ContextWithPrincipal returns a new context with the given Principal embedded.

func ContextWithToken

func ContextWithToken(ctx context.Context, token string) context.Context

ContextWithToken returns a context embedding the token string. This should be called by the transport layer *before* Server.HandleMessage.

func NewAuthenticationHook

func NewAuthenticationHook(config AuthHookConfig) (hooks.BeforeHandleMessageHook, error)

NewAuthenticationHook creates a BeforeHandleMessageHook that performs token validation. It requires a configured TokenValidator.

func TokenFromContext

func TokenFromContext(ctx context.Context) (string, bool)

TokenFromContext extracts the token string from the context.

Types

type AllowAllPermissionChecker

type AllowAllPermissionChecker struct{}

AllowAllPermissionChecker is a simple implementation that grants all permissions. Useful for testing or servers that don't require fine-grained checks after authentication.

func (*AllowAllPermissionChecker) CheckPermission

func (c *AllowAllPermissionChecker) CheckPermission(ctx context.Context, principal Principal, method string, params interface{}) error

type AuthHookConfig

type AuthHookConfig struct {
	Validator TokenValidator // The configured token validator (e.g., JWKSTokenValidator)
	// Add other config as needed, e.g., how to extract token (header, param, etc.)
	TokenHeader string // e.g., "Authorization"
	TokenPrefix string // e.g., "Bearer "
}

AuthHookConfig holds configuration needed for the authentication hook.

type JWKSConfig

type JWKSConfig struct {
	// JWKSURL is the URL of the JSON Web Key Set endpoint. (Required)
	JWKSURL string
	// ExpectedIssuer is the required value for the 'iss' claim. (Optional)
	ExpectedIssuer string
	// ExpectedAudience is the required value for the 'aud' claim. (Optional)
	ExpectedAudience string
	// ClockSkew defines the acceptable time difference for validating expiry ('exp') and not before ('nbf') claims. Defaults to 0.
	ClockSkew time.Duration
	// RefreshInterval defines how often to refresh the JWK set from the URL. Defaults to 1 hour.
	RefreshInterval time.Duration
}

JWKSConfig holds configuration for the JWKS-based validator.

type JWKSTokenValidator

type JWKSTokenValidator struct {
	// contains filtered or unexported fields
}

JWKSTokenValidator implements the TokenValidator interface using a JWKS endpoint.

func NewJWKSTokenValidator

func NewJWKSTokenValidator(config JWKSConfig, client *http.Client) (*JWKSTokenValidator, error)

NewJWKSTokenValidator creates a new validator instance.

func (*JWKSTokenValidator) ValidateToken

func (v *JWKSTokenValidator) ValidateToken(ctx context.Context, tokenString string) (Principal, error)

ValidateToken implements the TokenValidator interface.

type PermissionChecker

type PermissionChecker interface {
	// CheckPermission verifies if the given principal has the necessary permissions
	// for the specified MCP method and parameters.
	// It should return nil if authorized, or an error (e.g., a *protocol.ErrorPayload
	// with ErrorCodePermissionDenied) if not.
	CheckPermission(ctx context.Context, principal Principal, method string, params interface{}) error
}

PermissionChecker defines the interface for checking if a principal is authorized to perform a specific MCP action.

type Principal

type Principal interface {
	// GetClaims returns the claims associated with the principal.
	// The specific type of claims depends on the token format (e.g., map[string]interface{} for JWT).
	GetClaims() interface{}
	// GetSubject returns a unique identifier for the principal (e.g., 'sub' claim from JWT).
	GetSubject() string
}

Principal represents the authenticated entity (e.g., user, client application) after successful token validation. It can carry claims from the token.

func PrincipalFromContext

func PrincipalFromContext(ctx context.Context) (Principal, bool)

PrincipalFromContext retrieves the Principal from the context, if present.

type TokenValidator

type TokenValidator interface {
	// ValidateToken attempts to validate the given token string.
	// It returns the authenticated Principal if validation is successful,
	// or an error (potentially a *protocol.ErrorPayload for specific JSON-RPC errors) otherwise.
	ValidateToken(ctx context.Context, tokenString string) (Principal, error)
}

TokenValidator defines the interface for validating access tokens. Implementations will handle specific token types (e.g., JWT) and validation methods (e.g., JWKS).