Documentation
¶
Overview ¶
Package aws provides utilities for generating and verifying Chainguard tokens backed by AWS identity credentials via the AWS STS GetCallerIdentity API.
VerifyToken treats a token as proof of an AWS identity only when the audience and identity binding headers — along with the host and date headers it relies on — are covered by the request's SigV4 signature, and when the request targets the expected STS host with a fresh, non-future timestamp. This prevents a GetCallerIdentity request signed for another relying party from being replayed against this verifier.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrTokenRejected = errors.New("token rejected by AWS STS endpoint") ErrTokenExpired = errors.New("token expired") ErrInvalidAudience = errors.New("audience header in token does not match expected audience") ErrInvalidIdentity = errors.New("identity header in token does not match expected identity") ErrInvalidEncoding = errors.New("invalid token encoding") ErrInvalidVerificationConfiguration = errors.New("verification was incorrectly configured") // Added with the SignedHeaders binding fix. Callers that branch on // VerifyToken errors with errors.Is should handle these explicitly rather // than letting them fall into a generic "unknown error" bucket. ErrUnsignedBindingHeaders = errors.New("a required header is not covered by the request signature") ErrInvalidRequest = errors.New("token is not a well-formed GetCallerIdentity request") ErrTokenFutureDated = errors.New("token timestamp is in the future") )
Functions ¶
func GenerateToken ¶
func GenerateToken(ctx context.Context, creds aws.Credentials, audience, identity string) (string, error)
GenerateToken creates token using the supplied AWS credentials that can prove the user's AWS identity. Audience and identity are the Chainguard STS url (e.g https://issuer.enforce.dev) and the UID of the Chainguard assumable identity to assume via STS.
Types ¶
type VerifiedClaims ¶
type VerifiedClaims struct {
UserID string `json:"UserId"`
Arn string `json:"Arn"`
Account string `json:"Account"`
}
func VerifyToken ¶
func VerifyToken(ctx context.Context, token string, opts ...VerifyOption) (*VerifiedClaims, error)
VerifyToken verifies a Chainguard token backed by an AWS STS GetCallerIdentity request and returns the caller's verified AWS identity.
By default only tokens addressed to the global endpoint "sts.amazonaws.com" are accepted; tokens signed against a regional, FIPS, or partition (GovCloud, China) endpoint must opt in with WithExpectedSTSHost, otherwise VerifyToken rejects them with ErrInvalidRequest before contacting STS.
Example ¶
ExampleVerifyToken demonstrates that an invalid token returns an error.
package main
import (
"context"
"fmt"
"chainguard.dev/sdk/auth/aws"
)
func main() {
ctx := context.Background()
_, err := aws.VerifyToken(ctx, "not-a-valid-token")
fmt.Println(err != nil)
}
Output: true
type VerifyOption ¶
type VerifyOption func(*verifyConf)
func WithAllowedClockSkew ¶ added in v0.1.107
func WithAllowedClockSkew(skew time.Duration) VerifyOption
WithAllowedClockSkew sets how far a token's X-Amz-Date may be ahead of the verifier's clock before it is rejected as future-dated. It defaults to defaultAllowedClockSkew (5 minutes, matching AWS SigV4's tolerance). Increase it for environments with looser clock synchronization.
func WithAudience ¶
func WithAudience(aud sets.Set[string]) VerifyOption
func WithExpectedSTSHost ¶ added in v0.1.107
func WithExpectedSTSHost(host string) VerifyOption
WithExpectedSTSHost sets the STS host a token's GetCallerIdentity request must be addressed to: both the host required in the signed request (compared against the request's Host header) and the endpoint VerifyToken forwards to. It defaults to "sts.amazonaws.com"; override it to verify identities whose tokens are signed against a regional, FIPS, or GovCloud/China-partition STS endpoint (all of which use https://<host>/?Action=GetCallerIdentity&Version=2011-06-15).
The value must be a lowercase, port-less hostname with no trailing dot, matching the host as it appears in the SigV4 canonical request. It assumes the forwarded endpoint host equals the signed host; deployments where they differ (PrivateLink/VPC-interface endpoints, egress proxies) are not yet supported.
func WithIdentity ¶
func WithIdentity(id string) VerifyOption
Source Files