Customers run containerized workloads in more than one AWS Region to reduce latency for their users, meet data residency and regulatory requirements. Running in more than one Region also keeps workload available during a Regional disruption. Some customers put a routing layer in front of Amazon Elastic Container Registry (Amazon ECR) Regional OCI endpoints, such as a custom proxy, that sends image pushes and pulls to the nearest healthy Region. The routing layer sends image pushes and pulls to the nearest healthy Region. An Amazon ECR authorization token comes from a Regional endpoint, works only in that Region, and lasts a fixed 12 hours. When the routing layer sends a request to a different Region, the container client first needs a token from that Region. Customers either fetch a token for every Region in advance or fetch one each time the routing decision changes.
If one token worked in every Region, the routing layer could choose a Region without also managing authentication. An image push or pull request that the routing layer moves from one Region to another during a disruption would succeed with the token the client already has.
Amazon ECR now supports global authentication, which simplifies this workflow. You request one token from AWS Sign-In and use it to push and pull images in any AWS Region in the same partition. By default, this token is valid for 12 hours and you can lower the lifetime to as little as 5 minutes. In this post, we show you how to request a global token and use it to push and pull images across two Regions.
What we are launching
Today we are launching global authentication tokens for Amazon ECR. The launch includes the following:
- A new AWS Sign-In API.
CreateBearerTokenexchanges your IAM credentials for a bearer token for a supported AWS service. In the AWS Command Line Interface (AWS CLI), the command isaws signin create-bearer-token. For Amazon ECR, you request a token for the resourceecr.amazonaws.com. The principal that requests the token needs thesignin:CreateBearerTokenpermission. The token carries the principal’s IAM permissions and doesn’t add any. - A token for every Region in the partition. Amazon ECR accepts the global token at its regional endpoints in all AWS Regions in the same partition, for any supported OCI operation, including push, pull, delete, and referrers. For opt-in Regions, your account must be opted in to the Region for requests to succeed.
- A lifetime you set. A global token lasts 12 hours by default, the same as a regional token. You can request a lifetime as short as 5 minutes with the
--duration-secondsparameter, for automation, deployment jobs, and other workloads that don’t need a 12-hour token. A shorter lifetime reduces the period in which an exposed token remains usable. - Global token support in Amazon ECR authentication tools. The Amazon ECR Docker Credential Helper, Kubernetes ECR credential provider, and Amazon ECR Login action for GitHub Actions can now get a global token. You opt in where you configure each tool. For the credential helper, version 0.13.0 or later, set
AWS_ECR_PRIVATE_TOKEN_TYPE=global-token. Existing configurations keep using Regional tokens. - Token activity you can trace across AWS Regions. Each global token is issued in its own AWS Sign-In session, and AWS CloudTrail records that session ARN on the
CreateBearerTokenevent and on the Amazon ECR events the token authorizes. Security teams use this shared identifier to correlate image activity with the token request that authorized it, investigate use across Regions, and deny requests from a specific sign-in session without affecting other sessions. Regional authorization tokens don’t carry this context. - Global tokens preserve the existing Amazon ECR security model. Amazon ECR evaluates the requesting principal’s IAM permissions on every operation, and the token grants no additional permissions.
The following doesn’t change:
- Regional tokens from
aws ecr get-login-passwordkeep working, so existing pipelines need no changes. If each of your clusters pulls only from the registry in its own Region, a regional token still fits. - Registries, repositories, and endpoints stay regional. Images stay in the AWS Region you push them to, and replication still copies them to other Regions.
- The IAM permissions your principals need for Amazon ECR actions.
How it works
Pushing or pulling an image takes two steps: get a token, then push or pull at a regional registry endpoint.
With the global token: One token for the partition
With a global token, the flow works like this:
- The client requests a token in one Region. It calls
CreateBearerTokenat the AWS Sign-In endpoint in a Region you choose, for the resourceecr.amazonaws.com. - AWS Sign-In checks the caller’s IAM credentials and the
signin:CreateBearerTokenpermission. - AWS Sign-In returns a bearer token. The token is scoped to Amazon ECR and to the IAM principal that requested it. It expires after the lifetime you requested: 12 hours by default, or as little as 5 minutes.
- The client authenticates to a registry in any Region. It passes the token to
docker loginfor that Region’s registry endpoint. The same token works for Amazon ECR registries in other Regions in the partition. - Amazon ECR authorizes each request. For every push or pull, Amazon ECR validates the token and checks the principal’s IAM permissions for that action, as it does for a regional token.
For example, the following loop tries the US East (N. Virginia) Region (us-east-1) first and falls back to the US West (Oregon) Region (us-west-2):
The output shows which Region issued the token:
Prerequisites
- An AWS account and two AWS Regions to work in. This walkthrough uses us-east-1 and us-west-2.
- AWS CLI version 2.39.7 or later, which adds the
aws signin create-bearer-tokencommand. Runaws --versionto check. - Docker installed and running.
- An ECR private repository with the same name in both Regions.
- A local container image to push.
- IAM permissions for the new token API (see Step 1).
- If you use AWS PrivateLink: a virtual private cloud (VPC) endpoint for the sign-in service.
Implementation walkthrough
The following steps request one global token in us-east-1 and use it to push and pull an image in us-east-1 and us-west-2. Start by setting the variables that the commands use, and pull a sample image to push:
The echo command confirms the values:
Step 1: Grant IAM permissions for the global token
Save the following policy as create-ecr-global-token-policy.json:
The resource limits the permission to tokens for Amazon ECR. Attach the policy to the IAM role that requests the token. The role also needs Amazon ECR permissions to push and pull, such as those in the AmazonEC2ContainerRegistryPowerUser managed policy. Replace <role-name> with the name of your role:
For more information, see Adding and removing IAM identity permissions in the IAM User Guide.
Step 2: Create a global authentication token
--grant-typeis alwaysclient_credentials.--resource ecr.amazonaws.comrequests a token for Amazon ECR.--duration-seconds 3600sets a 1-hour lifetime.--regionpicks the AWS Sign-In endpoint that issues the token. It doesn’t limit where the token works.
Without the --query and --output options, the command returns the full response, and the response contains the token, its type, and its lifetime.
expiresIn is the token’s lifetime in seconds, matching the --duration-seconds value in the request. When you omit --duration-seconds, the token is valid for 12 hours.
As with an Amazon ECR Regional token, the length of a global token is not fixed. Before you adopt global tokens broadly, verify that your credential stores and container tooling accept variable-length credentials.
The token is a credential. Don’t print it, log it, or commit it to source control.
Step 3: Push an image to both Regions with the same token
Authenticate to the registry in us-east-1 and push the image:
The output shows that the login succeeded and the image was pushed:
Use the same token for the registry in us-west-2:
The same token works for the registry in the second Region:
Docker stores credentials for each registry hostname, so you run docker login once for each registry. You reuse the same token each time.
Step 4: Pull the image from both AWS Regions with the same token
Remove the local copies so that the docker pull commands download from Amazon ECR:
The output confirms that no local copy remains:
Pull the image from each Region:
Both pulls succeed:
Both pulls use the token from Step 2: one in the Region where you requested it, and one in another Region. The Region you request the token from doesn’t limit where you can use the token in the partition.
Step 5: Inspect the token
Check whether the token is still active and when it expires. To run this command, the principal also needs the signin:IntrospectOAuth2Token permission. Add it to the role from Step 1. Run this command with an identity that can update IAM roles:
Then inspect the token by using the aws signin command.
The output shows the token’s claims:
Examining the output, active is true until the token expires. exp and iat are the expiry and issue times in Unix seconds, and their difference matches the --duration-seconds value from Step 2. sub is the IAM principal that requested the token, aud shows that the token is for Amazon ECR, and signinSession is the AWS Sign-In session the token belongs to.
signinSession is the handle that ties this token to activity in your account. Amazon ECR requests made with the token include the same value as aws:SignInSessionArn context, so you can correlate image pushes and pulls with the sign-in session that issued the token. Security teams can use that to monitor how global tokens are used, investigate authorization activity, and detect anomalous behavior. They can feed these events into existing auditing, compliance, and incident response workflows alongside other AWS activity. Step 6 shows this in AWS CloudTrail.
Step 6: Trace Amazon ECR requests to the token request
Amazon ECR requests made with a global token carry the aws:SignInSessionArn context key, which identifies the AWS Sign-In session the token was issued in. AWS CloudTrail records that session ARN on the CreateBearerToken event and on the Amazon ECR events the token authorizes. You can use it to match image pulls to the token request, in every Region where the token was used.
Look up the token request in the Region where you requested it:
The following excerpt from the event shows the token request:
DurationSeconds is the lifetime granted to the token. You can use it to see which principals request long-lived tokens.
CloudTrail records each Amazon ECR request in the Region where it was made. Look up the pull from Step 4 in us-west-2:
The event carries the same session ARN in userIdentity.sessionContext.signInSessionArn:
The session ID in this us-west-2 event matches the session from the CreateBearerToken event in us-east-1, so you can trace the pull back to the token request.
Use the aws:SignInSessionArn global condition key to deny authorization for a specific sign-in session. With it, administrators can contain a suspicious or compromised token without affecting other active sessions.
Cleaning up
Delete the repositories in both Regions and log out of both registries. The --force option also deletes the images in each repository.
Remove the policies you added to the role in Steps 1 and 5. Detach AmazonEC2ContainerRegistryPowerUser only if you attached it for this walkthrough:
If you created a sign-in VPC endpoint, delete it too.
Try it today
Amazon ECR global authentication tokens are available today in all AWS commercial Regions. To start, upgrade to AWS CLI version 2.39.7 or later, request a token with
and pass it to docker login for any Amazon ECR registry in the partition. Regional tokens keep working, so you can move to global tokens one client at a time.
- Private registry authentication in Amazon ECR in the Amazon ECR User Guide.
- CreateBearerToken in the AWS Sign-In API Reference.
- create-bearer-token in the AWS CLI Command Reference.





