Documentation
¶
Overview ¶
Package aws provides functionality to retrieve OIDC tokens from AWS STS GetWebIdentityToken API. It defines a token source that implements oauth2.TokenSource, allowing for easy integration with OAuth2 libraries and frameworks. The package also includes support for custom claims and configurable options for audience, signing algorithm, and AWS configuration.
Index ¶
- Constants
- func HasValidClaims(claims map[string]any) bool
- func NewHTTPClient(ctx context.Context, opts ...Opt) (*http.Client, error)
- func NewTokenSource(opts ...Opt) oauth2.TokenSource
- func NormalizeClaims(claims map[string]any) map[string]any
- type Claims
- type CustomClaims
- type Opt
- type PrincipalSource
- func (s *PrincipalSource) Claims(ctx context.Context) map[string]any
- func (s *PrincipalSource) Extract(ctx context.Context) (string, error)
- func (s *PrincipalSource) IsService(ctx context.Context) bool
- func (s *PrincipalSource) Name() string
- func (s *PrincipalSource) Roles(ctx context.Context) []string
Constants ¶
const STSNamespace = "https://sts.amazonaws.com/"
STSNamespace is the OIDC custom claim namespace for AWS STS.
Variables ¶
This section is empty.
Functions ¶
func HasValidClaims ¶ added in v0.5.7
HasValidClaims reports whether claims contains the AWS STS namespace custom claims that identify an AWS OIDC token validated by a generic JWT middleware.
func NewHTTPClient ¶
NewHTTPClient creates an HTTP client configured with AWS OIDC authentication. The opts parameter allows for configuring the token source, such as setting the audience, signing algorithm, or AWS configuration.
func NewTokenSource ¶
func NewTokenSource(opts ...Opt) oauth2.TokenSource
NewTokenSource creates a new token source configured with the provided options. It returns an oauth2.TokenSource that can be used to retrieve OIDC tokens from AWS.
func NormalizeClaims ¶ added in v0.5.7
NormalizeClaims flattens the nested AWS STS namespace claims from a raw OIDC token payload into the canonical aws_* prefixed form expected by ClaimRoleMapper rules. Returns nil when claims is empty. The input map is not modified; the returned map is a new copy.
Types ¶
type Claims ¶
type Claims struct {
CustomClaims
}
Claims represents the JWT claims returned by the AWS OIDC provider, including both standard registered claims and custom AWS-specific claims.
type CustomClaims ¶
type CustomClaims struct {
HttpsStsAmazonawsCom struct {
Ec2InstanceSourceVpc string `json:"ec2_instance_source_vpc"`
Ec2RoleDelivery string `json:"ec2_role_delivery"`
OrgId string `json:"org_id"`
AwsAccount string `json:"aws_account"`
OuPath []string `json:"ou_path"`
OriginalSessionExp time.Time `json:"original_session_exp"`
SourceRegion string `json:"source_region"`
Ec2SourceInstanceArn string `json:"ec2_source_instance_arn"`
PrincipalId string `json:"principal_id"`
Ec2InstanceSourcePrivateIpv4 string `json:"ec2_instance_source_private_ipv4"`
} `json:"https://sts.amazonaws.com/"`
}
CustomClaims represents the custom claims included in the JWT token returned by AWS STS GetWebIdentityToken API. These claims provide additional information about the AWS environment and the context of the token issuance.
type Opt ¶
type Opt func(*tokenSource)
Opt defines a functional option for configuring the token source. It allows for setting various parameters such as audience, signing algorithm, and AWS configuration when creating a new token source.
func WithAWSConfig ¶
WithAWSConfig sets the AWS configuration for the token source
func WithAudience ¶
WithAudience sets the audience for the OIDC token
func WithIMDSClient ¶ added in v0.5.0
func WithIMDSClient(client imdsClient) Opt
WithIMDSClient sets a custom IMDS client for the token source.
func WithRegion ¶ added in v0.5.0
WithRegion sets the AWS region for the token source. If not set, it will be automatically discovered from the EC2 metadata service or the default AWS configuration.
func WithSTSClient ¶
func WithSTSClient(client stsClient) Opt
WithSTSClient sets a custom STS client for the token source.
func WithSigningAlgorithm ¶
WithSigningAlgorithm sets the signing algorithm for the OIDC token
type PrincipalSource ¶ added in v0.4.0
type PrincipalSource struct {
// RoleMapper maps raw AWS JWT claims to internal role strings.
// When nil, Roles returns nil.
RoleMapper mapper.Mapper
}
PrincipalSource extracts principal identity from AWS OIDC tokens.
func (*PrincipalSource) Claims ¶ added in v0.4.0
func (s *PrincipalSource) Claims(ctx context.Context) map[string]any
Claims returns the AWS OIDC token claims as a map. AWS STS custom claims are flattened from the nested STS namespace into canonical aws_* prefixed keys so that ClaimRoleMapper rules can reference them uniformly across both the typed and generic validation paths.
func (*PrincipalSource) Extract ¶ added in v0.4.0
func (s *PrincipalSource) Extract(ctx context.Context) (string, error)
Extract returns the principal subject from an AWS OIDC token. It first attempts the typed-claims path (JWT middleware configured with an AWS validator), then falls back to fingerprinting generic validated claims stored by a non-typed JWT middleware.
func (*PrincipalSource) IsService ¶ added in v0.4.0
func (s *PrincipalSource) IsService(ctx context.Context) bool
IsService returns true for any valid AWS OIDC token, as these represent machine/role identities rather than human users.
func (*PrincipalSource) Name ¶ added in v0.4.0
func (s *PrincipalSource) Name() string
Source Files