Documentation
¶
Overview ¶
Package remote provides authentication handling for remote MCP servers.
This package implements OAuth/OIDC-based authentication with automatic discovery support for remote MCP servers. It handles:
- OAuth issuer discovery (RFC 8414)
- Protected resource metadata (RFC 9728)
- OAuth flow execution (PKCE-based)
- Token source creation for HTTP transports
The main entry point is Handler.Authenticate() which takes a remote URL and performs all necessary discovery and authentication steps.
Configuration is defined in pkg/runner.RemoteAuthConfig as part of the runner's RunConfig structure.
Index ¶
Constants ¶
const BearerTokenEnvVarName = "TOOLHIVE_REMOTE_AUTH_BEARER_TOKEN"
BearerTokenEnvVarName is the environment variable name used for bearer token authentication. The bearer token will be read from this environment variable if not provided via flag or file. #nosec G101 - this is an environment variable name, not a credential
const DefaultCallbackPort = 8666
DefaultCallbackPort is the default port for the OAuth callback server
Variables ¶
This section is empty.
Functions ¶
func CreateTokenSourceFromCached ¶ added in v0.8.1
func CreateTokenSourceFromCached( config *oauth2.Config, refreshToken string, expiry time.Time, ) oauth2.TokenSource
CreateTokenSourceFromCached creates an oauth2.TokenSource from a cached refresh token. The returned token source will immediately refresh to get a new access token, then automatically refresh when it expires.
func DefaultResourceIndicator ¶
DefaultResourceIndicator derives the resource indicator (RFC 8707) from the remote server URL. This function should only be called when the user has not explicitly provided a resource indicator. If the resource indicator cannot be derived, it returns an empty string.
Types ¶
type BearerTokenSource ¶ added in v0.6.17
type BearerTokenSource struct {
// contains filtered or unexported fields
}
BearerTokenSource implements oauth2.TokenSource for static bearer tokens. It returns a token with the bearer token value as the access token.
func NewBearerTokenSource ¶ added in v0.6.17
func NewBearerTokenSource(bearerToken string) *BearerTokenSource
NewBearerTokenSource creates a new BearerTokenSource with the provided bearer token.
type Config ¶
type Config struct {
ClientID string `json:"client_id,omitempty" yaml:"client_id,omitempty"`
ClientSecret string `json:"client_secret,omitempty" yaml:"client_secret,omitempty"`
ClientSecretFile string `json:"client_secret_file,omitempty" yaml:"client_secret_file,omitempty"`
Scopes []string `json:"scopes,omitempty" yaml:"scopes,omitempty"`
SkipBrowser bool `json:"skip_browser,omitempty" yaml:"skip_browser,omitempty"`
Timeout time.Duration `json:"timeout,omitempty" yaml:"timeout,omitempty" swaggertype:"string" example:"5m"`
CallbackPort int `json:"callback_port,omitempty" yaml:"callback_port,omitempty"`
UsePKCE bool `json:"use_pkce" yaml:"use_pkce"`
// Resource is the OAuth 2.0 resource indicator (RFC 8707).
Resource string `json:"resource,omitempty" yaml:"resource,omitempty"`
// OAuth endpoint configuration (from registry)
Issuer string `json:"issuer,omitempty" yaml:"issuer,omitempty"`
AuthorizeURL string `json:"authorize_url,omitempty" yaml:"authorize_url,omitempty"`
TokenURL string `json:"token_url,omitempty" yaml:"token_url,omitempty"`
// Headers for HTTP requests
Headers []*registry.Header `json:"headers,omitempty" yaml:"headers,omitempty"`
// Environment variables for the client
EnvVars []*registry.EnvVar `json:"env_vars,omitempty" yaml:"env_vars,omitempty"`
// OAuth parameters for server-specific customization
OAuthParams map[string]string `json:"oauth_params,omitempty" yaml:"oauth_params,omitempty"`
// Bearer token configuration (alternative to OAuth)
BearerToken string `json:"bearer_token,omitempty" yaml:"bearer_token,omitempty"`
BearerTokenFile string `json:"bearer_token_file,omitempty" yaml:"bearer_token_file,omitempty"`
// Cached OAuth token reference for persistence across restarts.
// The refresh token is stored securely in the secret manager, and this field
// contains the reference to retrieve it (e.g., "OAUTH_REFRESH_TOKEN_workload").
// This enables session restoration without requiring a new browser-based login.
CachedRefreshTokenRef string `json:"cached_refresh_token_ref,omitempty" yaml:"cached_refresh_token_ref,omitempty"`
CachedTokenExpiry time.Time `json:"cached_token_expiry,omitempty" yaml:"cached_token_expiry,omitempty"`
}
Config holds authentication configuration for remote MCP servers. Supports OAuth/OIDC-based authentication with automatic discovery.
func (*Config) ClearCachedTokens ¶ added in v0.8.1
func (c *Config) ClearCachedTokens()
ClearCachedTokens removes any cached OAuth token references from the config. Note: This does not delete the actual secret from the secret manager.
func (*Config) HasValidCachedTokens ¶ added in v0.8.1
HasValidCachedTokens returns true if the config has a cached token reference that can be used to create a TokenSource without requiring a new OAuth flow. Note: This only checks if a refresh token reference exists, not if the token is actually valid. The actual validity will be determined when the token is used.
func (*Config) UnmarshalJSON ¶
UnmarshalJSON implements custom JSON unmarshaling for backward compatibility This handles both the old PascalCase format and the new snake_case format
type Handler ¶
type Handler struct {
// contains filtered or unexported fields
}
Handler handles authentication for remote MCP servers. Supports OAuth/OIDC-based authentication with automatic discovery.
func NewHandler ¶
NewHandler creates a new remote authentication handler
func (*Handler) Authenticate ¶
Authenticate is the main entry point for remote MCP server authentication
func (*Handler) SetSecretProvider ¶ added in v0.8.1
SetSecretProvider sets the secret provider used to store and retrieve cached tokens.
func (*Handler) SetTokenPersister ¶ added in v0.8.1
func (h *Handler) SetTokenPersister(persister TokenPersister)
SetTokenPersister sets a callback function that will be called whenever OAuth tokens are refreshed. This enables token persistence across restarts.
type PersistingTokenSource ¶ added in v0.8.1
type PersistingTokenSource struct {
// contains filtered or unexported fields
}
PersistingTokenSource wraps an oauth2.TokenSource and persists tokens whenever they are refreshed. This enables session restoration across workload restarts without requiring a new browser-based OAuth flow.
func NewPersistingTokenSource ¶ added in v0.8.1
func NewPersistingTokenSource(source oauth2.TokenSource, persister TokenPersister) *PersistingTokenSource
NewPersistingTokenSource creates a new PersistingTokenSource that wraps the given token source and calls the persister function whenever tokens are refreshed.
type TokenPersister ¶ added in v0.8.1
TokenPersister is a callback function that persists OAuth refresh tokens. It is called whenever tokens are refreshed. Only the refresh token is persisted since the access token can be regenerated from it.
Source Files