Skip to main content

atmos azure acr login

Login to Azure Container Registry (ACR) using a named integration, an identity's linked integrations, or explicit registry login server URLs. This command writes Docker credentials to the standard Docker config location.

atmos azure acr login --help

Usage​

atmos azure acr login [integration] [flags]

Examples​

# Login using a named integration
atmos azure acr login dev/acr

# Login using an identity's linked integrations
atmos azure acr login --identity azure-dev

# Pick an identity interactively (requires a TTY)
atmos azure acr login --identity

# Login with explicit registry login server (uses ambient Azure credentials)
atmos azure acr login --registry myregistry.azurecr.io

# Login to multiple explicit registries
atmos azure acr login \
  --registry myregistry.azurecr.io \
  --registry otherregistry.azurecr.io

Arguments​

integration

Name of the integration to use for ACR login. The integration must be configured in auth.integrations with kind: azure/acr. When provided, Atmos authenticates the integration's linked identity and logs into the configured registry.

Flags​

--identity (alias -i)

Identity name whose linked integrations should be executed. All azure/acr integrations that reference this identity will be triggered. This authenticates the identity first, then executes all its linked integrations.

Passing --identity without a value opens an interactive picker to choose an identity (the same selector used by atmos auth login). This requires an interactive terminal (TTY); in CI or other non-interactive contexts it errors instead of prompting, so pass an explicit name there (--identity <name>).

--registry (alias -r)

Explicit ACR registry login server URL(s) for ad-hoc login. This mode uses ambient Azure credentials (the Azure SDK default credential chain: environment variables, managed identity, workload identity, Azure CLI) — not Atmos identities. Can be specified multiple times for multiple registries.

Format: {name}.azurecr.io

Configuration​

ACR integrations are configured in atmos.yaml under auth.integrations:

auth:
  providers:
    azure-device-code:
      kind: azure/device-code
      spec:
        tenant_id: 00000000-0000-0000-0000-000000000000

  identities:
    azure-dev:
      kind: azure/subscription
      via:
        provider: azure-device-code
      principal:
        subscription_id: 11111111-1111-1111-1111-111111111111

  # Integrations derive credentials from identities
  integrations:
    dev/acr:
      kind: azure/acr
      via:
        identity: azure-dev           # Which identity provides Azure credentials
      spec:
        auto_provision: true          # Auto-trigger on identity login (default: true)
        registry:
          name: myregistry

Integration Configuration Options​

FieldRequiredDefaultDescription
kindYes-Must be azure/acr
via.identityYes-Name of identity providing Azure credentials
spec.auto_provisionNotrueAuto-trigger on identity login
spec.registry.nameYes-ACR registry name (login server = {name}.azurecr.io)
spec.registry.tenant_idNoidentity's tenantOverride the AAD tenant used for the OAuth2 token exchange

How It Works​

Named Integration Mode​

When you specify an integration name:

  1. Atmos looks up the integration config from auth.integrations.
  2. Authenticates the linked identity (via via.identity).
  3. Exchanges the identity's AAD access token for an ACR refresh token via the registry's /oauth2/exchange endpoint (the same mechanism az acr login uses).
  4. Writes credentials to Docker config (~/.docker/config.json).

Identity Mode​

When you use --identity:

  1. Atmos finds all integrations that reference the specified identity.
  2. Authenticates the identity.
  3. Executes each linked integration.
  4. Each integration writes its credentials to Docker config.

Explicit Registry Mode​

When you use --registry:

  1. Atmos uses ambient Azure credentials (the Azure SDK default credential chain).
  2. Exchanges the token for each registry's login server.
  3. Writes credentials to Docker config (~/.docker/config.json).

Credential Storage​

ACR credentials are written to ~/.docker/config.json by default, the standard Docker config location. This means:

  • Docker commands work immediately after login without additional configuration
  • Credentials are merged with existing entries in your Docker config
  • Respects DOCKER_CONFIG environment variable if set

Auto-Provisioning​

When auto_provision is true (the default), ACR integrations are automatically triggered when you authenticate with their linked identity:

$ atmos auth login azure-dev
Authenticating with identity: azure-dev
Opening browser for device code authentication...
Successfully authenticated as azure-dev
✓ ACR login: myregistry.azurecr.io (expires in 2h59m)

To disable auto-provisioning for an integration, set auto_provision: false:

integrations:
  dev/acr:
    kind: azure/acr
    via:
      identity: azure-dev
    spec:
      auto_provision: false  # Only triggered via explicit `atmos azure acr login` command
      registry:
        name: myregistry

Notes​

  • ACR refresh tokens are typically long-lived; the actual expiration time (decoded from the token) is displayed when login succeeds.
  • No explicit IAM/RBAC permission is required beyond AcrPull/AcrPush on the target registry (or a role granting those actions) for the identity's principal.

See Also​