Documentation
¶
Overview ¶
Package iamproof generates short-lived, audience-bound GetCallerIdentity proofs and verifies them online with regional AWS STS. It does not require an API Gateway authorizer. It neither authorizes application actions nor installs callers in a context; compose those responsibilities in the application.
Send Token.Value as the credential in Authorization: EdgeIAM <value>, over HTTPS. A proof is reusable within its freshness window and does not sign the application request body, method or action. Do not log credentials or signed STS requests. Generation uses the caller's AWS credentials; verification never signs with the server's credentials. Every verification calls STS, without an application retry or result cache. Account for STS quotas when sizing traffic.
The version 1 protocol bounds encoded credentials to 8 KiB and STS responses to 64 KiB. Proofs expire 60 seconds after their signing time; verification permits up to 30 seconds of future clock skew, with no expired-proof grace. These are library policies, not AWS credential-size or expiration guarantees.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrInvalidConfiguration means [NewGenerator] or [NewVerifier] rejected its arguments or options, or a method was called on a nil or zero value or with a nil context. ErrInvalidConfiguration = errors.New("iamproof: invalid configuration") // ErrInvalidProof means [Verifier.Verify] rejected a malformed, expired, misdirected or STS-rejected proof. // When wiring the verifier into authn, map it to authn.ErrInvalidCredentials. ErrInvalidProof = errors.New("iamproof: invalid proof") ErrUnavailable = errors.New("iamproof: verification unavailable") ErrCredentialsUnavailable = errors.New("iamproof: credentials unavailable") // ErrProofTooLarge means [Generator.Generate] produced a proof larger than the protocol's 8 KiB bound. // Credentials are never truncated to fit. ErrProofTooLarge = errors.New("iamproof: proof too large") )
Package errors contain no credentials, signed URLs or dependency diagnostics. Match them with errors.Is.
Functions ¶
This section is empty.
Types ¶
type Generator ¶
type Generator struct {
// contains filtered or unexported fields
}
Generator presigns proofs using its credentials provider. It is safe for concurrent use if the provider is. A zero Generator is not configured.
func NewGenerator ¶
func NewGenerator(region, audience string, credentials aws.CredentialsProvider) (*Generator, error)
NewGenerator requires an explicit standard STS region, a case-sensitive audience of 1-256 visible ASCII bytes without spaces, and a nonnil provider. The provider owns credential caching, refresh and any retrieval I/O.
func (*Generator) Generate ¶
Generate retrieves fresh credentials and presigns locally, without calling STS. Failure returns a zero Token and a sanitized package or caller-context error. Oversized proofs fail with ErrProofTooLarge; credentials are not cut.
Example ¶
package main
import (
"context"
"fmt"
"net/http"
"github.com/aws/aws-sdk-go-v2/aws"
"github.com/asteroid-computing/go-lambda-edge/iamproof"
)
func main() {
ctx := context.Background()
// Synthetic credentials keep this example entirely local.
// In an application, pass cfg.Credentials from your existing AWS SDK configuration instead.
provider := aws.CredentialsProviderFunc(func(context.Context) (aws.Credentials, error) {
return aws.Credentials{AccessKeyID: "AKIAIOSFODNN7EXAMPLE", SecretAccessKey: "synthetic-example-only"}, nil
})
generator, err := iamproof.NewGenerator("eu-west-2", "orders.production", provider)
if err != nil {
fmt.Println(err)
return
}
token, err := generator.Generate(ctx)
if err != nil {
fmt.Println(err)
return
}
req, err := http.NewRequestWithContext(ctx, http.MethodPost, "https://orders.example.com/", nil)
if err != nil {
fmt.Println(err)
return
}
req.Header.Set("Authorization", "EdgeIAM "+token.Value())
req.Header.Set("Action", "ListOrders")
// Sending req is the application's responsibility.
// Never log its credential.
fmt.Println(req.Header.Get("Action"))
fmt.Println(token) // Default diagnostics redact the proof.
}
Output: ListOrders iamproof.Token(redacted)
type Token ¶
type Token struct {
// contains filtered or unexported fields
}
Token owns a versioned proof. Its zero value is unusable. Default string and debug formatting are redacted; Value explicitly exposes the credential.
func (Token) ExpiresAt ¶
ExpiresAt returns the earlier of proof expiry and known credential expiry. This is an upper bound, not a guarantee of AWS acceptance until that time.
type Verifier ¶
type Verifier struct {
// contains filtered or unexported fields
}
Verifier authenticates each proof through its configured regional STS endpoint. It is safe for concurrent use if its transport is. Its zero value is not configured. It never obtains or uses server-side AWS credentials.
func NewVerifier ¶
func NewVerifier(region, audience string, opts ...VerifierOption) (*Verifier, error)
NewVerifier requires the same region and audience as the client generator. Its owned HTTP client disables redirects and cookies. The default transport is http.DefaultTransport as configured when this constructor is called.
Example ¶
package main
import (
"fmt"
"github.com/asteroid-computing/go-lambda-edge/iamproof"
)
func main() {
verifier, err := iamproof.NewVerifier("eu-west-2", "orders.production")
if err != nil {
fmt.Println(err)
return
}
// Pass verifier.Verify to your authentication layer.
// It accepts a context and the proof credential, returns an identity.Caller, and calls real STS.
// Construction alone makes no network request.
fmt.Println(verifier != nil)
}
Output: true
func (*Verifier) Verify ¶
Verify accepts Token.Value, without an HTTP authentication scheme. It returns an IAM caller with SourceVerifiedIAMProof only after STS confirms the proof, response invariants hold and the proof remains fresh. It does not install the caller in a context. Every failure returns an anonymous zero caller.
Malformed or rejected credentials match ErrInvalidProof. Dependency failures, internal timeouts and unexpected responses match ErrUnavailable. Caller cancellation/deadline errors are preserved, without unsafe dependency causes.
type VerifierOption ¶
type VerifierOption func(*verifierConfig) error
VerifierOption configures a verifier. Options apply in order; the last value for a setting wins. Nil options and invalid values fail construction.
func WithTimeout ¶
func WithTimeout(timeout time.Duration) VerifierOption
WithTimeout sets a positive verification network deadline, defaulting to five seconds. The caller's earlier context deadline still wins.
func WithTransport ¶
func WithTransport(transport http.RoundTripper) VerifierOption
WithTransport sets trusted deployment infrastructure for STS requests. The transport must be nonnil, concurrency-safe and honor request cancellation. Internal transport retries and proxy/TLS policy belong to the transport owner.
Source Files