# Identities

Identities represent the user accounts or roles available from provider credentials. Configure identities in the `auth.identities` section of your `atmos.yaml`.

### AWS

## Permission Set

For AWS SSO permission sets.

**File:** `atmos.yaml`

```yaml
auth:
  identities:
    dev-admin:
      kind: aws/permission-set
      default: true
      via:
        provider: company-sso
      principal:
        name: AdminAccess
        account:
          name: development        # Account name (resolved via SSO)
          # OR use account ID directly:
          # id: "123456789012"
```

- **`kind`**
  **Required.**
   Must be 
  `aws/permission-set`
  .
- **`default`**
  Optional. If 
  `true`
  , this identity is used when no identity is specified.
- **`via.provider`**
  **Required.**
   Name of the provider to use for authentication.
- **`principal.name`**
  **Required.**
   Name of the permission set.
- **`principal.account.name`**
  Account name/alias (resolved via SSO ListAccounts API).
- **`principal.account.id`**
  Numeric account ID (used directly, no lookup required).

## Assume Role

For assuming IAM roles, either directly from a provider or chained from another identity.

**File:** `atmos.yaml`

```yaml
auth:
  identities:
    prod-admin:
      kind: aws/assume-role
      via:
        identity: base-admin       # Chain through another identity
        # OR directly from provider:
        # provider: okta-saml
      principal:
        assume_role: arn:aws:iam::999999999999:role/ProductionAdmin
        session_name: atmos-prod   # Optional
```

- **`kind`**
  **Required.**
   Must be 
  `aws/assume-role`
  .
- **`via.identity`**
  Name of another identity to chain from (mutually exclusive with 
  `via.provider`
  ).
- **`via.provider`**
  Name of a provider to use directly (mutually exclusive with 
  `via.identity`
  ).
- **`principal.assume_role`**
  **Required.**
   ARN of the IAM role to assume.
- **`principal.session_name`**
  Optional. Session name for CloudTrail auditing.

## Assume Root (Organizations)

For centralized root access in AWS Organizations using sts:AssumeRoot. This allows privileged operations on member accounts without enabling root user credentials.

**File:** `atmos.yaml`

```yaml
auth:
  identities:
    root-audit:
      kind: aws/assume-root
      via:
        identity: admin-base        # Chain through an existing identity
      principal:
        target_principal: "123456789012"           # 12-digit member account ID
        task_policy_arn: arn:aws:iam::aws:policy/root-task/IAMAuditRootUserCredentials
        duration: 15m                              # Optional (max 15m for AssumeRoot)
```

- **`kind`**
  **Required.**
   Must be 
  `aws/assume-root`
  .
- **`via.identity`**
  **Required.**
   Name of another identity to chain from (must provide AWS credentials).
- **`principal.target_principal`**
  **Required.**
   12-digit AWS account ID of the member account to assume root on.
- **`principal.task_policy_arn`**
  **Required.**
   AWS-managed root task policy ARN. See supported policies below.
- **`principal.duration`**
  Optional. Session duration (max 15 minutes for AssumeRoot).

**Supported task policies:**

- `arn:aws:iam::aws:policy/root-task/IAMAuditRootUserCredentials`
- `arn:aws:iam::aws:policy/root-task/IAMCreateRootUserPassword`
- `arn:aws:iam::aws:policy/root-task/IAMDeleteRootUserCredentials`
- `arn:aws:iam::aws:policy/root-task/S3UnlockBucketPolicy`
- `arn:aws:iam::aws:policy/root-task/SQSUnlockQueuePolicy`

:::note
AssumeRoot requires AWS Organizations with centralized root access enabled and appropriate permissions on the base identity.
:::

## User (Break-glass)

For static IAM user credentials, typically used for emergency access.

**File:** `atmos.yaml`

```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
        mfa_arn: arn:aws:iam::123456789012:mfa/username  # Optional
```

- **`kind`**
  **Required.**
   Must be 
  `aws/user`
  .
- **`credentials.access_key_id`**
  AWS access key ID. Use 
  `!env`
   to reference environment variables.
- **`credentials.secret_access_key`**
  AWS secret access key. Use 
  `!env`
   to reference environment variables.
- **`credentials.region`**
  AWS region for API calls.
- **`credentials.mfa_arn`**
  Optional. MFA device ARN. When set, Atmos prompts for TOTP code during authentication.
- **`credentials.webflow_enabled`**
  Optional. Defaults to 
  `true`
  . Set to 
  `false`
   to disable browser-based authentication fallback.

:::tip
Instead of storing credentials in configuration, use `atmos auth user configure` to store them securely in the system keyring.
:::

### Browser-Based Authentication (Automatic Fallback)

When neither configuration nor keyring entries provide credentials, Atmos automatically initiates an OAuth2 PKCE flow via the AWS sign-in service. This provides the same convenient web-based authentication that SSO users already enjoy, without requiring static access keys.

**Authentication priority:**

1. Static credentials from `atmos.yaml` (`access_key_id` + `secret_access_key`, including `!env` references)
2. Credentials stored in the system keyring (via `atmos auth user configure`)
3. Browser-based OAuth2 PKCE flow (when `webflow_enabled` is `true`, which is the default)

Atmos does **not** consult ambient AWS credentials (environment variables, `~/.aws/credentials`, instance profiles) for `aws/user` identities — credentials must be supplied through one of the three sources above.

If the keyring is reachable but the stored entry is unreadable (corrupted, missing fields, permission denied), Atmos reports the keyring read failure directly instead of silently falling back to the browser flow. This makes it possible to diagnose keyring issues rather than guessing why the browser flow opened.

**How it works:**

1. Atmos starts a local callback server on an ephemeral port
2. Opens your default browser to the AWS sign-in authorization endpoint
3. Exchanges the authorization code for temporary credentials using PKCE
4. Caches a refresh token for 12-hour session reuse

Subsequent authentications within the 12-hour window reuse the cached refresh token, avoiding repeated browser prompts. Credentials refresh automatically every 15 minutes.

In non-interactive environments (CI/CD), Atmos displays a URL that can be opened manually.

**Disabling browser authentication:**

**File:** `atmos.yaml`

```yaml
auth:
  identities:
    my-user:
      kind: aws/user
      credentials:
        webflow_enabled: false  # Disable browser-based auth fallback
```

### Azure

## Subscription

For targeting a specific Azure subscription using credentials from an Azure provider.

**File:** `atmos.yaml`

```yaml
auth:
  identities:
    dev-subscription:
      kind: azure/subscription
      via:
        provider: azure-cli          # Reference to an Azure provider
      principal:
        subscription_id: "12345678-1234-1234-1234-123456789012"
        location: eastus             # Optional: default location
        resource_group: my-rg        # Optional: default resource group
```

- **`kind`**
  **Required.**
   Must be 
  `azure/subscription`
  .
- **`via.provider`**
  **Required.**
   Name of an Azure provider to obtain credentials from.
- **`principal.subscription_id`**
  **Required.**
   Azure subscription ID to target.
- **`principal.location`**
  Optional. Default Azure region for resources.
- **`principal.resource_group`**
  Optional. Default resource group for resources.

The Azure subscription identity inherits credentials from the provider and sets subscription-specific environment variables (`AZURE_SUBSCRIPTION_ID`, `ARM_SUBSCRIPTION_ID`, etc.) for Terraform and other Azure tools.

:::tip
For a detailed walkthrough with examples, see the [Azure Authentication Tutorial](/tutorials/azure-authentication).
:::

### GCP

## Service Account

For impersonating a GCP service account using credentials from a GCP provider.

**File:** `atmos.yaml`

```yaml
auth:
  identities:
    terraform:
      kind: gcp/service-account
      default: true
      via:
        provider: gcp-adc             # Or gcp-wif for CI/CD
      principal:
        service_account_email: terraform@my-project.iam.gserviceaccount.com
        project_id: my-project        # Optional: override project
        scopes:                       # Optional: custom scopes
          - https://www.googleapis.com/auth/cloud-platform
        lifetime: 3600s               # Optional: token lifetime (default 1h)
```

- **`kind`**
  **Required.**
   Must be 
  `gcp/service-account`
  .
- **`via.provider`**
  **Required.**
   Name of a GCP provider (
  `gcp/adc`
   or 
  `gcp/workload-identity-federation`
  ).
- **`principal.service_account_email`**
  **Required.**
   Email of the service account to impersonate.
- **`principal.project_id`**
  Optional. GCP project ID. If not set, extracted from service account email.
- **`principal.scopes`**
  Optional. OAuth scopes for the impersonated token. Defaults to 
  `https://www.googleapis.com/auth/cloud-platform`
  .
- **`principal.lifetime`**
  Optional. Token lifetime (e.g., 
  `3600s`
  , 
  `1h`
  ). Default is 1 hour, maximum is 12 hours.
- **`principal.delegates`**
  Optional. Chain of service accounts for multi-hop impersonation.

The service account identity uses the IAM Credentials API to generate access tokens. Requires the base identity to have `roles/iam.serviceAccountTokenCreator` on the target service account.

## Project

For setting GCP project context without authentication. Useful for targeting a specific project when credentials come from a provider or parent identity.

**File:** `atmos.yaml`

```yaml
auth:
  identities:
    prod-project:
      kind: gcp/project
      via:
        provider: gcp-adc
      principal:
        project_id: production-project
        region: us-central1           # Optional: default region
        zone: us-central1-a           # Optional: default zone
```

- **`kind`**
  **Required.**
   Must be 
  `gcp/project`
  .
- **`via.provider`**
  Optional. Name of a GCP provider to obtain credentials from.
- **`principal.project_id`**
  **Required.**
   GCP project ID to target.
- **`principal.region`**
  Optional. Default GCP region for resources.
- **`principal.zone`**
  Optional. Default GCP zone for resources.

The project identity sets environment variables (`GOOGLE_CLOUD_PROJECT`, `CLOUDSDK_CORE_PROJECT`, `GOOGLE_CLOUD_REGION`, etc.) for Terraform and gcloud tools.

## Atmos Pro

The `atmos/pro` identity is a passthrough over the [`atmos/pro` provider](/cli/configuration/auth/providers#atmos-pro): it forwards the provider's Atmos Pro session so linked integrations (e.g. [`github/sts`](/cli/configuration/auth#github-sts-atmos-pro)) can use it. It requires `via.provider`.

**File:** `atmos.yaml`

```yaml
auth:
  identities:
    atmos-pro:
      kind: atmos/pro
      via:
        provider: atmos-pro
```

- **`kind`**
  **Required.**
   Must be 
  `atmos/pro`
  .
- **`via.provider`**
  **Required.**
   Name of the 
  `atmos/pro`
   provider this identity authenticates through.

You authenticate and run as this identity (`atmos auth login --identity atmos-pro`). The `github/sts` integration can reference it via `via.identity`, or bind to the provider directly via `via.provider`.

## Identity Chaining

Identity chaining allows you to create complex authentication flows where one identity is used to obtain another.

**File:** `atmos.yaml`

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

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

    # Further chain for specific access
    prod-readonly:
      kind: aws/assume-role
      via:
        identity: prod-admin       # Chain through prod-admin
      principal:
        assume_role: arn:aws:iam::999999999999:role/ReadOnlyAccess
```

**Chain Rules:**

- Chains can be arbitrarily deep: `provider → identity → identity → ... → identity`
- `via.provider` and `via.identity` are mutually exclusive
- `aws/user` identities don't require a `via` field
- Circular dependencies are detected and rejected

## Session Configuration

Configure session durations at the identity level to override provider defaults.

**File:** `atmos.yaml`

```yaml
auth:
  identities:
    high-security:
      kind: aws/user
      session:
        duration: 1h              # Override for this identity
      credentials:
        region: us-east-1
        mfa_arn: arn:aws:iam::123456789012:mfa/emergency
```

**IAM user limits:** 15m-12h (no MFA) or 15m-36h (with MFA)

## Component-Level Overrides

Override authentication settings for specific components in your stack configuration.

**File:** `stacks/catalog/myapp.yaml`

```yaml
components:
  terraform:
    myapp:
      auth:
        identities:
          custom-role:
            kind: aws/assume-role
            via:
              provider: company-sso
            principal:
              assume_role: arn:aws:iam::123456789012:role/MyAppRole
```

Component auth configuration is deep-merged with global auth. Component identities override global identities with the same name.

For components that need multiple identities authenticated simultaneously, see [Required](/cli/configuration/auth/required).

## Default Identity

Mark one identity as the default to use when no identity is explicitly specified:

**File:** `atmos.yaml`

```yaml
auth:
  identities:
    dev-admin:
      kind: aws/permission-set
      default: true              # This identity is used by default
      via:
        provider: company-sso
      principal:
        name: AdminAccess
        account:
          name: development

    prod-admin:
      kind: aws/assume-role
      via:
        identity: dev-admin
      principal:
        assume_role: arn:aws:iam::999999999999:role/ProductionAdmin
```

Only one identity should be marked as default. If multiple identities have `default: true`, the behavior is undefined.

## Using Profiles for Role-Based Access

Use [Atmos profiles](/cli/configuration/profiles) to define different identity configurations for various team roles. Each profile is a **directory** containing YAML configuration files.

**Profile structure:**

```
profiles/
├── developer/
│   └── auth.yaml      # Developer identity config
├── platform/
│   └── auth.yaml      # Platform engineer identity config
└── ci/
    └── auth.yaml      # CI/CD identity config
```

**File:** `profiles/developer/auth.yaml`

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

**File:** `profiles/platform/auth.yaml`

```yaml
# Profile for DevOps/Platform engineers - cross-account access
auth:
  identities:
    platform-admin:
      kind: aws/permission-set
      default: true
      via:
        provider: company-sso
      principal:
        name: AdminAccess
        account:
          name: core-identity

    prod-deploy:
      kind: aws/assume-role
      via:
        identity: platform-admin
      principal:
        assume_role: arn:aws:iam::999999999999:role/ProductionDeploy
```

**File:** `profiles/ci/auth.yaml`

```yaml
# Profile for CI/CD pipelines
auth:
  identities:
    github-deploy:
      kind: aws/assume-role
      default: true
      via:
        provider: github-oidc
      principal:
        assume_role: arn:aws:iam::123456789012:role/GitHubActionsRole
```

Activate a profile based on your role:

```bash
# Developers use the developer profile
atmos --profile developer terraform plan myapp -s dev

# Platform engineers use the platform profile
atmos --profile platform terraform apply myapp -s prod --identity prod-deploy

# CI/CD uses the ci profile
ATMOS_PROFILE=ci atmos terraform apply myapp -s prod
```

## Related Commands

## See Also

- [Providers](/cli/configuration/auth/providers) — Configure the providers that identities use
- [Keyring](/cli/configuration/auth/keyring) — Configure credential storage for IAM users
- [Profiles](/cli/configuration/profiles) — Environment-specific configuration overrides