Assume role credentials - AWS SDKs and Tools

Assume role credentials

Assuming a role involves using a set of temporary security credentials that you can use to access AWS resources that you might not normally have access to. These temporary credentials consist of an access key ID, a secret access key, and a security token. Typically, you assume a role within your account or for cross-account access.

To learn more about IAM roles, see Using IAM roles in the IAM User Guide.

To learn more about assuming a role, see AssumeRole in the AWS Security Token Service API Reference.

Configure this functionality by using the following:

credential_source - shared AWS config file setting

Used within Amazon EC2 instances or containers to specify where the SDK or development 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

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.

Example of setting this in a config file:

role_arn = arn:aws:iam::123456789012:role/my-role-name source_profile = profile-with-user-that-can-assume-role
role_arn = arn:aws:iam::123456789012:role/my-role-name credential_source = Ec2InstanceMetadata
role_session_name - shared AWS config file setting

Specifies the name to attach to the role session. This name appears in AWS CloudTrail logs for entries associated with this session.

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 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 static 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.

Note

This setting is an alternative to credential_source. You can't specify both source_profile and credential_source 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
web_identity_token_file - shared AWS config file setting

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.

Example of setting this in a config file:

[profile web-identity] role_arn=arn:aws:iam::123456789012:role/my-role-name web_identity_token_file=/path/to/a/token

Compatibility with AWS SDKS

The following SDKs support the features and settings described on this page, any partial exceptions are noted:

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
SDK for Java 2.x Partial mfa_serial not supported.
SDK for Java 1.x Partial mfa_serial not supported.
SDK for JavaScript 3.x Partial credential_source not supported.
SDK for JavaScript 2.x Partial credential_source not supported.
SDK for .NET 3.x Yes
SDK for PHP 3.x Yes
SDK for Python (Boto3) Yes
SDK for Ruby 3.x Yes