# Configure Authentication

The `auth` section configures how Atmos obtains and manages credentials for cloud providers and external services. Auth configuration is primarily defined in `atmos.yaml` but can be extended at the component level via `auth` as a top-level key.

## Use Cases

- **AWS SSO Integration:** Authenticate via AWS IAM Identity Center (SSO) for seamless credential management.
- **Azure Authentication:** Authenticate via device code flow, OIDC (workload identity), or existing Azure CLI credentials. Supports Azure Commercial, Government (GCC High), and China (Mooncake) clouds via the `cloud_environment` setting.
- **GCP Authentication:** Authenticate via Application Default Credentials or Workload Identity Federation.
- **Role Assumption Chains:** Configure multi-account access through role assumption.
- **Credential Storage:** Securely store and retrieve credentials using system keyrings.
- **Environment Injection:** Automatically inject credentials as environment variables for components.

## Configuration Locations

### Global Configuration (atmos.yaml)

The primary auth configuration is defined in your `atmos.yaml`:

```yaml
# atmos.yaml
auth:
  providers:
    aws-sso:
      kind: aws-sso
      start_url: https://acme.awsapps.com/start
      region: us-east-1

  identities:
    prod-admin:
      kind: aws
      via:
        provider: aws-sso
      principal:
        name: AdministratorAccess
        account:
          id: "123456789012"
```

### Component-Level Configuration

Components can override auth configuration by defining an `auth` section with an identity marked as `default: true`:

```yaml
components:
  terraform:
    vpc:
      auth:
        identities:
          prod-admin:
            default: true
```

## Auth Configuration Structure

### Providers

Providers define how Atmos connects to authentication sources:

```yaml
auth:
  providers:
    my-sso:
      kind: aws-sso
      start_url: https://company.awsapps.com/start
      region: us-east-1
      default: true
      session:
        duration: 8h
      console:
        session_duration: 12h
```

**Provider Fields:**

- **`kind`**
  Provider type (e.g., 
  `aws/iam-identity-center`
  , 
  `azure/device-code`
  , 
  `azure/oidc`
  , 
  `azure/cli`
  , 
  `gcp/adc`
  , 
  `gcp/workload-identity-federation`
  ).
- **`start_url`**
  AWS SSO portal URL.
- **`region`**
  AWS region for SSO.
- **`default`**
  Mark as default provider.
- **`session.duration`**
  CLI session duration.
- **`console.session_duration`**
  AWS Console session duration.

### Identities

Identities represent specific credentials or roles:

```yaml
auth:
  identities:
    dev-developer:
      kind: aws
      via:
        provider: aws-sso
      principal:
        name: DeveloperAccess
        account:
          name: acme-dev
          id: "111111111111"
      env:
        - key: AWS_PROFILE
          value: dev-developer

    prod-admin:
      kind: aws
      via:
        provider: aws-sso
      principal:
        name: AdministratorAccess
        account:
          id: "222222222222"
      default: true
```

**Identity Fields:**

- **`kind`**
  Identity type (e.g., 
  `aws/permission-set`
  , 
  `aws/assume-role`
  , 
  `aws/ambient`
  , 
  `ambient`
  , 
  `azure/subscription`
  , 
  `gcp/service-account`
  , 
  `gcp/project`
  ).
- **`via.provider`**
  Provider to use for authentication.
- **`via.identity`**
  Chain through another identity.
- **`principal.name`**
  Permission set or role name.
- **`principal.account.id`**
  Target AWS account ID.
- **`principal.account.name`**
  Target AWS account name.
- **`credentials`**
  Static credentials (use sparingly).
- **`env`**
  Environment variables to set.
- **`default`**
  Mark as default identity.
- **`alias`**
  Alternative name for the identity.
- **`session.duration`**
  Session duration override.

### Keyring Configuration

Configure how credentials are stored:

```yaml
auth:
  keyring:
    type: system  # system, file, or memory
    spec:
      # Type-specific configuration
```

**Keyring Types:**

- **`system`**
  Use OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service).
- **`file`**
  Store in encrypted file.
- **`memory`**
  Store in memory only (not persisted).

## Examples

### AWS SSO with Multiple Accounts

**File:** `atmos.yaml`

```yaml
auth:
  providers:
    acme-sso:
      kind: aws-sso
      start_url: https://acme.awsapps.com/start
      region: us-east-1
      default: true

  identities:
    dev-admin:
      kind: aws
      via:
        provider: acme-sso
      principal:
        name: AdministratorAccess
        account:
          name: acme-dev
          id: "111111111111"

    staging-admin:
      kind: aws
      via:
        provider: acme-sso
      principal:
        name: AdministratorAccess
        account:
          name: acme-staging
          id: "222222222222"

    prod-admin:
      kind: aws
      via:
        provider: acme-sso
      principal:
        name: AdministratorAccess
        account:
          name: acme-prod
          id: "333333333333"
      default: true
```

### Role Assumption Chain

Configure a chain where you first authenticate via SSO, then assume a role in another account:

**File:** `atmos.yaml`

```yaml
auth:
  providers:
    acme-sso:
      kind: aws-sso
      start_url: https://acme.awsapps.com/start
      region: us-east-1

  identities:
    # First, authenticate to management account via SSO
    mgmt-access:
      kind: aws
      via:
        provider: acme-sso
      principal:
        name: ManagementAccess
        account:
          id: "000000000000"

    # Then, assume role in target account from management
    prod-deployer:
      kind: aws
      via:
        identity: mgmt-access  # Chain through mgmt-access
      principal:
        name: arn:aws:iam::333333333333:role/TerraformDeployer
```

### Ambient Credentials (IRSA / EC2 Instance Profile / ECS Task Role)

Use the `aws/ambient` identity kind when Atmos runs on infrastructure that already has AWS credentials
available — such as an EKS pod with IRSA, an EC2 instance with an instance profile, or an ECS task with a task role.
Unlike other identity kinds, `aws/ambient` does **not** clear credential environment variables or disable IMDS.
It trusts the AWS SDK's default credential provider chain.

**File:** `atmos.yaml`

```yaml
auth:
  identities:
    eks-deployer:
      kind: aws/ambient
      principal:
        region: us-east-1
```

For a generic cloud-agnostic passthrough that simply preserves all environment variables as-is, use `ambient`:

**File:** `atmos.yaml`

```yaml
auth:
  identities:
    passthrough:
      kind: ambient
```

#### Chaining with Assume Role

A common pattern is to use ambient credentials as the base for cross-account role assumption:

**File:** `atmos.yaml`

```yaml
auth:
  identities:
    # Use the pod's IRSA credentials as the base
    pod-base:
      kind: aws/ambient
      principal:
        region: us-east-1

    # Assume a role in another account using the pod's credentials
    cross-account-deployer:
      kind: aws/assume-role
      via:
        identity: pod-base
      principal:
        assume_role: "arn:aws:iam::999999999999:role/TerraformDeployRole"
```

### Component-Level Identity Selection

**File:** `stacks/orgs/acme/plat/prod/us-east-1.yaml`

```yaml
components:
  terraform:
    # This component needs admin access
    iam-roles:
      auth:
        identities:
          prod-admin:
            default: true
      vars:
        # ...

    # This component uses read-only access
    monitoring:
      auth:
        identities:
          prod-readonly:
            default: true
      vars:
        # ...
```

### Environment Variable Injection

**File:** `atmos.yaml`

```yaml
auth:
  identities:
    prod-admin:
      kind: aws
      via:
        provider: acme-sso
      principal:
        name: AdministratorAccess
        account:
          id: "333333333333"
      env:
        - key: AWS_PROFILE
          value: prod-admin
        - key: AWS_DEFAULT_REGION
          value: us-east-1
```

When using this identity, the specified environment variables are automatically set.

## Credential Realm Isolation

By default, Atmos stores credentials in a shared location that all Atmos projects on the same machine can access.
If you work with multiple repositories that define identities with the same name but for different AWS accounts,
you can use **realms** to isolate credentials between projects.

### Configuration

Set a realm in your `atmos.yaml`:

**File:** `atmos.yaml`

```yaml
auth:
  realm: my-project
```

Or use the `ATMOS_AUTH_REALM` environment variable:

```bash
export ATMOS_AUTH_REALM=my-project
```

### Precedence

Realm is resolved in this order (highest to lowest priority):

1. `ATMOS_AUTH_REALM` environment variable
2. `auth.realm` in `atmos.yaml` configuration
3. Empty (no realm isolation)

### Credential Storage Paths

Without a realm, credentials are stored at:

```
~/.config/atmos/aws/{provider}/credentials
```

With a realm configured, credentials are stored at:

```
~/.config/atmos/{realm}/aws/{provider}/credentials
```

### Realm Naming Rules

Realm values must follow these rules:

- Only lowercase letters (`a-z`), digits (`0-9`), hyphens (`-`), and underscores (`_`)
- Maximum 64 characters
- Cannot start or end with a hyphen or underscore
- Cannot contain consecutive hyphens or underscores
- Cannot contain path traversal characters (`/`, `\`, `..`)

:::caution

Changing the realm (adding, removing, or modifying `auth.realm` or `ATMOS_AUTH_REALM`) makes
previously cached credentials inaccessible. You must run `atmos auth login` to re-authenticate
under the new realm. Atmos will warn you if it detects credentials stored under a different realm.

:::

### Checking Your Current Realm

Use `atmos auth whoami` to see the current realm and credential status:

```bash
atmos auth whoami --identity my-identity
```

## CLI Commands

Atmos provides commands for managing authentication:

```bash
# Login to default provider
atmos auth login

# Login to specific provider
atmos auth login --provider aws-sso

# Configure user credentials
atmos auth user configure

# List available identities
atmos auth list

# Switch identity
atmos auth switch prod-admin
```

## Best Practices

1. **Use SSO Over Static Credentials:** AWS SSO provides short-lived credentials and centralized access management.

2. **Define Environment-Specific Identities:** Create separate identities for dev, staging, and production with appropriate permissions.

3. **Use Role Chains for Cross-Account:** Rather than configuring SSO access to every account, use role assumption chains from a central account.

4. **Leverage System Keyring:** Use the system keyring for credential storage to benefit from OS-level security.

5. **Set Appropriate Session Durations:** Balance security and convenience when configuring session durations.

6. **Mark Default Identities:** Set `default: true` on commonly used identities to streamline workflows.

## Related

- [Authentication Providers](/cli/configuration/auth/providers) — Configure AWS, Azure, and GCP providers
- [Authentication Identities](/cli/configuration/auth/identities) — Configure identities for all cloud providers
- [Azure Authentication Tutorial](/tutorials/azure-authentication) — Complete Azure auth guide
- [Environment Variables (env)](/stacks/env)
- [Settings](/stacks/settings)
- [Terraform Providers](/stacks/providers)