stscreds

Documentation

Overview

Package stscreds are credential Providers to retrieve STS AWS credentials.

STS provides multiple ways to retrieve credentials which can be used when making future AWS service API operation calls.

Index

• func NewCredentials(client AssumeRoler, roleARN string, window time.Duration) *credentials.Credentials
• type AssumeRoleProvider
  • func (p *AssumeRoleProvider) Retrieve() (credentials.Value, error)
• type AssumeRoler

Functions

func NewCredentials

func NewCredentials(client AssumeRoler, roleARN string, window time.Duration) *credentials.Credentials

NewCredentials returns a pointer to a new Credentials object wrapping the AssumeRoleProvider. The credentials will expire every 15 minutes and the role will be named after a nanosecond timestamp of this operation.

The sts and roleARN parameters are used for building the "AssumeRole" call. Pass nil as sts to use the default client.

Window is the expiry window that will be subtracted from the expiry returned by the role credential request. This is done so that the credentials will expire sooner than their actual lifespan.

Types

type AssumeRoleProvider

type AssumeRoleProvider struct {
	credentials.Expiry

	// Custom STS client. If not set the default STS client will be used.
	Client AssumeRoler

	// Role to be assumed.
	RoleARN string

	// Session name, if you wish to reuse the credentials elsewhere.
	RoleSessionName string

	// Expiry duration of the STS credentials. Defaults to 15 minutes if not set.
	Duration time.Duration

	// Optional ExternalID to pass along, defaults to nil if not set.
	ExternalID *string

	// ExpiryWindow will allow the credentials to trigger refreshing prior to
	// the credentials actually expiring. This is beneficial so race conditions
	// with expiring credentials do not cause request to fail unexpectedly
	// due to ExpiredTokenException exceptions.
	//
	// So a ExpiryWindow of 10s would cause calls to IsExpired() to return true
	// 10 seconds before the credentials are actually expired.
	//
	// If ExpiryWindow is 0 or less it will be ignored.
	ExpiryWindow time.Duration
}

AssumeRoleProvider retrieves temporary credentials from the STS service, and keeps track of their expiration time. This provider must be used explicitly, as it is not included in the credentials chain.

Example how to configure a service to use this provider:

config := &aws.Config{
	Credentials: stscreds.NewCredentials(nil, "arn-of-the-role-to-assume", 10*time.Second),
})
// Use config for creating your AWS service.

Example how to obtain customised credentials:

provider := &stscreds.Provider{
	// Extend the duration to 1 hour.
	Duration: time.Hour,
	// Custom role name.
	RoleSessionName: "custom-session-name",
}
creds := credentials.NewCredentials(provider)

func (*AssumeRoleProvider) Retrieve

func (p *AssumeRoleProvider) Retrieve() (credentials.Value, error)

Retrieve generates a new set of temporary credentials using STS.

type AssumeRoler

type AssumeRoler interface {
	AssumeRole(input *sts.AssumeRoleInput) (*sts.AssumeRoleOutput, error)
}

AssumeRoler represents the minimal subset of the STS client API used by this provider.