Skip to main content

Identities

Identities represent the user accounts or roles available from provider credentials. Configure identities in the auth.identities section of your atmos.yaml.

Permission Set​

For AWS SSO permission sets.

atmos.yaml
auth:
  identities:
    dev-admin:
      kind: aws/permission-set
      default: true
      via:
        provider: company-sso
      principal:
        name: AdminAccess
        account:
          name: development        # Account name (resolved via SSO)
          # OR use account ID directly:
          # id: "123456789012"
kind
Required. Must be aws/permission-set.
default
Optional. If true, this identity is used when no identity is specified.
via.provider
Required. Name of the provider to use for authentication.
principal.name
Required. Name of the permission set.
principal.account.name
Account name/alias (resolved via SSO ListAccounts API).
principal.account.id
Numeric account ID (used directly, no lookup required).

Assume Role​

For assuming IAM roles, either directly from a provider or chained from another identity.

atmos.yaml
auth:
  identities:
    prod-admin:
      kind: aws/assume-role
      via:
        identity: base-admin       # Chain through another identity
        # OR directly from provider:
        # provider: okta-saml
      principal:
        assume_role: arn:aws:iam::999999999999:role/ProductionAdmin
        session_name: atmos-prod   # Optional
kind
Required. Must be aws/assume-role.
via.identity
Name of another identity to chain from (mutually exclusive with via.provider).
via.provider
Name of a provider to use directly (mutually exclusive with via.identity).
principal.assume_role
Required. ARN of the IAM role to assume.
principal.session_name
Optional. Session name for CloudTrail auditing.

Assume Root (Organizations)​

For centralized root access in AWS Organizations using sts:AssumeRoot. This allows privileged operations on member accounts without enabling root user credentials.

atmos.yaml
auth:
  identities:
    root-audit:
      kind: aws/assume-root
      via:
        identity: admin-base        # Chain through an existing identity
      principal:
        target_principal: "123456789012"           # 12-digit member account ID
        task_policy_arn: arn:aws:iam::aws:policy/root-task/IAMAuditRootUserCredentials
        duration: 15m                              # Optional (max 15m for AssumeRoot)
kind
Required. Must be aws/assume-root.
via.identity
Required. Name of another identity to chain from (must provide AWS credentials).
principal.target_principal
Required. 12-digit AWS account ID of the member account to assume root on.
principal.task_policy_arn
Required. AWS-managed root task policy ARN. See supported policies below.
principal.duration
Optional. Session duration (max 15 minutes for AssumeRoot).

Supported task policies:

  • arn:aws:iam::aws:policy/root-task/IAMAuditRootUserCredentials
  • arn:aws:iam::aws:policy/root-task/IAMCreateRootUserPassword
  • arn:aws:iam::aws:policy/root-task/IAMDeleteRootUserCredentials
  • arn:aws:iam::aws:policy/root-task/S3UnlockBucketPolicy
  • arn:aws:iam::aws:policy/root-task/SQSUnlockQueuePolicy
note

AssumeRoot requires AWS Organizations with centralized root access enabled and appropriate permissions on the base identity.

User (Break-glass)​

For static IAM user credentials, typically used for emergency access.

atmos.yaml
auth:
  identities:
    emergency-user:
      kind: aws/user
      credentials:
        access_key_id: !env EMERGENCY_AWS_ACCESS_KEY_ID
        secret_access_key: !env EMERGENCY_AWS_SECRET_ACCESS_KEY
        region: us-east-1
        mfa_arn: arn:aws:iam::123456789012:mfa/username  # Optional
      spec:
        endpoint_url: "http://localhost:4566"             # Optional for Floci/LocalStack-compatible endpoints
kind
Required. Must be aws/user.
credentials.access_key_id
AWS access key ID. Use !env to reference environment variables.
credentials.secret_access_key
AWS secret access key. Use !env to reference environment variables.
credentials.region
AWS region for API calls.
credentials.mfa_arn
Optional. MFA device ARN. When set, Atmos prompts for TOTP code during authentication.
credentials.webflow_enabled
Optional. Defaults to true. Set to false to disable browser-based authentication fallback.
spec.endpoint_url
Optional. AWS-compatible base endpoint URL for SDK calls, useful for Floci, LocalStack, and other test endpoints.
tip

Instead of storing credentials in configuration, use atmos auth user configure to store them securely in the system keyring.

Browser-Based Authentication (Automatic Fallback)​

When neither configuration nor keyring entries provide credentials, Atmos automatically initiates an OAuth2 PKCE flow via the AWS sign-in service. This provides the same convenient web-based authentication that SSO users already enjoy, without requiring static access keys.

Authentication priority:

  1. Static credentials from atmos.yaml (access_key_id + secret_access_key, including !env references)
  2. Credentials stored in the system keyring (via atmos auth user configure)
  3. Browser-based OAuth2 PKCE flow (when webflow_enabled is true, which is the default)

To explicitly use the browser flow without removing or changing configured IAM access keys, add --webflow to an aws/user login. This skips cached temporary sessions and configured credentials only for that invocation, then writes the newly issued temporary credentials to the usual session cache:

atmos auth login --profile=legacy --identity=cp-root/admin --webflow

Atmos does not consult ambient AWS credentials (environment variables, ~/.aws/credentials, instance profiles) for aws/user identities — credentials must be supplied through one of the three sources above.

If the keyring is reachable but the stored entry is unreadable (corrupted, missing fields, permission denied), Atmos reports the keyring read failure directly instead of silently falling back to the browser flow. This makes it possible to diagnose keyring issues rather than guessing why the browser flow opened.

How it works:

  1. Atmos starts a local callback server on an ephemeral port
  2. Opens your default browser to the AWS sign-in authorization endpoint
  3. Exchanges the authorization code for temporary credentials using PKCE
  4. Caches a refresh token for 12-hour session reuse

Subsequent authentications within the 12-hour window reuse the cached refresh token, avoiding repeated browser prompts. Credentials refresh automatically every 15 minutes.

In non-interactive environments (CI/CD), Atmos displays a URL that can be opened manually.

Disabling browser authentication:

atmos.yaml
auth:
  identities:
    my-user:
      kind: aws/user
      credentials:
        webflow_enabled: false  # Disable browser-based auth fallback

Credential Process​

For credentials that come from an external helper such as okta-aws-cli, aws-sso-cli, aws-vault, Granted, or a corporate SAML tool. Atmos runs the helper, which follows the AWS credential_process protocol, and uses the credentials it prints.

atmos.yaml
auth:
  identities:
    corp-base:
      kind: aws/credential-process
      credentials:
        credential_process: corp-credential-helper --account=prod
        region: us-east-1                        # Optional
      spec:
        endpoint_url: "http://localhost:4566"    # Optional for Floci/LocalStack-compatible endpoints
kind
Required. Must be aws/credential-process.
credentials.credential_process
Required. The command to run. Atmos executes it through the platform shell, like the AWS SDK for Go does: sh -c on Linux and macOS, and %COMSPEC% /S /C "<command>" on Windows (the command line is passed verbatim, so quoted paths survive). A command copied from ~/.aws/config therefore runs as written, and shell features such as pipes and environment variable expansion work. The AWS CLI itself does not use a shell: it splits the command into arguments. Keep the command free of shell-only syntax if you want the same line to also work in an AWS CLI profile. The helper's stdin and stderr are passed through to your terminal, so it can prompt for MFA or print browser-login instructions when you run Atmos interactively.
credentials.region
Optional. Default AWS region written to the Atmos-managed AWS config.
spec.endpoint_url
Optional. AWS-compatible base endpoint URL for SDK calls, useful for Floci, LocalStack, and other test endpoints.

This identity is standalone: it has no via, because its credentials come from the helper. Atmos rejects via, session, principal, access_key_id, secret_access_key, and mfa_arn on this kind, before running any helper in the chain. The helper owns the session, so a session.duration would have no effect. Use aws/user for IAM user access keys.

Behavior:

  • Credentials are used as returned. Atmos makes no STS call and never prompts for MFA. The helper is responsible for any MFA prompt.
  • Caching. Atmos writes the credentials to its managed AWS files together with their expiration, and reuses them instead of running the helper again while they have at least 15 minutes of lifetime left. Credentials with less time left than that are refreshed before they expire, so a helper that returns credentials valid for 15 minutes or less runs on every invocation. atmos aws credential-process raises that threshold with --min-validity.
  • No expiration. If the helper returns credentials without an Expiration, Atmos runs the helper on every invocation because it cannot know how long they stay valid.
  • No keyring storage. Helper output is never stored in the system keyring, on any command. The helper stays the source of truth, and atmos auth logout removes any stale entry an older version left behind, without --keychain.
  • Timeout. The helper must finish within one minute, and this limit is not configurable. Atmos then stops it and returns within a few seconds, even when the helper started child processes that keep running. A helper that waits for an MFA code or a browser login can therefore time out. Complete that login in the helper first, or run atmos auth login --identity=<name> in a terminal so the credentials are cached before a non-interactive caller needs them.
  • No prompts under a captured terminal. Atmos only prompts (identity selection, MFA, credentials) when both stdin and stderr are terminals. When a parent process such as the AWS CLI captures stderr, Atmos fails with an explanation and a hint instead of hanging. Log in first with atmos auth login.
  • Web console. atmos auth console works with these identities only when the helper returns temporary credentials that include a SessionToken. Long-lived access keys fail with a session token error, because the AWS federation endpoint requires a session.
  • Safe errors. If the helper fails or prints invalid output, Atmos reports which fields are missing or invalid without echoing any credential values.

Chaining from a Credential Process​

Credentials from a helper often represent a base session. Chain aws/assume-role identities from it to reach other accounts:

atmos.yaml
auth:
  identities:
    corp-base:
      kind: aws/credential-process
      credentials:
        credential_process: corp-credential-helper --account=prod

    prod-admin:
      kind: aws/assume-role
      via:
        identity: corp-base
      principal:
        assume_role: arn:aws:iam::111111111111:role/Admin

Each time prod-admin needs fresh credentials, Atmos asks corp-base for its credentials first. corp-base reuses its cached credentials while they have at least 15 minutes left, or runs the helper again when they are closer to expiring or carry no Expiration.

Using Atmos Identities from the AWS CLI​

The opposite direction is also supported. Any Atmos identity can serve as an AWS CLI profile through the atmos aws credential-process command, which prints credentials in the same credential_process format. It never prompts, so log in first when the identity needs an interactive login.

Choosing Between User, Ambient, and Credential Process​

aws/user
You have an IAM user with long-lived access keys. Atmos calls STS GetSessionToken and handles MFA for that user.
aws/ambient
Credentials already exist in the environment, such as IRSA, an EC2 instance profile, an ECS task role, or an AWS_PROFILE. Atmos passes them through.
aws/credential-process
You already have a command that prints temporary credentials. Atmos runs that command and caches the result.

Ambient​

For credentials that the environment already provides, such as IRSA on EKS, an EC2 instance profile, an ECS task role, or a profile selected with AWS_PROFILE. The aws/ambient identity resolves credentials through the AWS SDK default credential provider chain and does not clear credential environment variables or disable IMDS.

atmos.yaml
auth:
  identities:
    eks-deployer:
      kind: aws/ambient
      principal:
        region: us-east-1    # Optional
kind
Required. Must be aws/ambient.
principal.region
Optional. AWS region used for SDK calls.

Because aws/ambient returns real AWS credentials, other identities can chain from it:

atmos.yaml
auth:
  identities:
    pod-base:
      kind: aws/ambient
      principal:
        region: us-east-1

    cross-account-deployer:
      kind: aws/assume-role
      via:
        identity: pod-base
      principal:
        assume_role: arn:aws:iam::999999999999:role/TerraformDeployRole

For a cloud-agnostic passthrough that leaves the whole environment untouched, use the ambient kind. See the ambient credentials example for more.

Atmos Pro​

The atmos/pro identity is a passthrough over the atmos/pro provider: it forwards the provider's Atmos Pro session so linked integrations (e.g. github/sts) can use it. It requires via.provider.

atmos.yaml
auth:
  identities:
    atmos-pro:
      kind: atmos/pro
      via:
        provider: atmos-pro
kind
Required. Must be atmos/pro.
via.provider
Required. Name of the atmos/pro provider this identity authenticates through.

You authenticate and run as this identity (atmos auth login --identity atmos-pro). The github/sts integration can reference it via via.identity, or bind to the provider directly via via.provider.

Identity Chaining​

Identity chaining allows you to create complex authentication flows where one identity is used to obtain another.

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

  identities:
    # Base identity from SSO
    base-admin:
      kind: aws/permission-set
      via:
        provider: company-sso
      principal:
        name: AdminAccess
        account:
          name: core-identity

    # Cross-account role using base permissions
    prod-admin:
      kind: aws/assume-role
      via:
        identity: base-admin       # Chain through base-admin
      principal:
        assume_role: arn:aws:iam::999999999999:role/ProductionAdmin

    # Further chain for specific access
    prod-readonly:
      kind: aws/assume-role
      via:
        identity: prod-admin       # Chain through prod-admin
      principal:
        assume_role: arn:aws:iam::999999999999:role/ReadOnlyAccess

Chain Rules:

  • Chains can be arbitrarily deep: provider → identity → identity → ... → identity
  • via.provider and via.identity are mutually exclusive
  • aws/user, aws/ambient, and aws/credential-process identities don't require a via field
  • Circular dependencies are detected and rejected

Session Configuration​

Configure session durations at the identity level to override provider defaults.

atmos.yaml
auth:
  identities:
    high-security:
      kind: aws/user
      session:
        duration: 1h              # Override for this identity
      credentials:
        region: us-east-1
        mfa_arn: arn:aws:iam::123456789012:mfa/emergency

IAM user limits: 15m-12h (no MFA) or 15m-36h (with MFA)

Component-Level Overrides​

Override authentication settings for specific components in your stack configuration.

stacks/catalog/myapp.yaml
components:
  terraform:
    myapp:
      auth:
        identities:
          custom-role:
            kind: aws/assume-role
            via:
              provider: company-sso
            principal:
              assume_role: arn:aws:iam::123456789012:role/MyAppRole

Component auth configuration is deep-merged with global auth. Component identities override global identities with the same name.

For components that need multiple identities authenticated simultaneously, see Required.

Default Identity​

Mark one identity as the default to use when no identity is explicitly specified:

atmos.yaml
auth:
  identities:
    dev-admin:
      kind: aws/permission-set
      default: true              # This identity is used by default
      via:
        provider: company-sso
      principal:
        name: AdminAccess
        account:
          name: development

    prod-admin:
      kind: aws/assume-role
      via:
        identity: dev-admin
      principal:
        assume_role: arn:aws:iam::999999999999:role/ProductionAdmin

Only one identity should be marked as default. If multiple identities have default: true, the behavior is undefined.

Using Profiles for Role-Based Access​

Use Atmos profiles to define different identity configurations for various team roles. Each profile is a directory containing YAML configuration files.

Profile structure:

profiles/
├── developer/
│   └── auth.yaml      # Developer identity config
├── platform/
│   └── auth.yaml      # Platform engineer identity config
└── ci/
    └── auth.yaml      # CI/CD identity config
profiles/developer/auth.yaml
# Profile for developers - limited to dev/staging
auth:
  identities:
    dev-access:
      kind: aws/permission-set
      default: true
      via:
        provider: company-sso
      principal:
        name: DeveloperAccess
        account:
          name: development
profiles/platform/auth.yaml
# Profile for DevOps/Platform engineers - cross-account access
auth:
  identities:
    platform-admin:
      kind: aws/permission-set
      default: true
      via:
        provider: company-sso
      principal:
        name: AdminAccess
        account:
          name: core-identity

    prod-deploy:
      kind: aws/assume-role
      via:
        identity: platform-admin
      principal:
        assume_role: arn:aws:iam::999999999999:role/ProductionDeploy
profiles/ci/auth.yaml
# Profile for CI/CD pipelines
auth:
  identities:
    github-deploy:
      kind: aws/assume-role
      default: true
      via:
        provider: github-oidc
      principal:
        assume_role: arn:aws:iam::123456789012:role/GitHubActionsRole

Activate a profile based on your role:

# Developers use the developer profile
atmos --profile developer terraform plan myapp -s dev

# Platform engineers use the platform profile
atmos --profile platform terraform apply myapp -s prod --identity prod-deploy

# CI/CD uses the ci profile
ATMOS_PROFILE=ci atmos terraform apply myapp -s prod

OCI registry user​

Use a standalone oci/user identity for registry username/password or personal access token authentication. It requires no provider:

auth:
  identities:
    registry-reader:
      kind: oci/user
      spec:
        registry: ghcr.io
        username: company-bot
        password_env: GHCR_TOKEN
spec.registry
Exact registry hostname, with a port if needed. Omit schemes and repository paths. Credentials are restricted to this host.
spec.username
Registry username or service account name.
spec.password_env
Optional name of an environment variable containing the password or token. If configured, it must be populated at login. Omit it to use a masked interactive prompt.
atmos auth login --identity registry-reader
atmos auth whoami --identity registry-reader
atmos auth logout --identity registry-reader --keychain --force

Credentials are stored in the configured realm-scoped keyring. The identity does not publish passwords into shell environment variables, Docker configuration, or whoami output. Reference it from plugins.registries.<name>.identity to enable authenticated plugin registry operations. For cloud-federated access, use an AWS or Azure identity with an ECR or ACR integration instead.

Related Commands​

See Also​

  • Providers — Configure the providers that identities use
  • Keyring — Configure credential storage for IAM users
  • Profiles — Environment-specific configuration overrides