Skip to main content

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 default identity for subcommands. Can be overridden per command.
--profile
Atmos profile used to resolve configuration when running auth subcommands.

Subcommands​

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

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

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:

  1. Start with an SSO login to obtain base credentials.
  2. Use those credentials to assume a cross-account role.
  3. 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: "123456789012"

  # 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​

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: "123456789012"

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

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

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

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)​

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

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.

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

Credential Storage​

Atmos securely stores credentials using your operating system's keyring:

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

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.

This design avoids common problems:

  1. 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.

  2. Provider isolation: Each provider’s credentials live under ~/.aws/atmos/<provider>/, making it safe and easy to switch between SSO, SAML, OIDC, or static identities without conflicts.

  3. 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.

  4. 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.

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

File Locations​

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

Environment Variables​

  • Your files remain untouched
  • Your existing ~/.aws/credentials and ~/.aws/config are never modified
  • Atmos uses separate files to avoid conflicts

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

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