Skip to main content

Authentication

The auth section of the atmos.yaml configures how Atmos authenticates with cloud providers. It supports AWS SSO, SAML, OIDC, GitHub Actions, GCP Workload Identity Federation, Azure, and static user credentials with a unified configuration model.

Quick Start​

atmos.yaml

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

  identities:
    admin:
      kind: aws/permission-set
      default: true
      via:
        provider: my-sso
      principal:
        name: AdminAccess
        account:
          name: production

Configuration Reference​

Top-Level Structure​

atmos.yaml

auth:
  logs:
    level: Info                    # Debug, Info, Warn, Error
    file: /path/to/auth.log        # Optional log file

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

  console:
    isolated_sessions: false       # Enable isolated browser sessions per identity

  providers:
    <provider-name>:               # Named provider configurations
      kind: <provider-kind>
      # Provider-specific fields...

  identities:
    <identity-name>:               # Named identity configurations
      kind: <identity-kind>
      # Identity-specific fields...

  integrations:
    <integration-name>:            # Named integration configurations
      kind: <integration-kind>     # aws/ecr, aws/eks
      via:
        identity: <identity-name>
      spec: {}                     # Kind-specific configuration

Subpages​

  • Providers - Configure authentication providers (AWS SSO, SAML, GitHub OIDC, GCP, Azure)
  • Identities - Configure identities and identity chaining
  • Keyring - Configure credential storage backends
  • Logs - Configure auth-specific logging

Integrations​

Integrations are client-only credential materializations that derive from identities. They are automatically triggered during atmos auth login when auto_provision is enabled (the default).

Supported integration kinds:

Disabling Authentication​

In CI/CD environments, you may want to disable Atmos-managed authentication and use native cloud provider credentials.

# Via CLI flag
atmos terraform plan mycomponent --stack=dev --identity=false

# Via environment variable
export ATMOS_IDENTITY=false
atmos terraform plan mycomponent --stack=dev

Recognized disable values: false, 0, no, off (case-insensitive)

When disabled:

  • Atmos skips all identity authentication
  • Falls back to standard cloud provider SDK credential resolution
  • Works even when atmos.yaml has identity configurations

Environment Variables​

ATMOS_IDENTITY
Default identity name, or false to disable.
ATMOS_KEYRING_TYPE
Keyring backend (system, file, memory).
ATMOS_KEYRING_PASSWORD
Password for file keyring.
ATMOS_XDG_CONFIG_HOME
Override config directory for AWS files.
ATMOS_XDG_DATA_HOME
Override data directory for file keyring.

Complete Example​

atmos.yaml

auth:
  logs:
    level: Info

  keyring:
    type: system

  console:
    isolated_sessions: true        # Open each identity in its own browser session

  providers:
    company-sso:
      kind: aws/iam-identity-center
      region: us-east-1
      start_url: https://company.awsapps.com/start
      session:
        duration: 4h
      console:
        session_duration: 12h

    github-oidc:
      kind: github/oidc
      region: us-east-1

  identities:
    # Development access via SSO
    dev-admin:
      kind: aws/permission-set
      default: true
      via:
        provider: company-sso
      principal:
        name: AdminAccess
        account:
          name: development

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

    # CI/CD access via GitHub OIDC
    github-deploy:
      kind: aws/assume-role
      via:
        provider: github-oidc
      principal:
        assume_role: arn:aws:iam::123456789012:role/GitHubActionsRole

    # Emergency break-glass access
    emergency:
      kind: aws/user
      credentials:
        region: us-east-1
        mfa_arn: arn:aws:iam::123456789012:mfa/emergency

  # Integrations derive credentials from identities
  integrations:
    # ECR login for container workflows
    dev/ecr:
      kind: aws/ecr
      via:
        identity: dev-admin
      spec:
        registry:
          account_id: "123456789012"
          region: us-east-2

    # EKS kubeconfig for kubectl access
    dev/eks:
      kind: aws/eks
      via:
        identity: dev-admin
      spec:
        cluster:
          name: dev-cluster
          region: us-east-2
          alias: dev-eks

Using Profiles​

Use Atmos profiles to define different authentication configurations for various use cases. Each profile is a directory containing YAML files.

Profile structure:

profiles/
├── developer/
│   └── auth.yaml      # Developer auth config
├── ci/
│   └── auth.yaml      # CI/CD auth config
└── platform/
    └── auth.yaml      # Platform engineer auth config

profiles/developer/auth.yaml

auth:
  identities:
    dev-access:
      kind: aws/permission-set
      default: true
      via:
        provider: company-sso
      principal:
        name: DeveloperAccess
        account:
          name: development

profiles/ci/auth.yaml

auth:
  providers:
    github-oidc:
      kind: github/oidc
      region: us-east-1
  identities:
    deploy:
      kind: aws/assume-role
      default: true
      via:
        provider: github-oidc
      principal:
        assume_role: arn:aws:iam::123456789012:role/GitHubActionsRole

profiles/platform/auth.yaml

auth:
  providers:
    company-sso:
      kind: aws/iam-identity-center
      region: us-east-1
      start_url: https://company.awsapps.com/start
      session:
        duration: 8h
# Activate a profile
atmos --profile developer terraform plan myapp -s dev
ATMOS_PROFILE=ci atmos terraform apply myapp -s prod

Tutorials​

See Also​