Assume a role with AWS credentials - AWS SDKs and Tools
Assume an IAM role

Assume a role with AWS credentials

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 learn more about AWS Security Token Service (AWS STS) API requests, see Actions in the AWS Security Token Service API Reference.

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 or another AWS account. To learn more about IAM roles, see Using IAM roles in the IAM User Guide.

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.

Note

It is an AWS best practice to use Regional endpoints whenever possible and to configure your AWS Region.

Assume an IAM role

When assuming a role, AWS STS returns a set of temporary security credentials. These credentials are sourced from another profile or from the instance or container that your code is running in. Most commonly this type of assuming a role is used when you have AWS credentials for one account, but your application needs access to resources in another account.

Step 1: Set up an IAM role

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 using a role ARN. Roles establish trust relationships with another entity, typically within your account or for cross-account access. To set this up, see Creating IAM roles in the IAM User Guide.

Step 2: Configure the SDK or tool

Configure the SDK or tool to source credentials from credential_source or source_profile.

Use credential_source to source credentials from an Amazon ECS container, an Amazon EC2 instance, or from environment variables.

Use source_profile to source credentials from another profile. source_profile also supports role chaining, which is hierarchies of profiles where an assumed role is then used to assume another role.

When you specify this in a profile, the SDK or tool automatically makes the corresponding AWS STS AssumeRole API call for you. To retrieve and use temporary credentials by assuming a role, specify the following configuration values in the shared AWS config file. For more details on each of these settings, see the Assume role credential provider settings section.

  • role_arn - From the IAM role you created in Step 1

  • Configure either source_profile or credential_source

  • (Optional) duration_seconds

  • (Optional) external_id

  • (Optional) mfa_serial

  • (Optional) role_session_name

The following examples show the configuration of both assume role options in a shared config file:

role_arn = arn:aws:iam::123456789012:role/my-role-name
source_profile = profile-name-with-user-that-can-assume-role
role_arn = arn:aws:iam::123456789012:role/my-role-name
credential_source = Ec2InstanceMetadata

For details on all assume role credential provider settings, see Assume role credential provider in this guide.