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, 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

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

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

Subpages​

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

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

  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

Using Profiles​

Use Atmos profiles to define different authentication configurations for various use cases:

atmos.yaml

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

  # Profile for CI/CD
  ci:
    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

  # Profile for platform engineers
  platform:
    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 dev terraform plan myapp -s dev
ATMOS_PROFILE=ci atmos terraform apply myapp -s prod

See Also​