Skip to main content

ECR Authentication Integration: Automatic Docker Login for AWS Container Registries

· 4 min read
Ben Smith
Ben Smith
Software Engineer

We're introducing ECR authentication integration - automatic Docker login for AWS Elastic Container Registry as part of your Atmos authentication workflow. Configure once, authenticate everywhere.

The Problem​

Teams working with AWS ECR face repetitive authentication friction:

# The manual dance everyone knows too well
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com

This breaks down when you have:

  • Multiple AWS accounts with different ECR registries
  • Different identities for different environments
  • Team members who forget the exact incantation
  • CI/CD pipelines that need consistent authentication

The Solution: Integrations​

We've introduced a new auth.integrations section that handles client-only credential materializations - services like ECR and EKS that derive credentials from your AWS identity rather than being identities themselves.

Configuration​

auth:
  providers:
    company-sso:
      kind: aws/iam-identity-center
      region: us-east-1
      start_url: https://company.awsapps.com/start/

  identities:
    dev-admin:
      kind: aws/permission-set
      via:
        provider: company-sso
      principal:
        name: AdministratorAccess
        account: dev

  # Integrations specify which identity they use via "via.identity"
  # auto_provision defaults to true, so integrations auto-trigger on identity login
  integrations:
    dev/ecr/primary:
      kind: aws/ecr
      via:
        identity: dev-admin
      spec:
        registry:
          account_id: "123456789012"
          region: us-east-2

    dev/ecr/secondary:
      kind: aws/ecr
      via:
        identity: dev-admin
      spec:
        registry:
          account_id: "123456789012"
          region: us-west-2

Automatic Login​

When you authenticate with an identity, all integrations that reference that identity are triggered automatically (auto_provision defaults to true):

$ atmos auth login dev-admin
Authenticating with identity: dev-admin
Opening browser for SSO authentication...
Successfully authenticated as dev-admin
✓ ECR login: 123456789012.dkr.ecr.us-east-2.amazonaws.com (expires in 11h59m)
✓ ECR login: 123456789012.dkr.ecr.us-west-2.amazonaws.com (expires in 11h59m)

Standalone ECR Login​

You can also trigger ECR login independently:

# Using a named integration
atmos auth ecr-login dev/ecr/primary

# Using an identity's linked integrations (all integrations referencing that identity)
atmos auth ecr-login --identity dev-admin

# Explicit registries (ad-hoc)
atmos auth ecr-login --registry 123456789012.dkr.ecr.us-east-1.amazonaws.com

Design Decisions​

Why Integrations, Not Identities?​

ECR login and EKS kubeconfig aren't really "identities" - they're derived credentials:

ConceptIAM UserDocker Login (ECR)EKS kubeconfig
Stored identity objectYesNoNo
Policy attachmentYesNoNo
Server-side lifecycleYesNoNo
Client-only materializationNoYesYes

Integrations are things that use an identity to materialize client-side credentials.

Zero Configuration​

ECR credentials are written to the standard Docker config location (~/.docker/config.json or $DOCKER_CONFIG/config.json if set). This means Docker commands work immediately after login—no additional environment variables or configuration required.

The token expiration time is displayed so you know when to re-authenticate.

Non-Blocking Errors​

Integration failures during atmos auth login are logged but don't block authentication. Your identity credentials succeed even if ECR login fails - you can retry the integration separately.

Use Cases​

Multi-Account Container Workflows​

auth:
  identities:
    prod-deployer:
      kind: aws/permission-set
      via:
        provider: company-sso
      principal:
        name: ContainerDeploy
        account: production

  # auto_provision defaults to true - integrations trigger on identity login
  integrations:
    prod/ecr:
      kind: aws/ecr
      via:
        identity: prod-deployer
      spec:
        registry:
          account_id: "111111111111"
          region: us-east-1

    shared/ecr:
      kind: aws/ecr
      via:
        identity: prod-deployer
      spec:
        registry:
          account_id: "999999999999"
          region: us-east-1

CI/CD Pipelines​

# Single command authenticates identity AND logs into ECR
atmos auth login prod-deployer

# Now docker pull/push works
docker pull 111111111111.dkr.ecr.us-east-1.amazonaws.com/my-app:latest

Implementation Details​

AWS SDK v2 Compatibility​

The implementation uses AWS SDK for Go v2 and follows AWS best practices:

  • Universal Token: ECR authorization tokens work for any registry your credentials can access. The deprecated RegistryIds parameter is no longer used.
  • 12-Hour Expiry: Tokens expire after 12 hours (AWS-enforced). The expiration time is displayed so you know when to re-authenticate.

Cross-Platform Support​

  • Uses homedir.Dir() for reliable home directory resolution across platforms.
  • Environment variables read through Viper for consistent configuration handling.
  • File locking via gofrs/flock prevents concurrent modification of Docker config.

Error Handling​

All errors use sentinel errors for consistent error checking:

errors.Is(err, errUtils.ErrECRAuthFailed)
errors.Is(err, errUtils.ErrIntegrationNotFound)

What's Next​

The integration pattern extends naturally to other client-only credential materializations:

  • EKS: aws eks update-kubeconfig integration
  • CodeArtifact: npm/pip repository authentication
  • Other registries: GCR, ACR support

Documentation​

Get Involved​

Have feedback on the integration pattern? Want to contribute EKS support?