Assume role credential provider

Configure this functionality by using the following:

credential_source - shared AWS config file setting

Used within Amazon EC2 instances or Amazon Elastic Container Service containers to specify where the SDK or tool can find credentials that have permission to assume the role that you specify with the role_arn parameter.

Default value: None

Valid values:

• Environment – Specifies that the SDK or tool is to retrieve source credentials from the environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.

• Ec2InstanceMetadata – Specifies that the SDK or tool is to use the IAM role attached to the EC2 instance profile to get source credentials.

• EcsContainer – Specifies that the SDK or tool is to use the IAM role attached to the ECS container to get source credentials.

You cannot specify both credential_source and source_profile in the same profile.

Example of setting this in a config file to indicate that credentials should be sourced from Amazon EC2:

credential_source = Ec2InstanceMetadata
role_arn = arn:aws:iam::123456789012:role/my-role-name

duration_seconds - shared AWS config file setting

Specifies the maximum duration of the role session, in seconds.

This setting applies only when the profile specifies to assume a role.

Default value: 3600 seconds (one hour)

Valid values: The value can range from 900 seconds (15 minutes) up to the maximum session duration setting configured for the role (which can be a maximum of 43200 seconds, or 12 hours). For more information, see View the Maximum Session Duration Setting for a Role in the IAM User Guide.

Example of setting this in a config file:

duration_seconds = 43200

external_id - shared AWS config file setting

Specifies a unique identifier that is used by third parties to assume a role in their customers' accounts.

This setting applies only when the profile specifies to assume a role and the trust policy for the role requires a value for ExternalId. The value maps to the ExternalId parameter that is passed to the AssumeRole operation when the profile specifies a role.

Default value: None.

Valid values: See How to use an External ID When Granting Access to Your AWS Resources to a Third Party in the IAM User Guide.

Example of setting this in a config file:

external_id = unique_value_assigned_by_3rd_party

mfa_serial - shared AWS config file setting

Specifies the identification or serial number of a multi-factor authentication (MFA) device that the user must use when assuming a role.

Required when assuming a role where the trust policy for that role includes a condition that requires MFA authentication. For more information about MFA, see AWS Multi-factor authentication in IAM in the IAM User Guide.

Default value: None.

Valid values: The value can be either a serial number for a hardware device (such as GAHT12345678), or an Amazon Resource Name (ARN) for a virtual MFA device. The format of the ARN is: arn:aws:iam::account-id:mfa/mfa-device-name

Example of setting this in a config file:

This example assumes a virtual MFA device, called MyMFADevice, that has been created for the account and enabled for a user.

mfa_serial = arn:aws:iam::123456789012:mfa/MyMFADevice

role_arn - shared AWS config file setting

AWS_ROLE_ARN - environment variable

aws.roleArn - JVM system property: Java/Kotlin only

Specifies the Amazon Resource Name (ARN) of an IAM role that you want to use to perform operations requested using this profile.

Default value: None.

Valid values: The value must be the ARN of an IAM role, formatted as follows: arn:aws:iam::account-id:role/role-name

In addition, you must also specify one of the following settings:

• source_profile – To identify another profile to use to find credentials that have permission to assume the role in this profile.

• credential_source – To use either credentials identified by the current environment variables or credentials attached to an Amazon EC2 instance profile, or an Amazon ECS container instance.

• web_identity_token_file – To use public identity providers or any OpenID Connect (OIDC)-compatible identity provider for users who have been authenticated in a mobile or web application.

role_session_name - shared AWS config file setting

AWS_ROLE_SESSION_NAME - environment variable

aws.roleSessionName - JVM system property: Java/Kotlin only

Specifies the name to attach to the role session. This name appears in AWS CloudTrail logs for entries associated with this session, which can be useful when auditing. For details, see CloudTrail userIdentity element in the AWS CloudTrail User Guide.

Default value: An optional parameter. If you don't provide this value, a session name is generated automatically if the profile assumes a role.

Valid values: Provided to the RoleSessionName parameter when the AWS CLI or AWS API calls the AssumeRole operation (or operations such as the AssumeRoleWithWebIdentity operation) on your behalf. The value becomes part of the assumed role user Amazon Resource Name (ARN) that you can query, and shows up as part of the CloudTrail log entries for operations invoked by this profile.

arn:aws:sts::123456789012:assumed-role/my-role-name/my-role_session_name.

Example of setting this in a config file:

role_session_name = my-role-session-name

source_profile - shared AWS config file setting

Specifies another profile whose credentials are used to assume the role specified by the role_arn setting in the original profile. To understand how profiles are used in the shared AWS config and credentials files, see Shared config and credentials files.

If you specify a profile that is also an assume role profile, each role will be assumed in sequential order to fully resolve the credentials. This chain is stopped when the SDK encounters a profile with credentials. Role chaining limits your AWS CLI or AWS API role session to a maximum of one hour and can't be increased. For more information, see Roles terms and concepts in the IAM User Guide.

Default value: None.

Valid values: A text string that consists of the name of a profile defined in the config and credentials files. You must also specify a value for role_arn in the current profile.

You cannot specify both credential_source and source_profile in the same profile.

Example of setting this in a config file:

[profile A]
source_profile = B
role_arn =  arn:aws:iam::123456789012:role/RoleA
role_session_name = ProfileARoleSession
                
[profile B]
credential_process = ./aws_signing_helper credential-process --certificate /path/to/certificate --private-key /path/to/private-key --trust-anchor-arn arn:aws:rolesanywhere:region:account:trust-anchor/TA_ID --profile-arn arn:aws:rolesanywhere:region:account:profile/PROFILE_ID --role-arn arn:aws:iam::account:role/ROLE_ID

In the previous example, the A profile tells the SDK or tool to automatically look up the credentials for the linked B profile. In this case, the B profile uses the credential helper tool provided by IAM Roles Anywhere to get credentials for the AWS SDK. Those temporary credentials are then used by your code to access AWS resources. The specified role must have attached IAM permissions policies that allow the requested code to run, such as the command, AWS service, or API method. Every action that is taken by profile A has the role session name included in CloudTrail logs.

For a second example of role chaining, the following configuration can be used if you have an application on an Amazon Elastic Compute Cloud instance, and you want to have that application assume another role.

[profile A]
source_profile = B
role_arn =  arn:aws:iam::123456789012:role/RoleA
role_session_name = ProfileARoleSession
                
[profile B]
credential_source=Ec2InstanceMetadata

Profile A will use the credentials from the Amazon EC2 instance to assume the specified role and will renew the credentials automatically.

web_identity_token_file - shared AWS config file setting

AWS_WEB_IDENTITY_TOKEN_FILE - environment variable

aws.webIdentityTokenFile - JVM system property: Java/Kotlin only

Specifies the path to a file that contains an access token from a supported OAuth 2.0 provider or OpenID Connect ID identity provider.

This setting enables authentication by using web identity federation providers, such as Google, Facebook, and Amazon, among many others. The SDK or developer tool loads the contents of this file and passes it as the WebIdentityToken argument when it calls the AssumeRoleWithWebIdentity operation on your behalf.

Default value: None.

Valid values: This value must be a path and file name. The file must contain an OAuth 2.0 access token or an OpenID Connect token that was provided to you by an identity provider. Relative paths are treated as relative to the working directory of the process.