Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Assume a role

Assuming a role involves using a set of temporary security credentials to access Amazon 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 Amazon Security Token Service (Amazon STS) API requests, see Actions in the Amazon 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 Amazon Web Service, another Amazon Web Services account, a web identity provider or OIDC, or SAML federation. 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. To do this, either Assume an IAM role or Federate with web identity or OpenID Connect.

Assume an IAM role

When assuming a role, Amazon 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. Other examples of assuming a role include managing multiple Amazon Web Services accounts from Amazon EC2, using Amazon CodeCommit across Amazon Web Services accounts, or accessing another account from Amazon CodeBuild.

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 Amazon STS AssumeRole API call for you. To retrieve and use temporary credentials by assuming a role, specify the following configuration values in the shared Amazon config file. For more details on each of these settings, see the Assume role credential provider settings section.

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

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

role_arn = arn:aws-cn: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.

Federate with web identity or OpenID Connect

When creating mobile applications or client-based web applications that require access to Amazon, Amazon STS returns a set of temporary security credentials for federated users who are authenticated through a public identity provider (IdP). Examples of public identity providers include Login with Amazon, Facebook, Google, or any OpenID Connect (OIDC)-compatible identity provider. With this method, your users don't need their own Amazon or IAM identities.

If you are using Amazon Elastic Kubernetes Service, this feature provides the ability to specify different IAM roles for each one of your containers. Kubernetes provides capability to distribute OIDC tokens to your containers which are used by this credential provider to obtain temporary credentials. For more information on this Amazon EKS configuration, see IAM roles for service accounts in the Amazon EKS User Guide. However, for a simpler option, we recommend you use Amazon EKS Pod Identities instead if your SDK supports it.

Step 1: Set up an identity provider and IAM role

To configure federation with an external IdP, use an IAM identity provider to inform Amazon about the external IdP and its configuration. This establishes trust between your Amazon Web Services account and the external IdP. Before configuring the SDK to use the web identity token for authentication, you must first set up the identity provider (IdP) and the IAM role used to access it. To set these up, see Creating a role for web identity or OpenID Connect Federation (console) in the IAM User Guide.

Step 2: Configure the SDK or tool

Configure the SDK or tool to use a web identity token from Amazon STS for authentication.

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

The following is an example of a shared config file configuration to assume a role with web identity:

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

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