discovery

Documentation

Overview

Package discovery provides authentication discovery utilities for detecting authentication requirements from remote servers.

Supported Authentication Types: - OAuth 2.0 with PKCE (Proof Key for Code Exchange) - OIDC (OpenID Connect) discovery - Manual OAuth endpoint configuration - RFC 9728 Protected Resource Metadata

Index

• Constants
• func DeriveIssuerFromRealm(realm string) string
• func DeriveIssuerFromURL(remoteURL string) string
• func ExtractParameter(params, paramName string) string
• func FetchResourceMetadata(ctx context.Context, metadataURL string) (*auth.RFC9728AuthInfo, error)
• type AuthInfo
  • func DetectAuthenticationFromServer(ctx context.Context, targetURI string, config *Config) (*AuthInfo, error)
  • func ParseWWWAuthenticate(header string) (*AuthInfo, error)
• type AuthServerInfo
  • func ValidateAndDiscoverAuthServer(ctx context.Context, potentialIssuer string) (*AuthServerInfo, error)
• type Config
  • func DefaultDiscoveryConfig() *Config
• type OAuthFlowConfig
• type OAuthFlowResult
  • func PerformOAuthFlow(ctx context.Context, issuer string, config *OAuthFlowConfig) (*OAuthFlowResult, error)

Constants

const (
	DefaultOAuthTimeout      = 5 * time.Minute
	DefaultHTTPTimeout       = 30 * time.Second
	DefaultAuthDetectTimeout = 10 * time.Second
	MaxRetryAttempts         = 3
	RetryBaseDelay           = 2 * time.Second
	MaxResponseBodyDrain     = 1 * 1024 * 1024 // 1 MB - limit response body draining to prevent resource exhaustion
)

Default timeout constants for authentication operations

Functions

func DeriveIssuerFromRealm

func DeriveIssuerFromRealm(realm string) string

DeriveIssuerFromRealm attempts to derive the OAuth issuer from the realm parameter According to RFC 8414, the issuer MUST be a URL using the "https" scheme with no query or fragment

func DeriveIssuerFromURL

func DeriveIssuerFromURL(remoteURL string) string

DeriveIssuerFromURL attempts to derive the OAuth issuer from the remote URL using general patterns

func ExtractParameter

func ExtractParameter(params, paramName string) string

ExtractParameter extracts a parameter value from an authentication header Handles both quoted and unquoted values according to RFC 2617 and RFC 6750

func FetchResourceMetadata

func FetchResourceMetadata(ctx context.Context, metadataURL string) (*auth.RFC9728AuthInfo, error)

FetchResourceMetadata as specified in RFC 9728

Types

type AuthInfo

type AuthInfo struct {
	Realm            string
	Type             string
	ResourceMetadata string
	Error            string
	ErrorDescription string
}

AuthInfo contains authentication information extracted from WWW-Authenticate header

func DetectAuthenticationFromServer

func DetectAuthenticationFromServer(ctx context.Context, targetURI string, config *Config) (*AuthInfo, error)

DetectAuthenticationFromServer attempts to detect authentication requirements from the target server

func ParseWWWAuthenticate

func ParseWWWAuthenticate(header string) (*AuthInfo, error)

ParseWWWAuthenticate parses the WWW-Authenticate header to extract authentication information Supports multiple authentication schemes and complex header formats

type AuthServerInfo

type AuthServerInfo struct {
	Issuer               string
	AuthorizationURL     string
	TokenURL             string
	RegistrationEndpoint string
}

AuthServerInfo contains information about a validated authorization server

func ValidateAndDiscoverAuthServer

func ValidateAndDiscoverAuthServer(ctx context.Context, potentialIssuer string) (*AuthServerInfo, error)

ValidateAndDiscoverAuthServer attempts to validate if a URL is an authorization server and discover its actual issuer by fetching its metadata. This handles the case where the URL used to fetch metadata differs from the actual issuer (e.g., Stripe's case where https://mcp.stripe.com hosts metadata for https://marketplace.stripe.com)

type Config

type Config struct {
	Timeout               time.Duration
	TLSHandshakeTimeout   time.Duration
	ResponseHeaderTimeout time.Duration
	EnablePOSTDetection   bool // Whether to try POST requests for detection
}

Config holds configuration for authentication discovery

func DefaultDiscoveryConfig

func DefaultDiscoveryConfig() *Config

DefaultDiscoveryConfig returns a default discovery configuration

type OAuthFlowConfig

type OAuthFlowConfig struct {
	ClientID             string
	ClientSecret         string
	AuthorizeURL         string // Manual OAuth endpoint (optional)
	TokenURL             string // Manual OAuth endpoint (optional)
	RegistrationEndpoint string // Manual registration endpoint (optional)
	Scopes               []string
	CallbackPort         int
	Timeout              time.Duration
	SkipBrowser          bool
	Resource             string // RFC 8707 resource indicator (optional)
	OAuthParams          map[string]string
}

OAuthFlowConfig contains configuration for performing OAuth flows

type OAuthFlowResult

type OAuthFlowResult struct {
	TokenSource oauth2.TokenSource
	Config      *oauth.Config
}

OAuthFlowResult contains the result of an OAuth flow

func PerformOAuthFlow

func PerformOAuthFlow(ctx context.Context, issuer string, config *OAuthFlowConfig) (*OAuthFlowResult, error)

PerformOAuthFlow performs an OAuth authentication flow with the given configuration