Documentation
¶
Overview ¶
Package tokenexchange provides OAuth 2.0 Token Exchange (RFC 8693) support.
Index ¶
- Constants
- func CreateMiddleware(config *types.MiddlewareConfig, runner types.MiddlewareRunner) error
- func CreateMiddlewareFromHeader(config Config) (types.MiddlewareFunction, error)
- func CreateMiddlewareFromTokenSource(config Config, tokenSource oauth2.TokenSource) (types.MiddlewareFunction, error)
- func NormalizeTokenType(tokenType string) (string, error)
- type Config
- type ExchangeConfig
- type Middleware
- type MiddlewareParams
- type SubjectTokenProvider
Constants ¶
const ( // HeaderStrategyReplace replaces the Authorization header with the exchanged token HeaderStrategyReplace = "replace" // HeaderStrategyCustom adds the exchanged token to a custom header HeaderStrategyCustom = "custom" )
Header injection strategy constants
const ( // EnvClientSecret is the environment variable name for the OAuth client secret // This corresponds to the "client_secret" field in the token exchange configuration //nolint:gosec // G101: This is an environment variable name, not a credential EnvClientSecret = "TOOLHIVE_TOKEN_EXCHANGE_CLIENT_SECRET" )
Environment variable names
const (
MiddlewareType = "tokenexchange"
)
Middleware type constant
Variables ¶
This section is empty.
Functions ¶
func CreateMiddleware ¶
func CreateMiddleware(config *types.MiddlewareConfig, runner types.MiddlewareRunner) error
CreateMiddleware factory function for token exchange middleware
func CreateMiddlewareFromHeader ¶
func CreateMiddlewareFromHeader(config Config) (types.MiddlewareFunction, error)
CreateMiddlewareFromHeader creates token exchange middleware that extracts the subject token from the incoming request's Authorization header. This is the recommended approach when the proxy receives authenticated requests and needs to exchange those tokens for backend access.
For external authentication flows (OAuth/OIDC), use CreateMiddlewareFromTokenSource instead.
func CreateMiddlewareFromTokenSource ¶
func CreateMiddlewareFromTokenSource( config Config, tokenSource oauth2.TokenSource, ) (types.MiddlewareFunction, error)
CreateMiddlewareFromTokenSource creates token exchange middleware using an oauth2.TokenSource. This is the recommended approach for external authentication flows (OAuth/OIDC).
The middleware will automatically select the appropriate token based on config.SubjectTokenType:
- tokenTypeAccessToken: Uses token.AccessToken
- tokenTypeIDToken or tokenTypeJWT: Uses token.Extra("id_token")
This moves the token selection logic into the middleware where it belongs, keeping the command layer focused on configuration.
func NormalizeTokenType ¶
NormalizeTokenType converts a short token type name to its full URN. Accepts both short forms ("access_token", "id_token", "jwt") and full URNs. Returns the full URN or an error if the token type is invalid.
This is primarily intended for CLI/user input processing. Internal APIs should use full URNs directly.
Types ¶
type Config ¶
type Config struct {
// TokenURL is the OAuth 2.0 token endpoint URL
TokenURL string `json:"token_url"`
// ClientID is the OAuth 2.0 client identifier
ClientID string `json:"client_id"`
// ClientSecret is the OAuth 2.0 client secret
ClientSecret string `json:"client_secret"`
// Audience is the target audience for the exchanged token
Audience string `json:"audience"`
// Scopes is the list of scopes to request for the exchanged token
Scopes []string `json:"scopes,omitempty"`
// SubjectTokenType specifies the type of the subject token being exchanged.
// Common values: tokenTypeAccessToken (default), tokenTypeIDToken, tokenTypeJWT.
// If empty, defaults to tokenTypeAccessToken.
SubjectTokenType string `json:"subject_token_type,omitempty"`
// HeaderStrategy determines how to inject the token
// Valid values: HeaderStrategyReplace (default), HeaderStrategyCustom
HeaderStrategy string `json:"header_strategy,omitempty"`
// ExternalTokenHeaderName is the name of the custom header to use when HeaderStrategy is "custom"
ExternalTokenHeaderName string `json:"external_token_header_name,omitempty"`
}
Config holds configuration for token exchange middleware
type ExchangeConfig ¶
type ExchangeConfig struct {
// TokenURL is the OAuth 2.0 token endpoint URL
TokenURL string
// ClientID is the OAuth 2.0 client identifier
ClientID string
// ClientSecret is the OAuth 2.0 client secret
ClientSecret string
// Audience is the target audience for the exchanged token (optional per RFC 8693)
Audience string
// Scopes is the list of scopes to request (optional per RFC 8693)
Scopes []string
// SubjectTokenType specifies the type of the subject token being exchanged.
// Common values: tokenTypeAccessToken (default), tokenTypeIDToken, tokenTypeJWT.
// If empty, defaults to tokenTypeAccessToken.
SubjectTokenType string
// SubjectTokenProvider is a function that returns the subject token to exchange
// we use a function to allow dynamic retrieval of the token (e.g. from request context)
// and also to lazy-load the token only when needed, load from dynamic sources, etc.
SubjectTokenProvider func() (string, error)
// HTTPClient is the HTTP client to use for token exchange requests.
// If nil, defaultHTTPClient will be used.
HTTPClient *http.Client
}
ExchangeConfig holds the configuration for token exchange.
func (*ExchangeConfig) TokenSource ¶
func (c *ExchangeConfig) TokenSource(ctx context.Context) oauth2.TokenSource
TokenSource returns an oauth2.TokenSource that performs token exchange.
func (*ExchangeConfig) Validate ¶
func (c *ExchangeConfig) Validate() error
Validate checks if the ExchangeConfig contains all required fields.
type Middleware ¶
type Middleware struct {
// contains filtered or unexported fields
}
Middleware wraps token exchange middleware functionality
func (*Middleware) Close ¶
func (*Middleware) Close() error
Close cleans up any resources used by the middleware.
func (*Middleware) Handler ¶
func (m *Middleware) Handler() types.MiddlewareFunction
Handler returns the middleware function used by the proxy.
type MiddlewareParams ¶
type MiddlewareParams struct {
TokenExchangeConfig *Config `json:"token_exchange_config,omitempty"`
}
MiddlewareParams represents the parameters for token exchange middleware
type SubjectTokenProvider ¶
SubjectTokenProvider is a function that provides the subject token for exchange. This is used when the token comes from an external source (e.g., OAuth flow) rather than from incoming request headers.
Source Files