Assume a role - AWS SDKs and Tools

Assume a role

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

Federate with web identity or OpenID Connect

When creating mobile applications or client-based web applications that require access to AWS, AWS 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 AWS 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 AWS about the external IdP and its configuration. This establishes trust between your AWS 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 AWS STS for authentication.

When you specify this in a profile, the SDK or tool automatically makes the corresponding AWS STS AssumeRoleWithWebIdentity API call for you. To retrieve and use temporary credentials using web identity federation, 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

  • web_identity_token_file - From the external IdP

  • (Optional) duration_seconds

  • (Optional) role_session_name

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:iam::123456789012:role/my-role-name web_identity_token_file=/path/to/a/token
Note

For mobile applications, consider using Amazon Cognito. Amazon Cognito acts as an identity broker and does much of the federation work for you. However, the Amazon Cognito identity provider isn't included in the SDKs and tools core libraries like other identity providers. To access the Amazon Cognito API, include the Amazon Cognito service client in the build or libraries for your SDK or tool. For usage with AWS SDKs, see Code Examples in the Amazon Cognito Developer Guide.

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