Skip to main content

Configure Authentication

The auth section configures how Atmos obtains and manages credentials for cloud providers and external services. Auth configuration is primarily defined in atmos.yaml but can be extended at the component level via auth as a top-level key.

Use Cases​

  • AWS SSO Integration: Authenticate via AWS IAM Identity Center (SSO) for seamless credential management.
  • Role Assumption Chains: Configure multi-account access through role assumption.
  • Credential Storage: Securely store and retrieve credentials using system keyrings.
  • Environment Injection: Automatically inject credentials as environment variables for components.

Configuration Locations​

Global Configuration (atmos.yaml)​

The primary auth configuration is defined in your atmos.yaml:

# atmos.yaml
auth:
  providers:
    aws-sso:
      kind: aws-sso
      start_url: https://acme.awsapps.com/start
      region: us-east-1

  identities:
    prod-admin:
      kind: aws
      via:
        provider: aws-sso
      principal:
        name: AdministratorAccess
        account:
          id: "123456789012"

Component-Level Configuration​

Components can reference or extend auth configuration via the auth top-level key:

components:
  terraform:
    vpc:
      auth:
        identity: prod-admin

Auth Configuration Structure​

Providers​

Providers define how Atmos connects to authentication sources:

auth:
  providers:
    my-sso:
      kind: aws-sso
      start_url: https://company.awsapps.com/start
      region: us-east-1
      default: true
      session:
        duration: 8h
      console:
        session_duration: 12h

Provider Fields:

kind
Provider type (aws-sso, static).
start_url
AWS SSO portal URL.
region
AWS region for SSO.
default
Mark as default provider.
session.duration
CLI session duration.
console.session_duration
AWS Console session duration.

Identities​

Identities represent specific credentials or roles:

auth:
  identities:
    dev-developer:
      kind: aws
      via:
        provider: aws-sso
      principal:
        name: DeveloperAccess
        account:
          name: acme-dev
          id: "111111111111"
      env:
        - key: AWS_PROFILE
          value: dev-developer

    prod-admin:
      kind: aws
      via:
        provider: aws-sso
      principal:
        name: AdministratorAccess
        account:
          id: "222222222222"
      default: true

Identity Fields:

kind
Identity type (aws).
via.provider
Provider to use for authentication.
via.identity
Chain through another identity.
principal.name
Permission set or role name.
principal.account.id
Target AWS account ID.
principal.account.name
Target AWS account name.
credentials
Static credentials (use sparingly).
env
Environment variables to set.
default
Mark as default identity.
alias
Alternative name for the identity.
session.duration
Session duration override.

Keyring Configuration​

Configure how credentials are stored:

auth:
  keyring:
    type: system  # system, file, or memory
    spec:
      # Type-specific configuration

Keyring Types:

system
Use OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service).
file
Store in encrypted file.
memory
Store in memory only (not persisted).

Examples​

AWS SSO with Multiple Accounts​

atmos.yaml

auth:
  providers:
    acme-sso:
      kind: aws-sso
      start_url: https://acme.awsapps.com/start
      region: us-east-1
      default: true

  identities:
    dev-admin:
      kind: aws
      via:
        provider: acme-sso
      principal:
        name: AdministratorAccess
        account:
          name: acme-dev
          id: "111111111111"

    staging-admin:
      kind: aws
      via:
        provider: acme-sso
      principal:
        name: AdministratorAccess
        account:
          name: acme-staging
          id: "222222222222"

    prod-admin:
      kind: aws
      via:
        provider: acme-sso
      principal:
        name: AdministratorAccess
        account:
          name: acme-prod
          id: "333333333333"
      default: true

Role Assumption Chain​

Configure a chain where you first authenticate via SSO, then assume a role in another account:

atmos.yaml

auth:
  providers:
    acme-sso:
      kind: aws-sso
      start_url: https://acme.awsapps.com/start
      region: us-east-1

  identities:
    # First, authenticate to management account via SSO
    mgmt-access:
      kind: aws
      via:
        provider: acme-sso
      principal:
        name: ManagementAccess
        account:
          id: "000000000000"

    # Then, assume role in target account from management
    prod-deployer:
      kind: aws
      via:
        identity: mgmt-access  # Chain through mgmt-access
      principal:
        name: arn:aws:iam::333333333333:role/TerraformDeployer

Component-Level Identity Selection​

stacks/orgs/acme/plat/prod/us-east-1.yaml

components:
  terraform:
    # This component needs admin access
    iam-roles:
      auth:
        identity: prod-admin
      vars:
        # ...

    # This component uses read-only access
    monitoring:
      auth:
        identity: prod-readonly
      vars:
        # ...

Environment Variable Injection​

atmos.yaml

auth:
  identities:
    prod-admin:
      kind: aws
      via:
        provider: acme-sso
      principal:
        name: AdministratorAccess
        account:
          id: "333333333333"
      env:
        - key: AWS_PROFILE
          value: prod-admin
        - key: AWS_DEFAULT_REGION
          value: us-east-1

When using this identity, the specified environment variables are automatically set.

Credential Realm Isolation​

By default, Atmos stores credentials in a shared location that all Atmos projects on the same machine can access. If you work with multiple repositories that define identities with the same name but for different AWS accounts, you can use realms to isolate credentials between projects.

Configuration​

Set a realm in your atmos.yaml:

atmos.yaml

auth:
  realm: my-project

Or use the ATMOS_AUTH_REALM environment variable:

export ATMOS_AUTH_REALM=my-project

Precedence​

Realm is resolved in this order (highest to lowest priority):

  1. ATMOS_AUTH_REALM environment variable
  2. auth.realm in atmos.yaml configuration
  3. Empty (no realm isolation)

Credential Storage Paths​

Without a realm, credentials are stored at:

~/.config/atmos/aws/{provider}/credentials

With a realm configured, credentials are stored at:

~/.config/atmos/{realm}/aws/{provider}/credentials

Realm Naming Rules​

Realm values must follow these rules:

  • Only lowercase letters (a-z), digits (0-9), hyphens (-), and underscores (_)
  • Maximum 64 characters
  • Cannot start or end with a hyphen or underscore
  • Cannot contain consecutive hyphens or underscores
  • Cannot contain path traversal characters (/, \, ..)
caution

Changing the realm (adding, removing, or modifying auth.realm or ATMOS_AUTH_REALM) makes previously cached credentials inaccessible. You must run atmos auth login to re-authenticate under the new realm. Atmos will warn you if it detects credentials stored under a different realm.

Checking Your Current Realm​

Use atmos auth whoami to see the current realm and credential status:

atmos auth whoami --identity my-identity

CLI Commands​

Atmos provides commands for managing authentication:

# Login to default provider
atmos auth login

# Login to specific provider
atmos auth login --provider aws-sso

# Configure user credentials
atmos auth user configure

# List available identities
atmos auth list

# Switch identity
atmos auth switch prod-admin

Best Practices​

  1. Use SSO Over Static Credentials: AWS SSO provides short-lived credentials and centralized access management.

  2. Define Environment-Specific Identities: Create separate identities for dev, staging, and production with appropriate permissions.

  3. Use Role Chains for Cross-Account: Rather than configuring SSO access to every account, use role assumption chains from a central account.

  4. Leverage System Keyring: Use the system keyring for credential storage to benefit from OS-level security.

  5. Set Appropriate Session Durations: Balance security and convenience when configuring session durations.

  6. Mark Default Identities: Set default: true on commonly used identities to streamline workflows.