AWS Compute Blog

Using Federation with Amazon ECR

This is a guest post from my colleague Asif Khan.


Federation is a mechanism to connect identity management systems together. A user’s credentials are always stored with the “home” organization (the identity provider). A service provider trusts the identity provider to validate credentials when the user logs into a service. The user never provides credentials directly to anybody but the identity provider.

Many of our customers use federation to manage secure access to systems and user stores and have expressed a requirement to use federation with Amazon ECR, and this post explains how to do that.

Overview of Amazon ECR

With Amazon EC2 Container Registry (Amazon ECR), customers can store their Docker images in highly available repositories managed by AWS. ECR encrypts images at rest using server-side encryption managed by Amazon S3, and also provides integration with AWS Identity and Access Management (IAM) to control who can access a given repository.

Amazon ECR makes it easy to set up repository policies that grant push/pull access to IAM users, roles, or other AWS accounts. In order to push and pull images to an ECR repository using the standard Docker commands, customers must first authenticate with ECR by obtaining an encrypted token to pass in the docker login command. The token is generated for the AWS identity (IAM user, group, role, etc.) that originally requested the token.

However, many customers might already have an identity store outside AWS that they would like to use to authenticate with ECR. With IAM identity federation support, customers can benefit from the standardization on a protocol such as SAML, security control, and an improved user experience. Developers can use their corporate SAML identity provider to log in and use ECR seamlessly. IAM provides an integration with a variety of SAML providers such as Auth0, Bitium and Okta Ping Identity, among others. For a full list, see Integrating Third-Party SAML Solution Providers with AWS.

Customers can also choose to implement federation and control access issuing tokens themselves which can be used with the docker login command.

With IAM federation, we can set up federation to other identity providers listed. After federation is set up, developers or hosts can use AssumeRole, be granted tokens from the customer identity provider (IDP), and switch to a role which has permission to access the ECR repository.


This post walks you through the process of using federation along with ECR. This walkthrough uses the SAML identity provider Auth0, but you can follow along with any other AWS-supported provider. The steps are:

  1. Set up federation between an identity provider and IAM.
  2. Set up a role and configure it for federation.
  3. Set up user permissions to assume the role.
  4. Set up ECR permissions to allow access to the repository.
  5. Use the temporary AWS credentials returned by assumeRole when calling aws ecr get-login to obtain the docker auth token.
  6. Push and pull from an ECR repository using the Docker commands.

Set up federation
Follow the steps in the following topic to set up federation against an identity provider of your choice: Integrating Third-Party SAML Solution Providers with AWS. This walkthrough uses Auth0 as an example. Next, register an app on Auth0 or your IDP.
In the IAM console, set up the identity provider on AWS.
SAML Provider

Set up a role
Next, create a role with read-only access to assume. Note the role name for later.
IAM Role

Set up your user permissions to assume the new role
To switch to a role using the AWS CLI, follow the steps in Switching to an IAM Role (AWS Command Line Interface) and grant permissions to switch roles to the role that you created in the previous step.

Set up permissions for the ECR repository
With ECR, you can use the permissions tool to restrict access to selected principals. Choose the previously-created role “TestSAML” as the principal in the permissions.

ECR Permissions
ECR Actions

Use temporary AWS credentials
Use the temporary AWS credentials when calling aws ecr get-login to obtain the docker auth token. After you have assumed the role, you can enter the following command:

$ aws ecr get-login --profile testSAML

The results should be as follows:

docker login -u AWS -p  -e none

Log in to Docker and push/pull
Using the encrypted credentials returned from the previous command, you can now log in to Docker:

$ docker login -u AWS -p  -e none

You can now push or pull to and from Amazon ECR using the following commands:

$ docker push
$ docker pull

When you run microservices on Amazon ECS, you can pull images from Amazon ECR securely using federation and your identity provider. Federation includes benefits such as standardization on SAML, enhanced security, and an improved user experience. Use this walkthrough with any other identity provider, and achieve the same results.

If you have questions or suggestions, please comment below.