Private registry authentication in Amazon ECR
You can use the AWS Management Console, the AWS CLI, or the AWS SDKs to create and manage private repositories. You can also use those methods to perform some actions on images, such as listing or deleting them. These clients use standard AWS authentication methods. Even though you can use the Amazon ECR API to push and pull images, you're more likely to use the Docker CLI or a language-specific Docker library.
The Docker CLI doesn't support native IAM authentication methods. Additional steps must be taken so that Amazon ECR can authenticate and authorize Docker push and pull requests.
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.
| Token type | Token request | AWS Region scope | Validity |
|---|---|---|---|
| Global token | AWS Sign-In CreateBearerToken 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 or aws ecr
get-login-password |
Valid in the same AWS Region that issued the token | 12 hours |
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
signInSessionArnfield in theuserIdentity.sessionContextelement of CloudTrail events to correlate token usage with the AWS session that requested the token. For more information, see CloudTrail userIdentity element. -
Use the IntrospectOAuth2TokenWithIAM API operation to check a token's active state and metadata.
To authenticate Docker to an Amazon ECR private registry with a global token
-
Use the create-bearer-token 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 \ --regiontoken_region\ --query accessToken \ --output text) -
Pass the global token to
docker login, and specifyAWSas the username.printf '%s' "$TOKEN" | docker login \ --username AWS \ --password-stdin \aws_account_id.dkr.ecr.registry_region.amazonaws.com
Using a regional token
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
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.
To authenticate Docker to an Amazon ECR private registry with a regional token
-
Configure the AWS CLI to interact with AWS. For more information, see AWS CLI configuration basics in the AWS Command Line Interface User Guide.
-
Use one of the following commands to authenticate to an Amazon ECR private registry. For docker login, use
AWSas the username and specify the Amazon ECR registry URI. Repeat the command for each registry that you want to authenticate to.-
get-login-password (AWS CLI)
aws ecr get-login-password --regionregion| docker login --username AWS --password-stdin.dkr.ecr.aws_account_idregion.amazonaws.com -
Get-ECRLoginCommand (AWS Tools for Windows PowerShell)
(Get-ECRLoginCommand).Password | docker login --username AWS --password-stdin.dkr.ecr.aws_account_idregion.amazonaws.com
-
Using HTTP API authentication
Amazon ECR supports the Docker
Registry HTTP API
The output is as follows:
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Date: Thu, 04 Jan 2018 16:06:59 GMT
Docker-Distribution-Api-Version: registry/2.0
Content-Length: 50
Connection: keep-alive
{"name":"amazonlinux","tags":["2017.09","latest"]}
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
The Amazon ECR Docker credential helper doesn't support multi-factor authentication (MFA) currently.