Documentation
¶
Overview ¶
Package strategies provides authentication strategy implementations for Virtual MCP Server.
Package strategies provides authentication strategy implementations for Virtual MCP Server.
Index ¶
Constants ¶
const ( // StrategyTypeUnauthenticated identifies the unauthenticated strategy. // This strategy performs no authentication and is used when a backend // requires no authentication. StrategyTypeUnauthenticated = "unauthenticated" // StrategyTypeHeaderInjection identifies the header injection strategy. // This strategy injects a static header value into request headers. StrategyTypeHeaderInjection = "header_injection" // StrategyTypeTokenExchange identifies the token exchange strategy. // This strategy exchanges an incoming token for a new token to use // when authenticating to the backend service. StrategyTypeTokenExchange = "token_exchange" )
Strategy type identifiers used to identify authentication strategies.
const ( // MetadataHeaderName is the key for the HTTP header name in metadata. // Used by HeaderInjectionStrategy to identify which header to inject. MetadataHeaderName = "header_name" // MetadataHeaderValue is the key for the HTTP header value in metadata. // Used by HeaderInjectionStrategy to identify the value to inject. MetadataHeaderValue = "header_value" )
Metadata key names used in strategy configurations.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type HeaderInjectionStrategy ¶
type HeaderInjectionStrategy struct{}
HeaderInjectionStrategy injects a static header value into request headers. This is a general-purpose strategy that can inject any header with any value, commonly used for API keys, bearer tokens, or custom authentication headers.
The strategy extracts the header name and value from the metadata configuration and injects them into the backend request headers.
Required metadata fields:
- header_name: The HTTP header name to use (e.g., "X-API-Key", "Authorization")
- header_value: The header value to inject (can be an API key, token, or any value)
This strategy is appropriate when:
- The backend requires a static header value for authentication
- The header value is stored securely in the vMCP configuration
- No dynamic token exchange or user-specific authentication is required
Future enhancements may include:
- Secret reference resolution (e.g., ${SECRET_REF:...})
- Support for multiple header formats (e.g., "Bearer <key>")
- Value rotation and refresh mechanisms
func NewHeaderInjectionStrategy ¶
func NewHeaderInjectionStrategy() *HeaderInjectionStrategy
NewHeaderInjectionStrategy creates a new HeaderInjectionStrategy instance.
func (*HeaderInjectionStrategy) Authenticate ¶
func (*HeaderInjectionStrategy) Authenticate(_ context.Context, req *http.Request, metadata map[string]any) error
Authenticate injects the header value from metadata into the request header.
This method:
- Validates that header_name and header_value are present in metadata
- Sets the specified header with the provided value
Parameters:
- ctx: Request context (currently unused, reserved for future secret resolution)
- req: The HTTP request to authenticate
- metadata: Strategy-specific configuration containing header_name and header_value
Returns an error if:
- header_name is missing or empty
- header_value is missing or empty
func (*HeaderInjectionStrategy) Name ¶
func (*HeaderInjectionStrategy) Name() string
Name returns the strategy identifier.
func (*HeaderInjectionStrategy) Validate ¶
func (*HeaderInjectionStrategy) Validate(metadata map[string]any) error
Validate checks if the required metadata fields are present and valid.
This method verifies that:
- header_name is present and non-empty
- header_value is present and non-empty
- header_name is a valid HTTP header name (prevents CRLF injection)
- header_value is a valid HTTP header value (prevents CRLF injection)
This validation is typically called during configuration parsing to fail fast if the strategy is misconfigured.
type TokenExchangeStrategy ¶ added in v0.6.3
type TokenExchangeStrategy struct {
// contains filtered or unexported fields
}
TokenExchangeStrategy exchanges the client's token for a backend-specific token using RFC 8693 token exchange protocol.
This strategy implements OAuth 2.0 Token Exchange (RFC 8693) to convert a client's token into a backend-specific token that the backend MCP server can validate.
The strategy caches ExchangeConfig instances per backend configuration to avoid recreating configuration objects. Per-user token caching is handled by the upper vMCP TokenCache layer.
Required metadata fields:
- token_url: The OAuth 2.0 token endpoint URL for token exchange
Optional metadata fields:
- client_id: OAuth 2.0 client identifier (required for some token endpoints)
- client_secret: OAuth 2.0 client secret (directly provided, mutually exclusive with client_secret_env)
- client_secret_env: Name of environment variable containing the client secret (mutually exclusive with client_secret)
- audience: Target audience for the exchanged token
- scopes: Array of scope strings to request
- subject_token_type: Type of the subject token (default: "access_token")
This strategy is appropriate when:
- The backend uses a different identity provider than the vMCP server
- Token exchange relationships are configured between the identity providers
- Per-user token exchange is required (not static credentials)
func NewTokenExchangeStrategy ¶ added in v0.6.3
func NewTokenExchangeStrategy(envReader env.Reader) *TokenExchangeStrategy
NewTokenExchangeStrategy creates a new TokenExchangeStrategy instance.
func (*TokenExchangeStrategy) Authenticate ¶ added in v0.6.3
func (s *TokenExchangeStrategy) Authenticate(ctx context.Context, req *http.Request, metadata map[string]any) error
Authenticate exchanges the client's token for a backend token and injects it.
This method:
- Retrieves the client's identity and token from the context
- Parses and validates the token exchange configuration from metadata
- Gets or creates a cached ExchangeConfig for this backend configuration
- Creates a TokenSource with the current identity token
- Obtains an access token by performing the exchange
- Injects the token into the backend request's Authorization header
Token caching per user is handled by the upper vMCP TokenCache layer. This strategy only caches the ExchangeConfig template per backend.
Parameters:
- ctx: Request context containing the authenticated identity
- req: The HTTP request to authenticate
- metadata: Strategy-specific configuration for token exchange
Returns an error if:
- No identity is found in the context
- The identity has no token
- Metadata is invalid or incomplete
- Token exchange fails
func (*TokenExchangeStrategy) Name ¶ added in v0.6.3
func (*TokenExchangeStrategy) Name() string
Name returns the strategy identifier.
func (*TokenExchangeStrategy) Validate ¶ added in v0.6.3
func (s *TokenExchangeStrategy) Validate(metadata map[string]any) error
Validate checks if the required metadata fields are present and valid.
This method verifies that:
- token_url is present and valid
- Optional fields (if present) have correct types and values
- client_secret is only provided when client_id is present
This validation is typically called during configuration parsing to fail fast if the strategy is misconfigured.
type UnauthenticatedStrategy ¶
type UnauthenticatedStrategy struct{}
UnauthenticatedStrategy is a no-op authentication strategy that performs no authentication. This strategy is used when a backend MCP server requires no authentication.
Unlike passing a nil authenticator (which is now an error), this strategy makes the intent explicit: "this backend intentionally has no authentication".
The strategy performs no modifications to requests and validates all metadata.
This is appropriate when:
- The backend MCP server is on a trusted network (e.g., localhost)
- The backend has no authentication requirements
- Authentication is handled by network-level security (e.g., VPC, firewall)
Security Warning: Only use this strategy when you are certain the backend requires no authentication. For production deployments, prefer explicit authentication strategies (pass_through, header_injection, token_exchange).
Configuration: No metadata required, but any metadata is accepted and ignored.
Example configuration:
backends:
local-backend:
strategy: "unauthenticated"
func NewUnauthenticatedStrategy ¶
func NewUnauthenticatedStrategy() *UnauthenticatedStrategy
NewUnauthenticatedStrategy creates a new UnauthenticatedStrategy instance.
func (*UnauthenticatedStrategy) Authenticate ¶
func (*UnauthenticatedStrategy) Authenticate(_ context.Context, _ *http.Request, _ map[string]any) error
Authenticate performs no authentication and returns immediately.
This method:
- Does not modify the request in any way
- Always returns nil (success)
Parameters:
- ctx: Request context (unused)
- req: The HTTP request (not modified)
- metadata: Strategy-specific configuration (ignored)
Returns nil (always succeeds).
func (*UnauthenticatedStrategy) Name ¶
func (*UnauthenticatedStrategy) Name() string
Name returns the strategy identifier.
func (*UnauthenticatedStrategy) Validate ¶
func (*UnauthenticatedStrategy) Validate(_ map[string]any) error
Validate checks if the strategy configuration is valid.
UnauthenticatedStrategy accepts any metadata (including nil or empty), so this always returns nil.
This permissive validation allows the strategy to be used without configuration or with arbitrary configuration that may be present for documentation purposes.
Source Files