credentials: Fix AssumeRoleProvider documentation for TokenProvider (a…

…ws#1406)

Fixes the AssumeRoleProvider's documentation and error message for using custom TokenProviders.

Fixes aws#1384

.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"
+    ]
+}

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")
 		}
 	}