Documentation
¶
Overview ¶
Package awssts provides AWS STS token exchange with SigV4 signing support.
Package awssts provides AWS STS token exchange with SigV4 signing support.
Package awssts provides AWS STS token exchange and SigV4 signing functionality.
Index ¶
- Constants
- Variables
- func CreateMiddleware(config *types.MiddlewareConfig, runner types.MiddlewareRunner) error
- func ValidateConfig(cfg *Config) error
- func ValidateRoleArn(roleArn string) error
- func ValidateSessionName(name string) error
- type Config
- type Exchanger
- type Middleware
- type MiddlewareParams
- type RoleMapper
- type RoleMapping
- type STSClient
Constants ¶
const MaxSessionDuration int32 = 43200
MaxSessionDuration is the maximum allowed session duration (12 hours).
const (
MiddlewareType = "awssts"
)
Middleware type constant
const MinSessionDuration int32 = 900
MinSessionDuration is the minimum allowed session duration (AWS limit).
Variables ¶
var ( // ErrNoRoleMapping is returned when no role mapping matches the JWT claims. ErrNoRoleMapping = errors.New("no role mapping found for JWT claims") // ErrInvalidRoleArn is returned when the role ARN format is invalid. ErrInvalidRoleArn = errors.New("invalid IAM role ARN format") // ErrMissingRegion is returned when region is not configured. ErrMissingRegion = errors.New("AWS region is required") // ErrMissingRoleConfig is returned when neither role_arn nor role_mappings is configured. ErrMissingRoleConfig = errors.New("either role_arn or role_mappings must be configured") // ErrInvalidRoleMapping is returned when a role mapping has invalid configuration. ErrInvalidRoleMapping = errors.New("invalid role mapping configuration") // ErrInvalidMatcher is returned when a CEL matcher expression is invalid. ErrInvalidMatcher = errors.New("invalid CEL matcher expression") // ErrMissingToken is returned when the identity token is empty. ErrMissingToken = errors.New("token is required") // ErrInvalidSessionDuration is returned when the session duration is outside allowed bounds. ErrInvalidSessionDuration = errors.New("invalid session duration") // ErrInvalidSessionName is returned when the session name does not meet AWS constraints. ErrInvalidSessionName = errors.New("invalid session name") // ErrSTSExchangeFailed is returned when the STS AssumeRoleWithWebIdentity call fails. ErrSTSExchangeFailed = errors.New("STS token exchange failed") // ErrSTSNilCredentials is returned when STS returns a response without credentials. ErrSTSNilCredentials = errors.New("STS returned nil credentials") )
Sentinel errors for AWS STS operations.
Functions ¶
func CreateMiddleware ¶ added in v0.9.4
func CreateMiddleware(config *types.MiddlewareConfig, runner types.MiddlewareRunner) error
CreateMiddleware is the factory function for AWS STS middleware.
func ValidateConfig ¶
ValidateConfig validates the AWS STS configuration structure. It checks that required fields are present, ARNs are well-formed, and session duration is within bounds.
This performs structural validation only — CEL expression compilation is handled by NewRoleMapper. It is safe to call standalone for early validation at config load time. NewRoleMapper calls this internally, so callers do not need to call both.
func ValidateRoleArn ¶
ValidateRoleArn validates that the given string is a valid IAM role ARN. It accepts ARNs from all AWS partitions (aws, aws-cn, aws-us-gov) and supports role paths (e.g., arn:aws:iam::123456789012:role/service-role/MyRole).
func ValidateSessionName ¶ added in v0.9.4
ValidateSessionName checks that a session name meets AWS RoleSessionName constraints: 2-64 characters, only letters, digits, and _+=,.@- are allowed.
Types ¶
type Config ¶
type Config struct {
// Region is the AWS region for STS and SigV4 signing.
Region string `json:"region" yaml:"region"`
// Service is the AWS service name for SigV4 signing (default: "aws-mcp").
Service string `json:"service" yaml:"service"`
// FallbackRoleArn is the IAM role ARN to assume when no role mapping matches.
FallbackRoleArn string `json:"fallback_role_arn,omitempty" yaml:"fallback_role_arn,omitempty"`
// RoleMappings maps JWT claim values to IAM roles with priority.
RoleMappings []RoleMapping `json:"role_mappings,omitempty" yaml:"role_mappings,omitempty"`
// RoleClaim is the JWT claim to use for role mapping (default: "groups").
RoleClaim string `json:"role_claim,omitempty" yaml:"role_claim,omitempty"`
// SessionDuration is the duration in seconds for assumed role credentials (default: 3600).
SessionDuration int32 `json:"session_duration,omitempty" yaml:"session_duration,omitempty"`
// SessionNameClaim is the JWT claim to use for role session name (default: "sub").
SessionNameClaim string `json:"session_name_claim,omitempty" yaml:"session_name_claim,omitempty"`
}
Config holds configuration for AWS STS token exchange.
func (*Config) GetRoleClaim ¶
GetRoleClaim returns the configured role claim or the default.
func (*Config) GetService ¶ added in v0.9.4
GetService returns the configured service name or the default ("aws-mcp").
func (*Config) GetSessionDuration ¶ added in v0.9.4
GetSessionDuration returns the configured session duration or the default (3600s).
type Exchanger ¶ added in v0.9.4
type Exchanger struct {
// contains filtered or unexported fields
}
Exchanger handles STS token exchange operations.
func NewExchanger ¶ added in v0.9.4
NewExchanger creates a new Exchanger with a regional STS client.
func (*Exchanger) ExchangeToken ¶ added in v0.9.4
func (e *Exchanger) ExchangeToken( ctx context.Context, token, roleArn, sessionName string, durationSeconds int32, ) (*aws.Credentials, error)
ExchangeToken performs AssumeRoleWithWebIdentity to exchange an identity token for temporary AWS credentials.
type Middleware ¶ added in v0.9.4
type Middleware struct {
// contains filtered or unexported fields
}
Middleware wraps AWS STS middleware functionality.
func (*Middleware) Close ¶ added in v0.9.4
func (*Middleware) Close() error
Close cleans up any resources used by the middleware.
func (*Middleware) Handler ¶ added in v0.9.4
func (m *Middleware) Handler() types.MiddlewareFunction
Handler returns the middleware function used by the proxy.
type MiddlewareParams ¶ added in v0.9.4
type MiddlewareParams struct {
AWSStsConfig *Config `json:"aws_sts_config,omitempty"`
// TargetURL is the remote MCP server URL for SigV4 signing.
// The request must be signed with the target host, not the proxy host.
TargetURL string `json:"target_url,omitempty"`
}
MiddlewareParams represents the parameters for AWS STS middleware.
type RoleMapper ¶
type RoleMapper struct {
// contains filtered or unexported fields
}
RoleMapper handles mapping JWT claims to IAM roles with priority-based selection. It uses CEL expressions for flexible claim matching.
func NewRoleMapper ¶
func NewRoleMapper(cfg *Config) (*RoleMapper, error)
NewRoleMapper creates a new RoleMapper with the provided configuration. It validates the configuration and compiles all CEL expressions during construction. Returns an error if the configuration is invalid or any expression fails to compile.
ValidateConfig is called internally, so callers do not need to call both.
func (*RoleMapper) SelectRole ¶
func (rm *RoleMapper) SelectRole(claims map[string]any) (string, error)
SelectRole selects the appropriate IAM role based on JWT claims. It returns the role ARN to assume based on the following logic:
- If no role mappings are configured, return the FallbackRoleArn
- Evaluate each mapping's CEL expression against the claims
- Collect all matching mappings
- Sort matches by priority (lower number = higher priority)
- Return the highest priority match
- If no matches found, fall back to the FallbackRoleArn
type RoleMapping ¶
type RoleMapping struct {
// Claim is the simple claim value to match (e.g., group name).
// Internally compiles to a CEL expression: "<claim_value>" in claims["<role_claim>"]
// Mutually exclusive with Matcher.
Claim string `json:"claim,omitempty" yaml:"claim,omitempty"`
// Matcher is a CEL expression for complex matching against JWT claims.
// The expression has access to a "claims" variable containing all JWT claims.
// Examples:
// - "admins" in claims["groups"]
// - claims["sub"] == "user123" && !("act" in claims)
// Mutually exclusive with Claim.
Matcher string `json:"matcher,omitempty" yaml:"matcher,omitempty"`
// RoleArn is the IAM role ARN to assume when this mapping matches.
RoleArn string `json:"role_arn" yaml:"role_arn"`
// Priority determines selection order (lower number = higher priority).
// When multiple mappings match, the one with the lowest priority is selected.
// When nil (omitted), the mapping has the lowest possible priority, and
// configuration order acts as tie-breaker via stable sort.
Priority *int `json:"priority,omitempty" yaml:"priority,omitempty"`
}
RoleMapping maps a JWT claim value or CEL expression to an IAM role with explicit priority.
type STSClient ¶ added in v0.9.4
type STSClient interface {
AssumeRoleWithWebIdentity(
ctx context.Context,
params *sts.AssumeRoleWithWebIdentityInput,
optFns ...func(*sts.Options),
) (*sts.AssumeRoleWithWebIdentityOutput, error)
}
STSClient defines the interface for STS operations, enabling mock injection for testing.