diff --git a/.changelog/ea9496c040f44c2db8807f5dbc80088a.json b/.changelog/ea9496c040f44c2db8807f5dbc80088a.json new file mode 100644 index 00000000000..4abb34915ae --- /dev/null +++ b/.changelog/ea9496c040f44c2db8807f5dbc80088a.json @@ -0,0 +1,8 @@ +{ + "id": "ea9496c0-40f4-4c2d-b880-7f5dbc80088a", + "type": "documentation", + "description": "Fixes the AssumeRoleProvider's documentation for using custom TokenProviders.", + "modules": [ + "credentials" + ] +} \ No newline at end of file diff --git a/credentials/stscreds/assume_role_provider.go b/credentials/stscreds/assume_role_provider.go index 4b94f8bdc49..3cafa4811b5 100644 --- a/credentials/stscreds/assume_role_provider.go +++ b/credentials/stscreds/assume_role_provider.go @@ -32,27 +32,31 @@ // // from assumed role. // svc := s3.NewFromConfig(cfg) // -// Assume Role with static MFA Token +// Assume Role with custom MFA Token provider // -// 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. +// To assume an IAM role with a MFA token you can either specify a custom MFA +// token provider or use the SDK's built in StdinTokenProvider that will prompt +// the user for a token code each time the credentials need to to be refreshed. +// Specifying a custom token provider allows you to control where the token +// code is retrieved from, and how it is refreshed. // -// With TokenCode the AssumeRoleProvider will be not be able to refresh the role's -// credentials. +// With a custom token provider, the provider is responsible for refreshing the +// token code when called. // // cfg, err := config.LoadDefaultConfig(context.TODO()) // if err != nil { // panic(err) // } // +// staticTokenProvider := func() (string, error) { +// return someTokenCode, nil +// } +// // // Create the credentials from AssumeRoleProvider to assume the role // // referenced by the "myRoleARN" ARN using the MFA token code provided. // creds := stscreds.NewAssumeRoleProvider(sts.NewFromConfig(cfg), "myRoleArn", func(o *stscreds.AssumeRoleOptions) { // o.SerialNumber = aws.String("myTokenSerialNumber") -// o.TokenCode = aws.String("00000000") +// o.TokenProvider = staticTokenProvider // }) // // cfg.Credentials = aws.NewCredentialsCache(creds) @@ -209,11 +213,7 @@ type AssumeRoleOptions struct { // 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. + // credentials need to be refreshed when SerialNumber is set. TokenProvider func() (string, error) // A list of session tags that you want to pass. Each session tag consists of a key @@ -281,7 +281,7 @@ func (p *AssumeRoleProvider) Retrieve(ctx context.Context) (aws.Credentials, err } input.TokenCode = aws.String(code) } else { - return aws.Credentials{}, fmt.Errorf("assume role with MFA enabled, but neither TokenCode nor TokenProvider are set") + return aws.Credentials{}, fmt.Errorf("assume role with MFA enabled, but TokenProvider is not set") } }