awssts

package
v0.9.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 16, 2026 License: Apache-2.0 Imports: 26 Imported by: 0

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

View Source
const MaxSessionDuration int32 = 43200

MaxSessionDuration is the maximum allowed session duration (12 hours).

View Source
const (
	MiddlewareType = "awssts"
)

Middleware type constant

View Source
const MinSessionDuration int32 = 900

MinSessionDuration is the minimum allowed session duration (AWS limit).

Variables

View Source
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

func ValidateConfig(cfg *Config) error

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

func ValidateRoleArn(roleArn string) error

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

func ValidateSessionName(name string) error

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

func (c *Config) GetRoleClaim() string

GetRoleClaim returns the configured role claim or the default.

func (*Config) GetService added in v0.9.4

func (c *Config) GetService() string

GetService returns the configured service name or the default ("aws-mcp").

func (*Config) GetSessionDuration added in v0.9.4

func (c *Config) GetSessionDuration() int32

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

func NewExchanger(ctx context.Context, region string) (*Exchanger, error)

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:

  1. If no role mappings are configured, return the FallbackRoleArn
  2. Evaluate each mapping's CEL expression against the claims
  3. Collect all matching mappings
  4. Sort matches by priority (lower number = higher priority)
  5. Return the highest priority match
  6. 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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL