AWS Security ChangesHomeSearch

AWS AmazonECR: Document ECR global and regional registry authentication tokens

Service: AmazonECR · 2026-11-18 · Documentation medium

File: AmazonECR/latest/userguide/registry_auth.md · Type: iam

Summary

Rewrites the ECR private registry authentication guide to introduce a new AWS Sign-In-issued 'global token' (CreateBearerToken) alongside the existing regional token (GetAuthorizationToken). Adds a comparison table (region scope, validity, configurable lifetime down to 5 minutes), the required signin:CreateBearerToken IAM policy, security/auditing capabilities (CloudTrail signInSessionArn correlation, IntrospectOAuth2TokenWithIAM), and updated Docker/HTTP API authentication examples for both token types.

Security assessment

The change documents authentication to the ECR private registry, including a new bearer-token mechanism with a scoped IAM permission (signin:CreateBearerToken on arn:aws:signin:*:*:service-principal/ecr.amazonaws.com), configurable short token lifetimes, CloudTrail session correlation, and token introspection. It clarifies that tokens inherit IAM permissions and grant no extra access, which is security-relevant guidance, but it does not reference or remediate any specific vulnerability, CVE, or incident.

Evidence

+The permission scope of a regional token or global token matches your IAM permissions. An authentication token doesn't give you additional Amazon ECR permissions. You must still have permission to perform the requested Amazon ECR actions.

Diff

diff --git a/AmazonECR/latest/userguide/registry_auth.md b/AmazonECR/latest/userguide/registry_auth.md
index 4e17a38..e32cf5a 100644
--- a//AmazonECR/latest/userguide/registry_auth.md
+++ b//AmazonECR/latest/userguide/registry_auth.md
@@ -7 +7 @@
-Using the Amazon ECR credential helperUsing an authorization tokenUsing HTTP API authentication
+Using a global tokenUsing a regional tokenUsing HTTP API authenticationUsing the Amazon ECR credential helper
@@ -15 +15 @@ The Docker CLI doesn't support native IAM authentication methods. Additional ste
-The registry authentication methods that are detailed in the following sections are available.
+You can use a regional token or a global token to authenticate to an Amazon ECR private registry. The following table compares regional tokens and global tokens.
@@ -17,3 +17,4 @@ The registry authentication methods that are detailed in the following sections
-## Using the Amazon ECR credential helper
-
-Amazon ECR provides a Docker credential helper which makes it easier to store and use Docker credentials when pushing and pulling images to Amazon ECR. For installation and configuration steps, see [Amazon ECR Docker Credential Helper](https://github.com/awslabs/amazon-ecr-credential-helper).
+Token type | Token request | AWS Region scope | Validity  
+---|---|---|---  
+Global token | AWS Sign-In [CreateBearerToken](https://docs.aws.amazon.com/signin/latest/APIReference/API_dataplane-signin_CreateBearerToken.html) or `aws signin create-bearer-token` | Valid in all AWS Regions in the same partition | 12 hours by default, with configurable duration support  
+Regional token | Amazon ECR [GetAuthorizationToken](https://docs.aws.amazon.com/AmazonECR/latest/APIReference/API_GetAuthorizationToken.html) or `aws ecr get-login-password` | Valid in the same AWS Region that issued the token | 12 hours  
@@ -23 +24,47 @@ Note
-The Amazon ECR Docker credential helper doesn't support multi-factor authentication (MFA) currently.
+The permission scope of a regional token or global token matches your IAM permissions. An authentication token doesn't give you additional Amazon ECR permissions. You must still have permission to perform the requested Amazon ECR actions.
+
+## Using a global token
+
+With an Amazon ECR _global token_ , you can authenticate to Amazon ECR registry endpoints in AWS Regions of a single partition. AWS Sign-In issues each global token as a bearer token for the `ecr.amazonaws.com` resource. A global token supports a configurable lifetime as short as 5 minutes. If you don't specify a duration, the default lifetime is 12 hours.
+
+Before you request a global token, make sure that you have `signin:CreateBearerToken` permission and the Amazon ECR permissions required for your image or repository operations. The following IAM policy grants permission to request a global token for Amazon ECR:
+    
+    
+    {
+        "Version": "2012-10-17",
+        "Statement": [
+            {
+                "Sid": "CreateECRGlobalToken",
+                "Effect": "Allow",
+                "Action": "signin:CreateBearerToken",
+                "Resource": "arn:aws:signin:*:*:service-principal/ecr.amazonaws.com"
+            }
+        ]
+    }
+
+Global tokens provide the following security and auditing capabilities:
+
+  * Use the `signInSessionArn` field in the `userIdentity.sessionContext` element of CloudTrail events to correlate token usage with the AWS session that requested the token. For more information, see [CloudTrail userIdentity element](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html).
+
+  * Use the [IntrospectOAuth2TokenWithIAM](https://docs.aws.amazon.com/signin/latest/APIReference/API_dataplane-signin_IntrospectOAuth2TokenWithIAM.html) API operation to check a token's active state and metadata.
+
+
+
+
+###### To authenticate Docker to an Amazon ECR private registry with a global token
+
+  1. Use the [create-bearer-token](https://docs.aws.amazon.com/cli/latest/reference/signin/create-bearer-token.html) AWS CLI command to request the default 12-hour global token for Amazon ECR.
+    
+        TOKEN=$(aws signin create-bearer-token \
+         --grant-type client_credentials \
+         --resource ecr.amazonaws.com \
+         --region token_region \
+         --query accessToken \
+         --output text)
+
+  2. Pass the global token to `docker login`, and specify `AWS` as the username.
+    
+        printf '%s' "$TOKEN" | docker login \
+         --username AWS \
+         --password-stdin \
+         aws_account_id.dkr.ecr.registry_region.amazonaws.com
@@ -25 +71,0 @@ The Amazon ECR Docker credential helper doesn't support multi-factor authenticat
-## Using an authorization token
@@ -27 +72,0 @@ The Amazon ECR Docker credential helper doesn't support multi-factor authenticat
-An authorization token's permission scope matches that of the IAM principal used to retrieve the authentication token. An authentication token is used to access any Amazon ECR registry that your IAM principal has access to and is valid for 12 hours. To obtain an authorization token, you must use the [GetAuthorizationToken](https://docs.aws.amazon.com/AmazonECR/latest/APIReference/API_GetAuthorizationToken.html) API operation to retrieve a base64-encoded authorization token containing the username `AWS` and an encoded password. The AWS CLI ` get-login-password` command simplifies this by retrieving and decoding the authorization token which you can then pipe into a **docker login** command to authenticate.
@@ -29 +73,0 @@ An authorization token's permission scope matches that of the IAM principal used
-###### To authenticate Docker to an Amazon ECR private registry with get-login
@@ -31 +75 @@ An authorization token's permission scope matches that of the IAM principal used
-  * To authenticate Docker to an Amazon ECR registry with get-login-password, run the **aws ecr get-login-password** command. When passing the authentication token to the **docker login** command, use the value `AWS` for the username and specify the Amazon ECR registry URI you want to authenticate to. If authenticating to multiple registries, you must repeat the command for each registry.
+## Using a regional token
@@ -33 +77 @@ An authorization token's permission scope matches that of the IAM principal used
-Important
+A regional token is valid for 12 hours in the same AWS Region that issued the token. To obtain a regional token, use the [GetAuthorizationToken](https://docs.aws.amazon.com/AmazonECR/latest/APIReference/API_GetAuthorizationToken.html) API operation to retrieve a base64-encoded authorization token containing the username `AWS` and an encoded password. The AWS CLI `get-login-password` command simplifies this by retrieving and decoding the token, which you can then pipe into a `docker login` command to authenticate.
@@ -35 +79,5 @@ Important
-If you receive an error, install or upgrade to the latest version of the AWS CLI. For more information, see [Installing the AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) in the _AWS Command Line Interface User Guide_.
+###### To authenticate Docker to an Amazon ECR private registry with a regional token
+
+  1. Configure the AWS CLI to interact with AWS. For more information, see [AWS CLI configuration basics](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) in the _AWS Command Line Interface User Guide_.
+
+  2. Use one of the following commands to authenticate to an Amazon ECR private registry. For **docker login** , use `AWS` as the username and specify the Amazon ECR registry URI. Repeat the command for each registry that you want to authenticate to.
@@ -50 +98,14 @@ If you receive an error, install or upgrade to the latest version of the AWS CLI
-Amazon ECR supports the [Docker Registry HTTP API](https://docs.docker.com/registry/spec/api/). However, because Amazon ECR is a private registry, you must provide an authorization token with every HTTP request. You can add an HTTP authorization header using the `-H` option for **curl** and pass the authorization token provided by the **get-authorization-token** AWS CLI command.
+Amazon ECR supports the [Docker Registry HTTP API](https://docs.docker.com/registry/spec/api/). However, because Amazon ECR is a private registry, you must provide a registry authentication token with every HTTP request. The following examples use a regional token or a global token to list the image tags in an Amazon ECR repository.
+
+Regional token
+    
+
+Retrieve a regional token with the AWS CLI and set it to an environment variable. The returned value is already encoded for an HTTP Basic authorization header.
+    
+    
+    TOKEN=$(aws ecr get-authorization-token \
+         --output text \
+         --query 'authorizationData[].authorizationToken')
+
+Pass the `$TOKEN` variable in the HTTP Basic authorization header.
+    
@@ -52 +113,3 @@ Amazon ECR supports the [Docker Registry HTTP API](https://docs.docker.com/regis
-###### To authenticate with the Amazon ECR HTTP API
+    curl -i \
+         -H "Authorization: Basic $TOKEN" \
+         https://aws_account_id.dkr.ecr.region.amazonaws.com/v2/amazonlinux/tags/list
@@ -54 +117 @@ Amazon ECR supports the [Docker Registry HTTP API](https://docs.docker.com/regis
-  1. Retrieve an authorization token with the AWS CLI and set it to an environment variable.
+Global token
@@ -56 +118,0 @@ Amazon ECR supports the [Docker Registry HTTP API](https://docs.docker.com/regis
-        TOKEN=$(aws ecr get-authorization-token --output text --query 'authorizationData[].authorizationToken')
@@ -58 +120 @@ Amazon ECR supports the [Docker Registry HTTP API](https://docs.docker.com/regis
-  2. To authenticate to the API, pass the `$TOKEN` variable to the ` -H` option of **curl**. For example, the following command lists the image tags in an Amazon ECR repository. For more information, see the [Docker Registry HTTP API](https://docs.docker.com/registry/spec/api/) reference documentation.
+Retrieve a global token with the AWS CLI. Create the HTTP Basic authorization value by base64-encoding the username `AWS`, a colon, and the global token.
@@ -60 +122,14 @@ Amazon ECR supports the [Docker Registry HTTP API](https://docs.docker.com/regis
-        curl -i -H "Authorization: Basic $TOKEN" https://aws_account_id.dkr.ecr.region.amazonaws.com/v2/amazonlinux/tags/list
+    
+    GLOBAL_TOKEN=$(aws signin create-bearer-token \
+         --grant-type client_credentials \
+         --resource ecr.amazonaws.com \
+         --query accessToken \
+         --output text)
+    TOKEN=$(printf 'AWS:%s' "$GLOBAL_TOKEN" | base64 | tr -d '\n')
+
+Pass the `$TOKEN` variable in the HTTP Basic authorization header.
+    
+    
+    curl -i \
+         -H "Authorization: Basic $TOKEN" \
+         https://aws_account_id.dkr.ecr.region.amazonaws.com/v2/amazonlinux/tags/list
@@ -72,0 +149,3 @@ The output is as follows:
+## Using the Amazon ECR credential helper
+
+Amazon ECR provides a Docker credential helper which makes it easier to store and use Docker credentials when pushing and pulling images to Amazon ECR. The Amazon ECR Docker credential helper can retrieve both regional tokens and global tokens. For installation and configuration steps, see [Amazon ECR Docker Credential Helper on GitHub](https://github.com/awslabs/amazon-ecr-credential-helper).
@@ -73,0 +153 @@ The output is as follows:
+Note
@@ -74,0 +155 @@ The output is as follows:
+The Amazon ECR Docker credential helper doesn't support multi-factor authentication (MFA) currently.