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.

AssumeRoleProvider

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

type AssumeRoleProvider struct { credentials.Expiry Client AssumeRoler RoleARN string RoleSessionName string Duration time.Duration ExternalID *string Policy *string SerialNumber *string TokenCode *string TokenProvider func() (string, error) ExpiryWindow time.Duration }

AssumeRoleProvider retrieves temporary credentials from the STS service, and keeps track of their expiration time.

This credential provider will be used by the SDKs default credential change when shared configuration is enabled, and the shared config or shared credentials file configure assume role. See Session docs for how to do this.

AssumeRoleProvider does not provide any synchronization and it is not safe to share this value across multiple Credentials, Sessions, or service clients without also sharing the same Credentials instance.

Expiry

Type: credentials.Expiry

Client

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

RoleARN

Type: string

Role to be assumed.

RoleSessionName

Type: string

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

Duration

Type: time.Duration

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

ExternalID

Type: *string

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

Policy

Type: *string

The policy plain text must be 2048 bytes or shorter. However, an internal conversion compresses it into a packed binary format with a separate limit. The PackedPolicySize response element indicates by percentage how close to the upper size limit the policy is, with 100% equaling the maximum allowed size.

SerialNumber

Type: *string

The identification number of the MFA device that is associated with the user who is making the AssumeRole call. Specify this value if the trust policy of the role being assumed includes a condition that requires MFA authentication. The value is either the serial number for a hardware device (such as GAHT12345678) or an Amazon Resource Name (ARN) for a virtual device (such as arn:aws:iam::123456789012:mfa/user).

TokenCode

Type: *string

The value provided by the MFA device, if the trust policy of the role being assumed requires MFA (that is, if the policy includes a condition that tests for MFA). If the role being assumed requires MFA and if the TokenCode value is missing or expired, the AssumeRole call returns an "access denied" error.

If SerialNumber is set and neither TokenCode nor TokenProvider are also set an error will be returned.

TokenProvider

Type: func() (string, error)

Async method of providing MFA token code for assuming an IAM role with MFA. The value returned by the function will be used as the TokenCode in the Retrieve call. See StdinTokenProvider for a provider that prompts and reads from stdin.

This token provider will be called when ever the assumed role's credentials need to be refreshed when SerialNumber is also set and TokenCode is not set.

If both TokenCode and TokenProvider is set, TokenProvider will be used and TokenCode is ignored.

ExpiryWindow

Type: time.Duration

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.

Method

Retrieve

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

Retrieve generates a new set of temporary credentials using STS.

On this page: