Containers

Use Amazon ECR global authentication token across AWS Regions

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. CreateBearerToken exchanges your IAM credentials for a bearer token for a supported AWS service. In the AWS Command Line Interface (AWS CLI), the command is aws signin create-bearer-token. For Amazon ECR, you request a token for the resource ecr.amazonaws.com. The principal that requests the token needs the signin:CreateBearerToken permission. 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-seconds parameter, 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 CreateBearerToken event 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-password keep 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:

  1. The client requests a token in one Region. It calls CreateBearerToken at the AWS Sign-In endpoint in a Region you choose, for the resource ecr.amazonaws.com.
  2. AWS Sign-In checks the caller’s IAM credentials and the signin:CreateBearerToken permission.
  3. 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.
  4. The client authenticates to a registry in any Region. It passes the token to docker login for that Region’s registry endpoint. The same token works for Amazon ECR registries in other Regions in the partition.
  5. 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):

for R in us-east-1 us-west-2; do
  TOKEN=$(aws signin create-bearer-token \
    --grant-type client_credentials \
    --resource ecr.amazonaws.com \
    --region $R \
    --cli-connect-timeout 5 \
    --query accessToken \
    --output text) \
    && echo "Token issued by AWS Sign-In in $R" \
    && break
done

The output shows which Region issued the token:

Token issued by AWS Sign-In in us-east-1

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-token command. Run aws --version to 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:

ACCOUNT=$(aws sts get-caller-identity --query Account --output text)
R1=us-east-1
R2=us-west-2
REPO=global-token-demo
docker pull public.ecr.aws/docker/library/alpine:latest
IMAGE=public.ecr.aws/docker/library/alpine:latest
echo "ACCOUNT=$ACCOUNT R1=$R1 R2=$R2 REPO=$REPO IMAGE=$IMAGE"

The echo command confirms the values:

ACCOUNT=111122223333 R1=us-east-1 R2=us-west-2 REPO=global-token-demo IMAGE=public.ecr.aws/docker/library/alpine:latest

Step 1: Grant IAM permissions for the global token

Save the following policy as create-ecr-global-token-policy.json:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "CreateECRGlobalToken",
      "Effect": "Allow",
      "Action": "signin:CreateBearerToken",
      "Resource": "arn:aws:signin:*:*:service-principal/ecr.amazonaws.com"
    }
  ]
}

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:

aws iam put-role-policy --role-name <role-name> --policy-name CreateECRGlobalToken --policy-document file://create-ecr-global-token-policy.json

aws iam attach-role-policy --role-name <role-name> --policy-arn arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryPowerUser

For more information, see Adding and removing IAM identity permissions in the IAM User Guide.

Step 2: Create a global authentication token

TOKEN=$(aws signin create-bearer-token \
  --grant-type client_credentials \
  --resource ecr.amazonaws.com \
  --duration-seconds 3600 \
  --region $R1 \
  --query accessToken \
  --output text)
  • --grant-type is always client_credentials.
  • --resource ecr.amazonaws.com requests a token for Amazon ECR.
  • --duration-seconds 3600 sets a 1-hour lifetime.
  • --region picks 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.

{
  "accessToken": "ASOAeyJraWQi...",
  "tokenType": "Bearer",
  "expiresIn": 3600
}

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:

printf '%s' "$TOKEN" | docker login --username AWS --password-stdin $ACCOUNT.dkr.ecr.$R1.amazonaws.com
docker tag $IMAGE $ACCOUNT.dkr.ecr.$R1.amazonaws.com/$REPO:v1
docker push --quiet $ACCOUNT.dkr.ecr.$R1.amazonaws.com/$REPO:v1

The output shows that the login succeeded and the image was pushed:

Login Succeeded

111122223333.dkr.ecr.us-east-1.amazonaws.com/global-token-demo:v1

Use the same token for the registry in us-west-2:

printf '%s' "$TOKEN" | docker login --username AWS --password-stdin $ACCOUNT.dkr.ecr.$R2.amazonaws.com
docker tag $IMAGE $ACCOUNT.dkr.ecr.$R2.amazonaws.com/$REPO:v1
docker push --quiet $ACCOUNT.dkr.ecr.$R2.amazonaws.com/$REPO:v1

The same token works for the registry in the second Region:

Login Succeeded

111122223333.dkr.ecr.us-west-2.amazonaws.com/global-token-demo:v1

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:

docker rmi $ACCOUNT.dkr.ecr.$R1.amazonaws.com/$REPO:v1
docker rmi $ACCOUNT.dkr.ecr.$R2.amazonaws.com/$REPO:v1
docker rmi $IMAGE

The output confirms that no local copy remains:

Untagged: 111122223333.dkr.ecr.us-east-1.amazonaws.com/global-token-demo:v1
Untagged: 111122223333.dkr.ecr.us-west-2.amazonaws.com/global-token-demo:v1
Untagged: public.ecr.aws/docker/library/alpine:latest
Deleted: sha256:f59abe656b692d901e184be3445e084786602108599d2a51d229c0f5a48c71bf

Pull the image from each Region:

docker pull --quiet $ACCOUNT.dkr.ecr.$R1.amazonaws.com/$REPO:v1
docker pull --quiet $ACCOUNT.dkr.ecr.$R2.amazonaws.com/$REPO:v1

Both pulls succeed:

111122223333.dkr.ecr.us-east-1.amazonaws.com/global-token-demo:v1
111122223333.dkr.ecr.us-west-2.amazonaws.com/global-token-demo:v1

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:

aws iam put-role-policy --role-name <role-name> --policy-name IntrospectECRGlobalToken --policy-document '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Action":"signin:IntrospectOAuth2Token","Resource":"*"}]}'

Then inspect the token by using the aws signin command.

aws signin introspect-oauth2-token-with-iam --token "$TOKEN" --region $R1

The output shows the token’s claims:

{
  "active": true,
  "clientId": "arn:aws:signin:::client-credentials/sigv4",
  "tokenType": "access_token",
  "exp": 1794558040,
  "iat": 1794554440,
  "nbf": 1794554440,
  "sub": "arn:aws:sts::111122223333:assumed-role/ecr-global-token-demo/global-token-test",
  "aud": "ecr.amazonaws.com",
  "iss": "signin.amazonaws.com",
  "jti": "39d174c0-b719-4488-9400-f5695025d2df",
  "accountId": "111122223333",
  "signinSession": "arn:aws:signin:us-east-1:111122223333:session/18e1256f-185b-4c7d-92cf-ae86f4593073"
}

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:

aws cloudtrail lookup-events \
  --lookup-attributes AttributeKey=EventName,AttributeValue=CreateBearerToken \
  --max-results 1 \
  --query 'Events[0].CloudTrailEvent' \
  --output text \
  --region $R1 | python3 -m json.tool

The following excerpt from the event shows the token request:

{
  "eventSource": "signin.amazonaws.com",
  "eventName": "CreateBearerToken",
  "awsRegion": "us-east-1",
  "requestParameters": {
    "resource": "ecr.amazonaws.com",
    "client_id": "arn:aws:signin:::client-credentials/sigv4"
  },
  "responseElements": null,
  "additionalEventData": {
    "signInSessionArn": "arn:aws:signin:us-east-1:111122223333:session/18e1256f-185b-4c7d-92cf-ae86f4593073",
    "grant_type": "client_credentials",
    "success": "true",
    "DurationSeconds": "3600"
  }
}

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:

aws cloudtrail lookup-events \
  --lookup-attributes AttributeKey=EventName,AttributeValue=BatchGetImage \
  --max-results 1 \
  --query 'Events[0].CloudTrailEvent' \
  --output text \
  --region $R2 | python3 -m json.tool

The event carries the same session ARN in userIdentity.sessionContext.signInSessionArn:

{
  "userIdentity": {
    "type": "AssumedRole",
    "arn": "arn:aws:sts::111122223333:assumed-role/ecr-global-token-demo/global-token-test",
    "accountId": "111122223333",
    "sessionContext": {
      "signInSessionArn": "arn:aws:signin:us-east-1:111122223333:session/18e1256f-185b-4c7d-92cf-ae86f4593073"
    }
  },
  "eventTime": "2026-11-13T07:22:10Z",
  "eventSource": "ecr.amazonaws.com",
  "eventName": "BatchGetImage",
  "awsRegion": "us-west-2",
  "requestParameters": {
    "registryId": "111122223333",
    "repositoryName": "global-token-demo"
  }
}

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.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "DenySpecificSignInSession",
      "Effect": "Deny",
      "Action": "*",
      "Resource": "*",
      "Condition": {
        "ArnEquals": {
          "aws:SignInSessionArn": "arn:aws:signin:us-east-1:111122223333:session/18e1256f-185b-4c7d-92cf-ae86f4593073"
        }
      }
    }
  ]
}

Cleaning up

Delete the repositories in both Regions and log out of both registries. The --force option also deletes the images in each repository.

aws ecr delete-repository --repository-name $REPO --force --region $R1
aws ecr delete-repository --repository-name $REPO --force --region $R2
docker logout $ACCOUNT.dkr.ecr.$R1.amazonaws.com
docker logout $ACCOUNT.dkr.ecr.$R2.amazonaws.com

Remove the policies you added to the role in Steps 1 and 5. Detach AmazonEC2ContainerRegistryPowerUser only if you attached it for this walkthrough:

aws iam delete-role-policy --role-name <role-name> --policy-name CreateECRGlobalToken

aws iam delete-role-policy --role-name <role-name> --policy-name IntrospectECRGlobalToken

aws iam detach-role-policy --role-name <role-name> --policy-arn arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryPowerUser

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

aws signin create-bearer-token --grant-type client_credentials --resource ecr.amazonaws.com

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.


About the authors

Sourav Kundu

Sourav Kundu

Sourav is a DevOps Consultant at AWS. He helps organizations securely migrate to and efficiently build on the AWS cloud using modern software engineering practices. He believes that democratizing cloud knowledge is essential for driving innovation and is committed to helping others succeed in their cloud journey.

Gaurav Gundal

Gaurav Gundal

Gaurav is a Senior DevOps consultant with AWS Professional Services, helping customers build solutions on the customer platform. When not building, designing, or developing solutions, Gaurav spends time with his family, plays guitar, and enjoys traveling to different places.

Meg Sarros

Meg Sarros

Meg is a Senior Product Manager for Amazon ECR. She is based in New York City. In her spare time, she enjoys tennis and baking.