AWS SDK for Go (PILOT)
API Reference

PREVIEW DOCUMENTATION - This is a preview of a new format for the AWS SDK for Go API Reference documentation. For the current AWS SDK for Go API Reference, see https://docs.aws.amazon.com/sdk-for-go/api/.

We welcome your feedback on this new version of the documentation. Send your comments to aws-sdkdocs-feedback@amazon.com.

stscreds

import "github.com/aws/aws-sdk-go/aws/credentials/stscreds"

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.

The SDK will ensure that per instance of credentials.Credentials all requests to refresh the credentials will be synchronized. But, the SDK is unable to ensure synchronous usage of the AssumeRoleProvider if the value is shared between multiple Credentials, Sessions or service clients.

Assume Role

To assume an IAM role using STS with the SDK you can create a new Credentials with the SDKs's stscreds package.

// Initial credentials loaded from SDK's default credential chain. Such as // the environment, shared credentials (~/.aws/credentials), or EC2 Instance // Role. These credentials will be used to to make the STS Assume Role API. sess := session.Must(session.NewSession()) // Create the credentials from AssumeRoleProvider to assume the role // referenced by the "myRoleARN" ARN. creds := stscreds.NewCredentials(sess, "myRoleArn") // Create service client value configured for credentials // from assumed role. svc := s3.New(sess, &aws.Config{Credentials: creds})

Assume Role with static MFA Token

To assume an IAM role with a MFA token you can either specify a MFA token code directly or provide a function to prompt the user each time the credentials need to refresh the role's credentials. Specifying the TokenCode should be used for short lived operations that will not need to be refreshed, and when you do not want to have direct control over the user provides their MFA token.

With TokenCode the AssumeRoleProvider will be not be able to refresh the role's credentials.

// Create the credentials from AssumeRoleProvider to assume the role // referenced by the "myRoleARN" ARN using the MFA token code provided. creds := stscreds.NewCredentials(sess, "myRoleArn", func(p *stscreds.AssumeRoleProvider) { p.SerialNumber = aws.String("myTokenSerialNumber") p.TokenCode = aws.String("00000000") }) // Create service client value configured for credentials // from assumed role. svc := s3.New(sess, &aws.Config{Credentials: creds})

Assume Role with MFA Token Provider

To assume an IAM role with MFA for longer running tasks where the credentials may need to be refreshed setting the TokenProvider field of AssumeRoleProvider will allow the credential provider to prompt for new MFA token code when the role's credentials need to be refreshed.

The StdinTokenProvider function is available to prompt on stdin to retrieve the MFA token code from the user. You can also implement custom prompts by satisfing the TokenProvider function signature.

Using StdinTokenProvider with multiple AssumeRoleProviders, or Credentials will have undesirable results as the StdinTokenProvider will not be synchronized. A single Credentials with an AssumeRoleProvider can be shared safely.

// Create the credentials from AssumeRoleProvider to assume the role // referenced by the "myRoleARN" ARN. Prompting for MFA token from stdin. creds := stscreds.NewCredentials(sess, "myRoleArn", func(p *stscreds.AssumeRoleProvider) { p.SerialNumber = aws.String("myTokenSerialNumber") p.TokenProvider = stscreds.StdinTokenProvider }) // Create service client value configured for credentials // from assumed role. svc := s3.New(sess, &aws.Config{Credentials: creds})