View a markdown version of this page

Federating AWS identities across AWS partitions - AWS Identity and Access Management
How cross-partition identity federation works

Federating AWS identities across AWS partitions

Cross-partition identity federation allows a workload to obtain short-lived access across AWS partitions. AWS partitions are hard isolation boundaries with independent instances of AWS Identity and Access Management (IAM), so a credential issued in one partition isn't valid in another. As a result, direct role assumption with the AssumeRole API doesn't work across partition boundaries.

Cross-partition identity federation works as a two-step exchange: your workload calls sts:GetWebIdentityToken to obtain a short-lived JSON Web Token (JWT) from AWS Security Token Service (STS) in the source partition. It then calls sts:AssumeRoleWithWebIdentity to exchange the token for temporary credentials in the destination partition. This approach lets the workload use temporary credentials in both partitions, following the IAM best practice of using temporary credentials for workloads.

Note

  • Cross-partition identity federation is available in the commercial AWS Regions (aws), the China Regions (aws-cn), the AWS GovCloud (US) Regions (aws-us-gov), and the AWS European Sovereign Cloud (aws-eusc).

  • The destination role must be in a different AWS partition from the one where the token was issued. The JWTs from GetWebIdentityToken cannot be used for OpenID Connect (OIDC) federation into the same partition through AssumeRoleWithWebIdentity. For role assumption within a partition, use the AssumeRole API instead.

  • If your workload requires cross-partition access, consult your compliance team to make sure that your implementation aligns with your regulatory or compliance obligations.

How cross-partition identity federation works

Your workload first requests a token from AWS STS in the source partition, then sends the token to AWS STS in the destination partition. To validate the request, AWS STS in the destination partition retrieves verification keys from the source account's OIDC issuer, verifies the token, and evaluates the destination role's trust policy. If the request is allowed, AWS STS returns temporary credentials to the workload, which uses them to call services and access resources in the destination partition.

Source STS issues a token; destination STS validates it and returns credentials the workload uses to access resources.

The numbered steps that follow describe each request and response in the diagram.

The flow works as follows:

  1. Token request: Your workload, running in an AWS Region in the source partition (for example, us-east-1 in the aws partition), calls the sts:GetWebIdentityToken API.

  2. Token issuance: AWS STS returns a short-lived, cryptographically signed JWT. The token contains claims that assert your workload's AWS identity, including the account ID, the principal Amazon Resource Name (ARN), the source AWS Region, and more.

  3. Token presentation: Your workload calls sts:AssumeRoleWithWebIdentity on the AWS STS endpoint in an AWS Region in the destination partition (for example, cn-north-1 in the aws-cn partition), passing the JWT as the web identity token and the ARN of the target role in the destination partition.

  4. Fetch verification keys and metadata: AWS STS in the destination partition retrieves the public verification key from the JWKS endpoint of the source account's issuer URL.

  5. Validation: AWS STS in the destination partition verifies the token's signature and evaluates the target role's trust policy.

  6. Return temporary credentials: AWS STS in the destination partition returns temporary credentials scoped by the policies attached to the role.

  7. Cross-partition resource access: Your workload uses the temporary credentials to access resources in the destination partition, such as an Amazon S3 bucket.

For more information, see the following topics: