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

**Configure Authentication**

Learn how to configure providers, identities, keyring, and credential storage in your atmos.yaml.

Configuration Reference[Read more](/cli/configuration/auth)

## Usage

## Examples

```shell
# 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

# Open cloud console in browser
atmos auth console

# Start a shell with authentication
atmos auth shell
```

## Flags

- **`--identity` (alias `-i`)**

  Specify the identity to use for authentication. Can be:

  An identity name (e.g., --identity admin or --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.

  :::tip Flag Placement Best Practice
  When using `--identity` with a value, place it **before the `--` separator** and before any positional arguments:
  ```shell
  # Recommended: --identity before -- separator
  atmos auth exec --identity admin -- terraform plan

  # Also recommended: use equals syntax for clarity
  atmos auth exec --identity=admin -- terraform plan
  ```
  Using the equals syntax (`--identity=admin`) is unambiguous and works in all contexts.
  :::

## Subcommands

## Authentication Concepts

### Providers

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

**AWS**

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

**Azure**

- **Device Code**: `azure/device-code`
- **OIDC (Workload Identity)**: `azure/oidc`
- **CLI**: `azure/cli`

**GCP**

- **Application Default Credentials**: `gcp/adc`
- **Workload Identity Federation**: `gcp/workload-identity-federation`

### Identities

**Identities** represent the user accounts or roles available from provider credentials:

**AWS**

- **Permission Set**: `aws/permission-set`
- **Assume Role**: `aws/assume-role`
- **Assume Root**: `aws/assume-root`
- **User (Break-glass)**: `aws/user`

**Azure**

- **Subscription**: `azure/subscription`

**GCP**

- **Service Account**: `gcp/service-account`
- **Project**: `gcp/project`

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

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

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

```yaml
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.
:::

```yaml
auth:
  providers:
    okta-saml:
      kind: aws/saml
      region: us-east-1
      url: https://company.okta.com/app/amazon_aws/abc123/sso/saml

      # Optional: Specify SAML driver (Browser, GoogleApps, Okta, ADFS)
      # If not specified, Atmos automatically selects the best option
      driver: Browser

      # Optional: Auto-download browser drivers on first use (recommended for Browser driver)
      download_browser_driver: true

  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): Launches an automated Chromium browser window for interactive SAML authentication. Uses Playwright for browser automation.

  **How it works:**

  - Atmos opens a **sandboxed Chromium browser window** (not your regular browser)
  - You interact with the SAML login page (username, password, MFA) in this window
  - The browser window is **visible** (not headless) so you can complete authentication
  - After successful login, Atmos captures the SAML response automatically
  - Your regular browser's saved passwords and extensions are **not available** (sandboxed instance)

  **Recommended: Automatic Download**

  ```yaml
  providers:
    my-saml:
      kind: aws/saml
      driver: Browser
      download_browser_driver: true  # Auto-downloads Chromium browser (~140 MB) on first use
  ```

  With this configuration, Atmos automatically downloads the Chromium browser binary on your first authentication attempt and stores it in your user cache directory:

  - macOS: `~/Library/Caches/ms-playwright/`
  - Linux: `~/.cache/ms-playwright/`
  - Windows: `%LOCALAPPDATA%\ms-playwright\`

  :::info Manual Installation
  Manual Chromium installation is **not recommended** because:

  - Version compatibility must be carefully managed between Atmos, saml2aws, and playwright-go
  - Different installation methods use different cache directories which may not be detected
  - The automatic download option handles everything correctly

  The `download_browser_driver: true` option is the simplest and most reliable approach.
  :::

  **Note**: The Chromium browser binary does not need to be in your system PATH. Playwright manages the browser binary location automatically.

  **Advanced: Custom Browser Configuration**

  You can configure a custom browser type or executable path instead of using the automatically downloaded Chromium:

  ```yaml
  providers:
    my-saml:
      kind: aws/saml
      driver: Browser
      browser_type: msedge           # Use Microsoft Edge instead of Chromium
      browser_executable_path: /usr/bin/microsoft-edge  # Path to Edge binary
  ```

  **Supported `browser_type` values:**

  - `chromium` - Default Chromium browser (default if not specified)
  - `firefox` - Mozilla Firefox browser
  - `webkit` - WebKit browser engine
  - `chrome` - Google Chrome (stable)
  - `chrome-beta`, `chrome-dev`, `chrome-canary` - Chrome development channels
  - `msedge` - Microsoft Edge (stable)
  - `msedge-beta`, `msedge-dev`, `msedge-canary` - Edge development channels

  **`browser_executable_path`** - Optional path to a browser executable. When specified with `browser_type`, allows using a system-installed browser instead of Playwright's managed version.

  :::warning Custom Browser Support
  Using custom browsers requires:

  - The browser must be installed and at the specified path
  - Browser version must be compatible with Playwright's automation protocol
  - `download_browser_driver: true` should still be set to ensure Playwright drivers are available

  **Most users should use the default Chromium** (with `download_browser_driver: true`) for best reliability.
  :::

- **`GoogleApps`**: Uses Google Apps SAML API (no browser automation needed)

- **`Okta`**: Uses Okta SAML API (no browser automation needed)

- **`ADFS`**: Uses Active Directory Federation Services API (no browser automation needed)

**Auto-Detection**: If `driver` is not specified, Atmos automatically selects the best option based on your SAML URL and whether browser drivers are available.

### GitHub Actions OIDC

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

```yaml
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:

```yaml
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](/cli/commands/auth/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:**

```yaml
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:

```yaml
# 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:**

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

**Authentication Flow with MFA:**

When you authenticate with an MFA-enabled identity:

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

## Disabling Authentication

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

```bash
# 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
```

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

When disabled, Atmos skips all identity authentication and falls back to standard cloud provider SDK credential resolution (AWS, Azure, or GCP).

## Environment Variable Formats

The `atmos auth env` command outputs credentials in multiple formats:

### Bash Format

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

### JSON Format

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

### Dotenv Format

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

## CI/CD Integration

### GitHub Actions

```yaml
name: Deploy Infrastructure
on: [push]

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

    steps:
      - uses: actions/checkout@v6

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

### GitLab CI

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

## Workflows Integration

Use Atmos Auth in workflows:

```yaml
# 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
```

## Troubleshooting

### Common Issues

**Configuration Validation Errors**

```bash
atmos auth validate --verbose
```

**Authentication Failures**

```bash
# 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**

```bash
# Verify identity configuration
atmos auth validate

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

**Environment Variable Issues**

```bash
# 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:

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

# Set log level explicitly
ATMOS_LOG_LEVEL=Debug atmos auth whoami
```

## Security Best Practices

- Never commit credentials to version control
- Use environment variables for sensitive data: `!env VAR_NAME`
- Regularly rotate credentials
- Use least-privilege access
- Validate configurations regularly: `atmos auth validate`
- Use shorter session durations for high-security environments