Assume role credential provider - AWS SDKs and Tools
Assume role credential provider settingsCompatibility with AWS SDKs

Assume role credential provider

Assuming a role involves using a set of temporary security credentials to access AWS resources that you might not have access to otherwise. These temporary credentials consist of an access key ID, a secret access key, and a security token.

To set up your SDK or tool to assume a role, you must first create or identify a specific role to assume. IAM roles are uniquely identified by a role Amazon Resource Name (ARN). Roles establish trust relationships with another entity. The trusted entity that uses the role might be an AWS service, another AWS account, a web identity provider or OIDC, or SAML federation.

After the IAM role is identified, if you are trusted by that role, you can configure your SDK or tool to use the permissions that are granted by the role. To do this, use the following settings.

For guidance on getting started using these settings, see Assume a role in this guide.

Assume role credential provider settings

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:

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.

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. For more information about MFA, see Configuring MFA-Protected API Access in the IAM User Guide.

Example of setting this in a config file:

mfa_serial = arn:aws:iam::123456789012:mfa/my-user-name
role_arn - shared AWS config file setting
AWS_IAM_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_IAM_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.

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
                
[profile B]
aws_access_key_id=AKIAIOSFODNN7EXAMPLE
aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
aws_session_token=IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZVERYLONGSTRINGEXAMPLE

In the previous example, the A profile uses the credentials in the B profile. When you specify that the SDK or tool should use the A profile, the SDK or tool automatically looks up the credentials for the linked B profile and uses them to request temporary credentials for the specified IAM role. The SDK or tool uses the sts:AssumeRole operation in the background to accomplish this. 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.

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.

Compatibility with AWS SDKs

The following SDKs support the features and settings described in this topic. Any partial exceptions are noted. Any JVM system property settings are supported by the AWS SDK for Java and the AWS SDK for Kotlin only.

SDK Supported Notes or more information
AWS CLI v2 Yes
SDK for C++ Partial credential_source not supported. duration_seconds not supported. mfa_serial not supported.
SDK for Go V2 (1.x) Yes
SDK for Go 1.x (V1) Yes To use shared config file settings, you must turn on loading from the config file; see Sessions.
SDK for Java 2.x Partial mfa_serial not supported. Use AWS_ROLE_ARN instead of AWS_IAM_ROLE_ARN. Use AWS_ROLE_SESSION_NAME instead of AWS_IAM_ROLE_SESSION_NAME.
SDK for Java 1.x Partial mfa_serial not supported.
SDK for JavaScript 3.x Yes
SDK for JavaScript 2.x Partial credential_source not supported.
SDK for Kotlin Yes Use AWS_ROLE_ARN instead of AWS_IAM_ROLE_ARN. Use AWS_ROLE_SESSION_NAME instead of AWS_IAM_ROLE_SESSION_NAME.
SDK for .NET 3.x Yes
SDK for PHP 3.x Yes
SDK for Python (Boto3) Yes
SDK for Ruby 3.x Yes
SDK for Rust Yes
Tools for PowerShell Yes