atmos auth

Atmos Auth gives you a single, consistent way to authenticate with multiple cloud providers. It supports SAML, SSO, OIDC, GitHub Actions, and static user identities. By consolidating these flows into one system, you no longer need to juggle separate tools or browser plugins, just to try to login. And because it’s built into Atmos, it works seamlessly with stacks, components, workflows, shells, and even custom commands.

Usage

atmos auth --help

Examples

# Validate configuration
atmos auth validate

# Authenticate with the default identity
atmos auth login

# Authenticate with a specific identity
atmos auth login --identity admin

# Print environment variables in JSON
atmos auth env --format json

# Execute a command with authentication context
atmos auth exec -- terraform plan

# Show current authentication status
atmos auth whoami

Flags

--identity (alias -i)

Specify the identity to use for authentication. Can be:

An identity name (e.g., --identity admin)
Empty for interactive selection (e.g., --identity)
false to disable authentication (e.g., --identity=false)

When set to false, Atmos skips identity authentication and uses standard AWS credential resolution.

Subcommands

📄️ env

Export temporary cloud credentials as environment variables for the selected identity.

📄️ exec

Execute a command with authentication environment variables set for the selected identity.

📄️ login

Authenticate to cloud providers using an identity defined in atmos.yaml.

📄️ user

Manage cloud provider user credentials in the local keychain.

📄️ user configure

Configure static AWS user credentials and store them securely in your system keychain.

📄️ validate

Validate the authentication configuration in atmos.yaml for syntax and logical errors.

📄️ whoami

Show current authentication status for the selected identity.

🗃️ Tutorials

3 items

📄️ list

List all configured authentication providers and identities with their relationships and chains.

📄️ shell

Launch an interactive shell with authentication environment variables configured for the selected identity.

📄️ console

Open cloud provider web console in your default browser using authenticated credentials.

📄️ logout

Remove locally cached credentials and session data

Overview

Atmos Auth provides a unified authentication system for cloud providers, supporting complex identity chaining and credential management. This guide will help you get started with configuring and using Atmos Auth for your infrastructure projects.

Quick Start

1. Basic Configuration

Add authentication configuration to your atmos.yaml:

auth:
  # Configure logging
  ## Optional, defaults to Atmos log level
  logs:
    level: Info

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

      # Optional: Configure session durations
      session:
        duration: 1h  # Credential lifetime for auth shell/env/exec

      console:
        session_duration: 12h  # Web console session duration (max 12h for AWS)

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

Notes:

Region is required for the GitHub OIDC provider and is validated at construction time.

2. Validate Configuration

atmos auth validate

3. Authenticate

# Use default identity
atmos auth login

# Use specific identity
atmos auth login --identity admin

4. Check Authentication Status

atmos auth whoami

5. Use with Terraform

# Atmos automatically handles authentication
atmos terraform plan mycomponent -s dev

Authentication Concepts

Providers

Providers are the upstream systems that Atmos Auth uses to obtain initial credentials:

AWS SSO: aws/iam-identity-center
AWS SAML: aws/saml
GitHub OIDC: github/oidc

Identities

Identities represent the user accounts or roles available from provider credentials, such as:

AWS Permission Set: aws/permission-set
AWS Assume Role: aws/assume-role
AWS User: aws/user

Identity Chaining

Identity chaining (often called role chaining) is when one identity is used to obtain another, forming a sequence of temporary credentials.

For example, you might:

Start with an SSO login to obtain base credentials.
Use those credentials to assume a cross-account role.
Optionally, chain again into another role with more limited or specialized permissions.

This allows you to:

Access multiple accounts or environments without long-lived keys.
Follow least-privilege practices by escalating only as needed.
Automate complex authentication flows while still relying on short-lived credentials.

You can chain identities to create complex authentication flows like this:

identities:
  # Base permission set from SSO
  base-admin:
    kind: aws/permission-set
    via:
      provider: my-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 another identity
    principal:
      assume_role: arn:aws:iam::999999999999:role/ProductionAdmin
      session_name: atmos-prod-access

Configuration Examples

AWS SSO with Permission Sets

AWS Permission Set identities assume roles via AWS IAM Identity Center (SSO). The account field specifies which AWS account contains the permission set.

Account Specification Options:

You can specify the account using either:

account.name - Account name/alias (resolved via SSO ListAccounts API)
account.id - Numeric account ID (used directly, no lookup required)

Using account names is recommended as it's more readable and maintainable. Account names match the account names/aliases configured in AWS Organizations.

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

  identities:
    dev-admin:
      kind: aws/permission-set
      default: true
      via:
        provider: company-sso
      principal:
        name: AdminAccess
        account:
          name: development
          # OR use account ID directly:
          # id: "123456789012"

    prod-readonly:
      kind: aws/permission-set
      via:
        provider: company-sso
      principal:
        name: ReadOnlyAccess
        account:
          name: production

AWS SAML Authentication

note

The aws/saml provider requires the next identity to be of kind aws/assume-role. This is because the assume_role is the chosen role to sign into after the SAML authentication.

auth:
  providers:
    okta-saml:
      kind: aws/saml
      region: us-east-1
      url: https://company.okta.com/app/amazon_aws/abc123/sso/saml
      idp_arn: arn:aws:iam::123456789012:saml-provider/okta-saml
      # Optional: Specify SAML driver (Browser, GoogleApps, Okta, ADFS).
      # Note: provider_type is deprecated; use driver instead.
      # If not specified, Atmos automatically selects the best driver based on:
      # 1. Browser (if Playwright drivers are installed)
      # 2. Provider-specific fallback (GoogleApps for Google, Okta for Okta, ADFS for ADFS)
      # 3. Browser with auto-download
      driver: Browser

  identities:
    saml-admin:
      kind: aws/assume-role
      default: true
      via:
        provider: okta-saml
      principal:
        assume_role: arn:aws:iam::123456789012:role/AdminRole

SAML Driver Options

The driver field controls how Atmos authenticates with your SAML identity provider:

Browser (recommended): Opens your system browser for authentication. Requires Playwright drivers to be installed or enables auto-download when supported.
```
# Install Playwright drivers
go run github.com/playwright-community/playwright-go/cmd/playwright@latest install
```
GoogleApps: Uses Google Apps SAML API (no browser needed)
Okta: Uses Okta SAML API (no browser needed)
ADFS: Uses Active Directory Federation Services API (no browser needed)

If driver is not specified, Atmos automatically selects the best option based on your SAML URL and available drivers.

GitHub Actions OIDC

auth:
  providers:
    github-oidc:
      kind: github/oidc
      region: us-east-1 # Required
      spec:
        audience: sts.us-east-1.amazonaws.com

  identities:
    github-deploy:
      kind: aws/assume-role
      default: true
      via:
        provider: github-oidc
      principal:
        assume_role: arn:aws:iam::123456789012:role/GitHubActionsRole

AWS User (Break-glass)

AWS User identities support static IAM user credentials with optional multi-factor authentication (MFA).

Basic Configuration

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

Alternatively, store credentials in the system keychain:

auth:
  identities:
    emergency-user:
      kind: aws/user
      credentials:
        region: us-east-1

Then run atmos auth user configure to configure the credentials on the keychain. See user configure for details.

Multi-Factor Authentication (MFA) for AWS

AWS User identities support MFA devices for enhanced security. When an MFA device ARN is configured, Atmos will prompt for a time-based one-time password (TOTP) during authentication.

note

This section describes MFA implementation for AWS IAM users. Other cloud providers will have their own MFA implementations in future releases.

Configuration with MFA:

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
        mfa_arn: arn:aws:iam::123456789012:mfa/username
        region: us-east-1

The mfa_arn can be specified in several ways:

# Direct ARN (suitable for shared team configurations)
mfa_arn: arn:aws:iam::123456789012:mfa/username

# Environment variable reference (suitable for personal configurations)
mfa_arn: !env AWS_MFA_ARN

# Stored in keychain (via atmos auth user configure)
# The mfa_arn field can be omitted from YAML if stored in keychain

Finding Your MFA Device ARN:

Log into AWS Console
Navigate to IAM → Users → [Your Username]
Click the "Security credentials" tab
Find "Assigned MFA device" section
Copy the ARN (format: arn:aws:iam::ACCOUNT_ID:mfa/USERNAME)

Authentication Flow with MFA:

When you authenticate with an MFA-enabled identity:

$ atmos auth login --identity emergency-user
╭─────────────────────────────────────────────────────╮
│ Enter MFA Token                                     │
├─────────────────────────────────────────────────────┤
│ MFA Device: arn:aws:iam::123456789012:mfa/user     │
│                                                     │
│ ┌──────────────────────────────────────────────┐   │
│ │ 123456                                       │   │
│ └──────────────────────────────────────────────┘   │
╰─────────────────────────────────────────────────────╯

Atmos will:

Read your long-lived credentials (access key + secret)
Prompt for a 6-digit TOTP code from your authenticator app
Call AWS STS GetSessionToken with MFA device ARN and TOTP code
Store temporary session credentials (valid for configured duration, default: 12h)
Use session credentials for subsequent AWS API calls

Security Notes:

MFA Device ARN is not a secret - It's safe to store in YAML configuration files
TOTP codes are never stored - You must enter them each time you authenticate
Session tokens are cached - Valid for 12 hours by default (configurable up to 36h with MFA), avoiding repeated MFA prompts
Long-lived credentials remain secure - Stored in OS keychain, not in plain text

When to Use MFA:

Compliance requirements mandate MFA for privileged access
Break-glass/emergency access accounts requiring extra security
Production environment access
Any scenario where you want defense-in-depth authentication

Troubleshooting:

"MFA token must be 6 digits" - Ensure you're entering exactly 6 digits from your authenticator app
"Invalid MFA token" - Check that your device's clock is synchronized (TOTP is time-based)
"MFA device not found" - Verify the MFA ARN matches your AWS IAM configuration
Repeated MFA prompts - Session tokens expire after the configured duration (default: 12h); re-authentication is required

CLI Commands

Authentication Commands

# Validate auth configuration
atmos auth validate
atmos auth validate --verbose

# Login (authenticate and cache credentials)
atmos auth login
atmos auth login --identity prod-admin

# Check current authentication status
atmos auth whoami
atmos auth whoami --identity dev-admin

# Get environment variables
atmos auth env
atmos auth env --identity prod-admin --format bash
atmos auth env --format json
atmos auth env --format dotenv

# Execute command with authentication
atmos auth exec --identity prod-admin -- aws sts get-caller-identity
atmos auth exec -- terraform plan

# Configure AWS user credentials
atmos auth user configure

Component-Level Configuration

Override authentication settings for specific components:

# In your component configuration
components:
  terraform:
    myapp:
      auth:
        identities:
          custom-role:
            kind: aws/assume-role
            via:
              provider: my-sso
            principal:
              assume_role: arn:aws:iam::123456789012:role/MyAppRole

Environment Variable Formats

Bash Format

atmos auth env --format bash
# Output:
export AWS_ACCESS_KEY_ID="AKIA..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_SESSION_TOKEN="..."

JSON Format

atmos auth env --format json
# Output:
{
  "AWS_ACCESS_KEY_ID": "AKIA...",
  "AWS_SECRET_ACCESS_KEY": "...",
  "AWS_SESSION_TOKEN": "..."
}

Dotenv Format

atmos auth env --format dotenv
# Output:
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
AWS_SESSION_TOKEN=...

Default Identity Handling

A default identity is the one Atmos Auth will use automatically when no specific identity is requested.

If you configure a single identity and mark it as default: true, Atmos will always use it without requiring you to pass --identity.
If multiple identities are defined, you can still mark one as default, but you’ll need to explicitly choose another when you don’t want the default.
If no default is set and multiple identities exist, Atmos will require you to specify which identity to use.

This makes workflows simpler because you can avoid passing extra flags for the identity you use most often.

Single Default

When you have one default identity, it's used automatically:

identities:
  admin:
    kind: aws/permission-set
    default: true # This will be used by default

Multiple Defaults

When multiple defaults exist, Atmos behavior depends on the environment:

Interactive Mode: Prompts you to choose

$ atmos auth whoami
? Multiple default identities found. Please choose one:
  ▸ dev-admin
    prod-admin
    staging-admin

No Defaults

Interactive Mode: Shows all available identities

$ atmos auth whoami
? No default identity configured. Please choose an identity:
  ▸ dev-admin
    prod-admin
    staging-admin

Disabling Identity Authentication

In some scenarios (e.g., CI/CD environments), you may want to explicitly disable Atmos-managed identity authentication and use standard AWS credential resolution instead.

When to Disable Authentication

CI/CD pipelines using GitHub Actions OIDC or other native cloud provider authentication
Development environments where you want to use local AWS profiles temporarily
Testing scenarios where you want to bypass Atmos authentication
Mixed environments where some contexts use Atmos auth and others don't

How to Disable

You can disable identity authentication by setting the --identity flag to false (or equivalent boolean false values):

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

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

Supported Disable Values

The following values are recognized as "disable authentication":

false, False, FALSE (case-insensitive)
0 (zero)
no, No, NO (case-insensitive)
off, Off, OFF (case-insensitive)

Behavior When Disabled

When authentication is disabled:

Atmos skips all identity authentication - No providers are initialized, no identities are loaded
Uses standard credential resolution - Falls back to cloud provider SDK defaults (e.g., for AWS: environment variables, shared credentials file, instance metadata, web identity tokens)
No configuration required - Works even when atmos.yaml has identity configurations

GitHub Actions Example

name: Deploy Infrastructure
on: [push]

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read

    steps:
      - uses: actions/checkout@v4

      - name: Configure AWS credentials via OIDC
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/GitHubActionsRole
          aws-region: us-east-1

      - name: Deploy with Atmos (using GitHub OIDC credentials)
        env:
          ATMOS_IDENTITY: false  # Disable Atmos auth, use GitHub-provided credentials
        run: |
          atmos terraform apply mycomponent --stack=prod

Local Development Example

# Use your personal cloud provider profile temporarily (e.g., AWS profile)
export AWS_PROFILE=my-personal-profile
atmos terraform plan mycomponent --stack=dev --identity=false

# Or inline
AWS_PROFILE=my-personal-profile atmos terraform plan mycomponent --stack=dev --identity=false

Precedence

When both Atmos identity and --identity=false are configured:

--identity=false flag (highest priority)
ATMOS_IDENTITY=false environment variable
Default identity from atmos.yaml

The disable flag always takes precedence, even over configured default identities.

Credential Storage

Atmos supports three keyring backends for storing authentication credentials, selectable via configuration:

System Keyring (Default)

Uses your operating system's native secure credential storage:

macOS: Keychain
Linux: Secret Service (GNOME Keyring, KDE Wallet)
Windows: Windows Credential Manager

# atmos.yaml (optional - this is the default)
auth:
  keyring:
    type: system

Best for: Personal workstations with OS-level security integration

File Keyring

AES-256 encrypted file-based storage with interactive password prompting:

# atmos.yaml
auth:
  keyring:
    type: file
    spec:
      path: ~/.atmos/keyring  # Optional: custom path
      password_env: ATMOS_KEYRING_PASSWORD  # Optional: env var name

Best for: Shared environments, servers, or CI/CD pipelines

Default storage location:

Follows the XDG Base Directory Specification
Default: $XDG_DATA_HOME/atmos/keyring (typically ~/.local/share/atmos/keyring on Linux/Unix and macOS)
Can be overridden via ATMOS_XDG_DATA_HOME or XDG_DATA_HOME environment variables
Custom path can be specified via spec.path configuration

Password resolution order:

Environment variable (ATMOS_KEYRING_PASSWORD or custom from password_env)
Interactive prompt (if TTY available)
Error if neither available

# Interactive mode - prompts for password
atmos auth login --identity prod-admin

# Automation mode - password from environment
export ATMOS_KEYRING_PASSWORD="my-secure-password"
atmos auth login --identity prod-admin

# Custom XDG data directory
export ATMOS_XDG_DATA_HOME=/custom/data
atmos auth login --identity prod-admin

Memory Keyring

In-memory storage with no persistence (credentials lost on exit):

# atmos.yaml
auth:
  keyring:
    type: memory

Best for: Unit tests, integration tests, and temporary credential caching

Note: Can also be set via ATMOS_KEYRING_TYPE environment variable

Credential Expiration

Credentials are automatically refreshed when expired
You can check expiration with atmos auth whoami
Manual refresh: atmos auth login --identity <name>

AWS File Management

Atmos manages AWS credential files separately from your personal AWS configuration, following the XDG Base Directory Specification.

This design avoids common problems:

No risk of overwriting personal config: Atmos never modifies ~/.aws/credentials or ~/.aws/config. This prevents accidental overrides of credentials you manage yourself and keeps your personal AWS setup intact.
Provider isolation: Each provider's credentials live under the Atmos namespace (e.g., ~/.config/atmos/aws/<provider>/ on Linux), making it safe and easy to switch between SSO, SAML, OIDC, or static identities without conflicts.
Seamless SDK integration: Under the hood, Atmos sets the standard AWS SDK environment variables (AWS_SHARED_CREDENTIALS_FILE, AWS_CONFIG_FILE) so tools that already rely on the AWS SDK (like Terraform, AWS CLI, CDK) just work without extra setup.
Project convenience: Since all configuration lives under Atmos, every project is self-contained. You don't have to share custom AWS config steps with teammates, and you can cleanly delete all credentials or config associated with a profile at any time.
XDG compliance: Atmos follows platform conventions, storing credentials in standard locations that respect $XDG_CONFIG_HOME and $ATMOS_XDG_CONFIG_HOME environment variables.

This makes authentication more secure, more portable across projects, and less error-prone in day-to-day development.

File Locations

Atmos-managed AWS credentials are stored following the XDG Base Directory Specification:

Linux:

Credentials: ~/.config/atmos/aws/<provider>/credentials
Config: ~/.config/atmos/aws/<provider>/config

macOS:

Credentials: ~/.config/atmos/aws/<provider>/credentials
Config: ~/.config/atmos/aws/<provider>/config

Windows:

Credentials: %APPDATA%\atmos\aws\<provider>\credentials
Config: %APPDATA%\atmos\aws\<provider>\config

Custom Locations:

You can override the default location using environment variables:

# Override for Atmos only
export ATMOS_XDG_CONFIG_HOME=/custom/path

# Override for all XDG-compliant tools
export XDG_CONFIG_HOME=/custom/path

Or configure per-provider in atmos.yaml:

auth:
  providers:
    my-sso:
      kind: aws/iam-identity-center
      # ... other config ...
      spec:
        files:
          base_path: /custom/path/aws

Environment Variables

Your files remain untouched
Your existing ~/.aws/credentials and ~/.aws/config are never modified
Atmos uses separate files to avoid conflicts
Standard AWS environment variables are set to point to Atmos-managed files

Troubleshooting

Common Issues

Configuration Validation Errors

atmos auth validate --verbose

Authentication Failures

# Check current status
atmos auth whoami

# Re-authenticate
atmos auth login --identity <name>

# Check with verbose output
atmos auth login --identity <name> --verbose

Permission Errors

# Verify identity configuration
atmos auth validate

# Check assumed role/permissions
atmos auth exec --identity <name> -- aws sts get-caller-identity

Environment Variable Issues

# Check what variables are set
atmos auth env --identity <name>

# Test environment
atmos auth exec --identity <name> -- env | grep AWS

Debug Mode

Enable debug logging for detailed troubleshooting:

# Verbose CLI output
atmos auth validate --verbose
atmos auth login --identity <name> --verbose

# Set log level explicitly
ATMOS_LOG_LEVEL=Debug atmos auth whoami

Logs Configuration

Configure logging in atmos.yaml:

auth:
  logs:
    level: Debug # Debug, Info, Warn, Error
    file: /tmp/atmos-auth.log

Workflows Integration

Use Atmos Auth in workflows:

# atmos.yaml workflows section
workflows:
  deploy:
    description: Deploy with authentication
    steps:
      - name: validate-auth
        command: atmos auth validate
      - name: deploy-dev
        command: atmos terraform apply myapp -s dev
        identity: dev-admin
      - name: deploy-prod
        command: atmos terraform apply myapp -s prod
        identity: prod-admin

CI/CD Integration

GitHub Actions

- name: Configure AWS credentials
  run: |
    # Atmos handles authentication automatically in CI
    atmos auth whoami

- name: Deploy infrastructure
  run: |
    atmos terraform apply myapp -s prod

GitLab CI

deploy:
  script:
    - atmos auth validate
    - atmos terraform apply myapp -s prod

Security Best Practices

Credential Management

Never commit credentials to version control
Use environment variables for sensitive data: !env VAR_NAME
Regularly rotate credentials
Use least-privilege access

Session Duration

Configure session durations based on your security requirements:

auth:
  providers:
    company-sso:
      kind: aws/iam-identity-center
      session:
        duration: "8h"  # Balance security and usability

  identities:
    prod-admin:
      kind: aws/user
      session:
        duration: "1h"  # Shorter for high-security environments

Supported formats: Integers (seconds), Go durations ("1h", "8h"), or days ("1d") IAM user limits: 15m-12h (no MFA) or 15m-36h (with MFA)

Shorter sessions are more secure but require more frequent re-authentication.

Configuration Security

Validate configurations regularly: atmos auth validate
Use specific account IDs in permission sets
Implement proper session naming for audit trails
Monitor authentication logs

Environment Isolation

Use different identities for different environments
Separate providers for different security domains
Implement proper identity chaining for cross-account access

Usage​

atmos auth --help

Examples​

Flags​

Subcommands​

📄️ env

📄️ exec

📄️ login

📄️ user

📄️ user configure

📄️ validate

📄️ whoami

🗃️ Tutorials

📄️ list

📄️ shell

📄️ console

📄️ logout

Overview​

Quick Start​

1. Basic Configuration​

2. Validate Configuration​

3. Authenticate​

4. Check Authentication Status​

5. Use with Terraform​

Authentication Concepts​

Providers​

Identities​

Identity Chaining​

Configuration Examples​

AWS SSO with Permission Sets​

AWS SAML Authentication​

SAML Driver Options​

GitHub Actions OIDC​

AWS User (Break-glass)​

Basic Configuration​

Multi-Factor Authentication (MFA) for AWS​

CLI Commands​

Authentication Commands​

Component-Level Configuration​

Environment Variable Formats​

Bash Format​

JSON Format​

Dotenv Format​

Default Identity Handling​

Single Default​

Multiple Defaults​

No Defaults​

Disabling Identity Authentication​

When to Disable Authentication​

How to Disable​

Supported Disable Values​

Behavior When Disabled​

GitHub Actions Example​

Local Development Example​

Precedence​

Credential Storage​

System Keyring (Default)​

File Keyring​

Memory Keyring​

Credential Expiration​

AWS File Management​

File Locations​

Environment Variables​

Troubleshooting​

Common Issues​

Debug Mode​

Logs Configuration​

Workflows Integration​

CI/CD Integration​

GitHub Actions​

GitLab CI​

Security Best Practices​

Credential Management​

Session Duration​

Configuration Security​

Environment Isolation​