Documentation
¶
Overview ¶
Package awssts provides AWS STS token exchange with SigV4 signing support.
Index ¶
Constants ¶
const MaxSessionDuration int32 = 43200
MaxSessionDuration is the maximum allowed session duration (12 hours).
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") )
Sentinel errors for AWS STS operations.
Functions ¶
func ValidateConfig ¶
ValidateConfig validates the AWS STS configuration structure. It checks that required fields are present, ARNs are well-formed, claim values are safe for CEL interpolation, 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).
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.
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.
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.
Priority int `json:"priority" yaml:"priority"`
}
RoleMapping maps a JWT claim value or CEL expression to an IAM role with explicit priority.
Source Files