Assume a role with web identity or OpenID Connect
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 a web identity provider or OpenID Connect(OIDC), or SAML federation. To learn more about IAM roles, see Methods to assume a role in the IAM User Guide.
After the IAM role is configured in your SDK, if that role is configured to trust your identity provider, you can further configure your SDK to assume that role in order to get temporary Amazon credentials.
Note
It is an Amazon best practice to use Regional endpoints whenever possible and to configure your Amazon Web Services Region.
Federate with web identity or OpenID Connect
You can use the JSON Web Tokens (JWTs) from public identity providers, such as Login
With Amazon, Facebook, Google to get temporary Amazon credentials using
AssumeRoleWithWebIdentity
. Depending on how they are used, these JWTs
may be called ID tokens or access tokens. You may also use JWTs issued from identity
providers (IdPs) that are compatible with OIDC’s discovery protocol, such as EntraId or
PingFederate.
If you are using Amazon Elastic Kubernetes Service, this feature provides the ability to specify different IAM roles for each one of your service accounts in an Amazon EKS cluster. This Kubernetes feature distributes JWTs to your pods which are then used by this credential provider to obtain temporary Amazon 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 JSON Web Token (JWT) 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 JSON Web Token (JWT) 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.
-
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-cn: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 Amazon 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.