# Providers

Providers are the upstream systems that Atmos uses to obtain initial credentials. Configure providers in the `auth.providers` section of your `atmos.yaml`.

> ⚠️ Experimental

### AWS

## IAM Identity Center (SSO)

The most common provider for AWS organizations using SSO.

**File:** `atmos.yaml`

```yaml
auth:
  providers:
    company-sso:
      kind: aws/iam-identity-center
      region: us-east-1
      start_url: https://company.awsapps.com/start
      spec:
        endpoint_url: "http://localhost:4566"  # Optional for Floci/LocalStack-compatible endpoints

      # Automatically discover all accounts and permission sets
      auto_provision_identities: true

      # Optional session configuration
      session:
        duration: 4h               # Credential lifetime

      console:
        session_duration: 12h      # Web console session (max 12h)
```

- **`kind`**
  **Required.**
   Must be 
  `aws/iam-identity-center`
  .
- **`region`**
  **Required.**
   AWS region for the Identity Center instance.
- **`start_url`**
  **Required.**
   Your AWS SSO start URL (e.g., 
  `https://company.awsapps.com/start`
  ).
- **`auto_provision_identities`**
  Optional. When 
  `true`
  , Atmos automatically discovers all AWS accounts and permission sets assigned to the user and creates identities for them. This eliminates the need to manually configure each identity. Default: 
  `false`
  .
- **`session.duration`**
  Optional. Session duration for CLI credentials (e.g., 
  `1h`
  , 
  `4h`
  ). Default varies by provider.
- **`console.session_duration`**
  Optional. Web console session duration. Maximum 12 hours for AWS.
- **`spec.endpoint_url`**
  Optional. AWS-compatible base endpoint URL for SDK calls, useful for Floci, LocalStack, and other test endpoints.

### IAM Permissions for Identity Provisioning

When using automatic identity provisioning (`auto_provision_identities: true`), Atmos queries AWS Identity Center APIs during login to discover available permission sets across assigned accounts. This requires specific IAM permissions.

Required IAM Permissions

#### Basic Provisioning (Required)

These permissions are required for automatic identity provisioning to work:

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "sso:ListAccounts",
        "sso:ListAccountRoles"
      ],
      "Resource": "*"
    }
  ]
}
```

**APIs Used:**

- `sso:ListAccounts` - Enumerates all AWS accounts the user can access
- `sso:ListAccountRoles` - Lists available permission sets (roles) for each account

#### How to Apply Permissions

These permissions should be attached to the IAM Identity Center permission set that users authenticate with, or to the IAM user/role if using static credentials. Without these permissions, identity provisioning will fail gracefully and fall back to manually configured identities.

## SAML

For organizations using SAML-based identity providers like Okta, Google Apps, or ADFS.

**File:** `atmos.yaml`

```yaml
auth:
  providers:
    okta-saml:
      kind: aws/saml
      region: us-east-1
      url: https://company.okta.com/app/amazon_aws/abc123/sso/saml
      driver: Browser              # Browser, GoogleApps, Okta, or ADFS
```

- **`kind`**
  **Required.**
   Must be 
  `aws/saml`
  .
- **`region`**
  **Required.**
   AWS region.
- **`url`**
  **Required.**
   SAML SSO URL from your identity provider.
- **`driver`**
  Optional. Authentication method: 
  `Browser`
   (default, requires Playwright), 
  `GoogleApps`
  , 
  `Okta`
  , or 
  `ADFS`
  .

:::note
The `aws/saml` provider requires the next identity to be of kind `aws/assume-role`, as the SAML authentication flow requires selecting a role to assume.
:::

## GitHub Actions OIDC

For CI/CD pipelines running in GitHub Actions.

**File:** `atmos.yaml`

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

- **`kind`**
  **Required.**
   Must be 
  `github/oidc`
  .
- **`region`**
  **Required.**
   AWS region for STS endpoint.
- **`spec.audience`**
  Optional. OIDC audience. Defaults to STS endpoint for the region.

:::info Credentials are never cached
`github/oidc` requests a fresh token from the GitHub Actions token endpoint on every
authentication, and Atmos never writes the resulting credentials to the keyring. A rotated
Actions token is always picked up on the next run.
:::

### Azure

## Interactive Browser

The recommended provider for human logins to Azure. Performs the same interactive browser flow as `az login` (authorization code + PKCE on a localhost redirect), so it works in tenants where Conditional Access blocks the device code flow.

**File:** `atmos.yaml`

```yaml
auth:
  providers:
    azure-interactive:
      kind: azure/interactive
      spec:
        tenant_id: "12345678-1234-1234-1234-123456789012"
        subscription_id: "87654321-4321-4321-4321-210987654321"
        location: eastus
```

- **`kind`**
  **Required.**
   Must be 
  `azure/interactive`
  .
- **`spec.tenant_id`**
  **Required.**
   Azure AD tenant ID.
- **`spec.subscription_id`**
  Optional. Default Azure subscription ID.
- **`spec.location`**
  Optional. Default Azure region (e.g., 
  `eastus`
  , 
  `westeurope`
  ).
- **`spec.client_id`**
  Optional. Azure AD application (client) ID. Defaults to Azure CLI's public client ID.
- **`spec.cloud_environment`**
  Optional. Azure cloud environment for sovereign clouds. Supported values: 
  `public`
   (default), 
  `usgovernment`
   (Azure Government / GCC High), 
  `china`
   (Azure China / Mooncake). When set, Atmos uses the correct login endpoints, API scopes, and blob storage URLs for the target cloud.

**How it works:**

1. Atmos first tries silent authentication from the persisted MSAL cache — repeat logins complete without opening a browser
2. If no cached session exists, Atmos opens your default browser for an authorization-code + PKCE sign-in (with MFA if configured)
3. Atmos acquires tokens for Azure Resource Manager, Microsoft Graph, and Azure Key Vault
4. Tokens are cached in `~/.azure/msal_token_cache.json` and `~/.azure/azureProfile.json`, so the `az` CLI and Terraform work without ever running `az login`

:::note
`azure/interactive` requires an interactive terminal and a browser. For CI/CD, use `azure/oidc`. For browser-less human sessions (e.g., SSH), use `azure/device-code` where tenant policy allows it.
:::

## Device Code

For interactive browser-based authentication to Azure, similar to `az login --use-device-code`. Useful when a browser can't be opened on the machine running Atmos (e.g., SSH sessions).

:::warning Conditional Access may block device code
Microsoft-managed Conditional Access policies now block the device code flow in many tenants (error `AADSTS530035`). If device code sign-in fails with this error, use `azure/interactive` instead.
:::

**File:** `atmos.yaml`

```yaml
auth:
  providers:
    azure-device-code:
      kind: azure/device-code
      spec:
        tenant_id: "12345678-1234-1234-1234-123456789012"
        subscription_id: "87654321-4321-4321-4321-210987654321"
        location: eastus
```

- **`kind`**
  **Required.**
   Must be 
  `azure/device-code`
  .
- **`spec.tenant_id`**
  **Required.**
   Azure AD tenant ID.
- **`spec.subscription_id`**
  Optional. Default Azure subscription ID.
- **`spec.location`**
  Optional. Default Azure region (e.g., 
  `eastus`
  , 
  `westeurope`
  ).
- **`spec.client_id`**
  Optional. Azure AD application (client) ID. Defaults to Azure CLI's public client ID.
- **`spec.cloud_environment`**
  Optional. Azure cloud environment for sovereign clouds. Supported values: 
  `public`
   (default), 
  `usgovernment`
   (Azure Government / GCC High), 
  `china`
   (Azure China / Mooncake). When set, Atmos uses the correct login endpoints, API scopes, and blob storage URLs for the target cloud.

**How it works:**

1. Atmos displays a device code and opens `https://microsoft.com/devicelogin`
2. You enter the code and sign in (with MFA if configured)
3. Atmos acquires tokens for Azure Resource Manager, Microsoft Graph, and Azure Key Vault
4. Tokens are cached in `~/.azure/msal_token_cache.json` for Terraform compatibility

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

## OIDC (Workload Identity Federation)

For CI/CD pipelines using federated identity tokens (GitHub Actions, Azure DevOps, etc.).

**File:** `atmos.yaml`

```yaml
auth:
  providers:
    azure-oidc:
      kind: azure/oidc
      spec:
        tenant_id: "12345678-1234-1234-1234-123456789012"
        client_id: "YOUR_APP_CLIENT_ID"
        subscription_id: "87654321-4321-4321-4321-210987654321"
        location: eastus
```

- **`kind`**
  **Required.**
   Must be 
  `azure/oidc`
  .
- **`spec.tenant_id`**
  **Required.**
   Azure AD tenant ID.
- **`spec.client_id`**
  **Required.**
   Azure AD application (client) ID with federated credentials configured.
- **`spec.subscription_id`**
  Optional. Default Azure subscription ID.
- **`spec.location`**
  Optional. Default Azure region.
- **`spec.audience`**
  Optional. OIDC audience for token exchange.
- **`spec.token_file_path`**
  Optional. Path to file containing the OIDC token. If not set, uses environment variables (
  `ACTIONS_ID_TOKEN_REQUEST_URL`
   in GitHub Actions).
- **`spec.cloud_environment`**
  Optional. Azure cloud environment for sovereign clouds. Supported values: 
  `public`
   (default), 
  `usgovernment`
   (Azure Government / GCC High), 
  `china`
   (Azure China / Mooncake). When set, Atmos uses the correct login endpoints, API scopes, and blob storage URLs for the target cloud.

:::info Credentials are never cached
`azure/oidc` re-reads its federated token on every authentication — from `spec.token_file_path`,
the `AZURE_FEDERATED_TOKEN_FILE` environment variable, or the GitHub Actions OIDC endpoint,
whichever applies — and Atmos never writes the resulting tokens (or credentials derived from
them) to the keyring. Rotate the token at its source and the next run picks it up.
:::

### GitHub Actions Setup

**File:** `.github/workflows/deploy.yaml`

```yaml
jobs:
  deploy:
    permissions:
      id-token: write    # Required for OIDC
      contents: read
    steps:
      - uses: actions/checkout@v6
      - name: Deploy with Atmos
        run: atmos terraform apply mycomponent -s prod
        env:
          AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
          AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
          AZURE_SUBSCRIPTION_ID: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
```

## CLI

For using existing Azure CLI credentials from `az login`.

**File:** `atmos.yaml`

```yaml
auth:
  providers:
    azure-existing:
      kind: azure/cli
      spec:
        tenant_id: "12345678-1234-1234-1234-123456789012"
        subscription_id: "87654321-4321-4321-4321-210987654321"
        location: eastus
```

- **`kind`**
  **Required.**
   Must be 
  `azure/cli`
  .
- **`spec.tenant_id`**
  **Required.**
   Azure AD tenant ID.
- **`spec.subscription_id`**
  Optional. Default Azure subscription ID.
- **`spec.location`**
  Optional. Default Azure region.
- **`spec.cloud_environment`**
  Optional. Azure cloud environment for sovereign clouds. Supported values: 
  `public`
   (default), 
  `usgovernment`
   (Azure Government / GCC High), 
  `china`
   (Azure China / Mooncake). When set, Atmos uses the correct login endpoints, API scopes, and blob storage URLs for the target cloud.

:::note
The `azure/cli` provider requires existing Azure CLI credentials. Run `az login` first.
:::

:::info Credentials are never cached
`azure/cli` re-reads your Azure CLI session on every authentication, and Atmos never writes
its tokens (or any credentials derived from them) to the keyring. Switch accounts with
`az login` and the next `atmos auth login` picks up the new principal — no `atmos auth logout`
needed.
:::

## Sovereign Clouds (GCC High, China)

Azure sovereign clouds use different authentication endpoints and API scopes than Azure Commercial (public). Set `cloud_environment` in your provider spec to target the correct cloud:

**File:** `atmos.yaml (Azure Government / GCC High)`

```
auth:
  providers:
    azure-gov:
      kind: azure/interactive
      spec:
        tenant_id: "12345678-1234-1234-1234-123456789012"
        subscription_id: "87654321-4321-4321-4321-210987654321"
        location: usgovvirginia
        cloud_environment: usgovernment
```

**File:** `atmos.yaml (Azure China / Mooncake)`

```
auth:
  providers:
    azure-china:
      kind: azure/oidc
      spec:
        tenant_id: "12345678-1234-1234-1234-123456789012"
        client_id: "YOUR_APP_CLIENT_ID"
        subscription_id: "87654321-4321-4321-4321-210987654321"
        cloud_environment: china
```

When `cloud_environment` is set, Atmos automatically adjusts:

- **Login endpoint** (e.g., `login.microsoftonline.us` for GCC High, `login.chinacloudapi.cn` for China)
- **API scopes** (Azure Resource Manager, Microsoft Graph, KeyVault)
- **Blob storage URLs** used by `!terraform.state` YAML functions
- **Portal URLs** for `atmos auth console`

| Cloud | `cloud_environment` | Login Endpoint | Blob Storage Suffix |
|-------|---------------------|----------------|---------------------|
| Commercial | `public` (default) | `login.microsoftonline.com` | `blob.core.windows.net` |
| US Government / GCC High | `usgovernment` | `login.microsoftonline.us` | `blob.core.usgovcloudapi.net` |
| China (Mooncake) | `china` | `login.chinacloudapi.cn` | `blob.core.chinacloudapi.cn` |

:::tip
Sovereign cloud support also affects the Terraform azurerm backend. Set `environment` in your backend configuration to match:

```yaml
backend:
  azurerm:
    storage_account_name: mystorageaccount
    container_name: tfstate
    key: terraform.tfstate
    environment: usgovernment  # Matches Terraform azurerm backend "environment" field
```

This ensures `!terraform.state` YAML functions use the correct blob storage endpoint.
:::

### GCP

## Application Default Credentials

For local development using existing `gcloud` authentication.

**File:** `atmos.yaml`

```yaml
auth:
  providers:
    gcp-adc:
      kind: gcp/adc
      project_id: my-gcp-project      # Optional: override default project
      region: us-central1             # Optional: default region
      scopes:                         # Optional: custom OAuth scopes
        - https://www.googleapis.com/auth/cloud-platform
```

- **`kind`**
  **Required.**
   Must be 
  `gcp/adc`
  .
- **`project_id`**
  Optional. GCP project ID. If not set, uses the project from 
  `gcloud config`
  .
- **`region`**
  Optional. Default GCP region for resources.
- **`scopes`**
  Optional. OAuth scopes for the access token. Defaults to 
  `https://www.googleapis.com/auth/cloud-platform`
  .

:::note
The `gcp/adc` provider requires existing Application Default Credentials. Run `gcloud auth application-default login` first.
:::

:::info Credentials are never cached
`gcp/adc` re-reads Application Default Credentials on every authentication, and Atmos never
writes its tokens (or any credentials derived from them) to the keyring. Switch accounts with
`gcloud auth application-default login` and the next `atmos auth login` picks up the new
principal — no `atmos auth logout` needed.
:::

## Workload Identity Federation

For CI/CD pipelines using OIDC tokens (e.g., GitHub Actions).

**In GitHub Actions, `token_source` is auto-detected** — you only need the WIF pool configuration:

**File:** `atmos.yaml`

```yaml
auth:
  providers:
    gcp-wif:
      kind: gcp/workload-identity-federation
      project_id: my-gcp-project
      project_number: "123456789012"
      workload_identity_pool_id: github-pool
      workload_identity_provider_id: github-provider
      service_account_email: ci-sa@my-project.iam.gserviceaccount.com
```

When running in GitHub Actions (detected via `ACTIONS_ID_TOKEN_REQUEST_URL`), Atmos automatically:

- Sets `token_source.type` to `url`
- Uses `ACTIONS_ID_TOKEN_REQUEST_URL` as the token endpoint
- Uses `ACTIONS_ID_TOKEN_REQUEST_TOKEN` as the bearer token
- Constructs the OIDC `audience` from `project_number`, `workload_identity_pool_id`, and `workload_identity_provider_id`
- Validates the token URL against known GitHub Actions OIDC hosts (`*.actions.githubusercontent.com`)

For non-GitHub environments, configure `token_source` explicitly:

**File:** `atmos.yaml (non-GitHub)`

```
auth:
  providers:
    gcp-wif:
      kind: gcp/workload-identity-federation
      project_number: "123456789012"
      workload_identity_pool_id: my-pool
      workload_identity_provider_id: my-provider
      token_source:
        type: url
        url: https://my-oidc-provider.example.com/token
        audience: //iam.googleapis.com/projects/123456789012/locations/global/workloadIdentityPools/my-pool/providers/my-provider
        allowed_hosts:
          - my-oidc-provider.example.com
```

- **`kind`**
  **Required.**
   Must be 
  `gcp/workload-identity-federation`
  .
- **`project_id`**
  Optional. GCP project ID for the resulting credentials.
- **`project_number`**
  **Required.**
   GCP project number (numeric) where WIF is configured.
- **`workload_identity_pool_id`**
  **Required.**
   Workload Identity Pool ID.
- **`workload_identity_provider_id`**
  **Required.**
   Workload Identity Provider ID within the pool.
- **`service_account_email`**
  Optional. Service account to impersonate after federation. If not set, uses the federated token directly.
- **`token_source`**
  Optional in GitHub Actions (auto-detected). Required for other OIDC providers.
- **`token_source.type`**
  Token source type: 
  `url`
  , 
  `file`
  , or 
  `environment`
  . Auto-detected as 
  `url`
   in GitHub Actions.
- **`token_source.environment_variable`**
  For 
  `type: environment`
  . Environment variable containing the OIDC token.
- **`token_source.file_path`**
  For 
  `type: file`
  . Path to file containing the OIDC token.
- **`token_source.url`**
  For 
  `type: url`
  . URL to fetch OIDC token. In GitHub Actions, defaults to 
  `ACTIONS_ID_TOKEN_REQUEST_URL`
  .
- **`token_source.request_token`**
  For 
  `type: url`
  . Bearer token for authenticating to the OIDC token endpoint. In GitHub Actions, defaults to 
  `ACTIONS_ID_TOKEN_REQUEST_TOKEN`
  .
- **`token_source.audience`**
  Optional. Audience for the OIDC token request. In GitHub Actions, auto-constructed from 
  `project_number`
  , 
  `workload_identity_pool_id`
  , and 
  `workload_identity_provider_id`
  .
- **`token_source.allowed_hosts`**
  For 
  `type: url`
  . Allowed hostnames for the token endpoint. Not needed in GitHub Actions (validated against known GitHub hosts automatically).
- **`scopes`**
  Optional. OAuth scopes for the access token.

:::info Credentials are never cached
Like `gcp/adc`, `gcp/workload-identity-federation` re-reads its OIDC token from whichever
`token_source` you configured — `url`, `file`, or `environment` — on every authentication, and
Atmos never writes the resulting tokens (or credentials derived from them) to the keyring.
Rotate the token at its source and the next run picks it up, with no `atmos auth logout` needed.
:::

### GitHub Actions Setup

In GitHub Actions, the only requirement is `id-token: write` permission. No `token_source` configuration is needed:

**File:** `.github/workflows/deploy.yaml`

```yaml
jobs:
  deploy:
    permissions:
      id-token: write    # Required for OIDC
      contents: read
    steps:
      - uses: actions/checkout@v6
      - name: Deploy with Atmos
        run: atmos terraform apply mycomponent -s prod
```

## Atmos Pro

The `atmos/pro` provider authenticates the Atmos CLI **to [Atmos Pro](https://atmos-pro.com)** (not to a cloud), by federating the GitHub Actions runner's OIDC token into an Atmos Pro session. It is the prerequisite for the [`github/sts` integration](/cli/configuration/auth#github-sts-atmos-pro). v1 is OIDC-only and requires a GitHub Actions environment.

**File:** `atmos.yaml`

```yaml
auth:
  providers:
    atmos-pro:
      kind: atmos/pro
      spec:
        workspace_id: <your-workspace-id>   # or ATMOS_PRO_WORKSPACE_ID
        base_url: https://atmos-pro.com     # optional; or ATMOS_PRO_BASE_URL
        audience: atmos-pro.com             # optional OIDC audience
```

- **`kind`**
  **Required.**
   Must be 
  `atmos/pro`
  .
- **`spec.workspace_id`**
  **Required.**
   Atmos Pro workspace ID. May also be supplied via 
  `ATMOS_PRO_WORKSPACE_ID`
   (set automatically in most Atmos Pro CI setups).
- **`spec.base_url`**
  Optional. Atmos Pro base URL. Defaults to 
  `https://atmos-pro.com`
  . May also be supplied via 
  `ATMOS_PRO_BASE_URL`
  .
- **`spec.audience`**
  Optional. OIDC audience for the Atmos Pro token exchange. Defaults to 
  `atmos-pro.com`
  .

Your GitHub Actions workflow only needs `permissions: id-token: write`. Pair this provider with an `atmos/pro` identity and a `github/sts` integration to mint just-in-time GitHub tokens for private module/source/vendor access.

## Multiple Providers

You can configure multiple providers for different use cases and cloud platforms:

**File:** `atmos.yaml`

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

    # AWS GitHub OIDC for CI/CD
    aws-github-oidc:
      kind: github/oidc
      region: us-east-1

    # Azure interactive browser login
    azure-dev:
      kind: azure/interactive
      spec:
        tenant_id: "12345678-1234-1234-1234-123456789012"
        subscription_id: "87654321-4321-4321-4321-210987654321"

    # Azure OIDC for CI/CD
    azure-ci:
      kind: azure/oidc
      spec:
        tenant_id: "12345678-1234-1234-1234-123456789012"
        client_id: "YOUR_APP_CLIENT_ID"
        subscription_id: "87654321-4321-4321-4321-210987654321"

    # GCP local development
    gcp-adc:
      kind: gcp/adc

    # GCP GitHub Actions (token_source auto-detected)
    gcp-wif:
      kind: gcp/workload-identity-federation
      project_number: "123456789012"
      workload_identity_pool_id: github-pool
      workload_identity_provider_id: github-provider
```

Each provider can be referenced by name in identity configurations using the `via.provider` field.

## Using Profiles for Different Environments

Use [Atmos profiles](/cli/configuration/profiles) to swap provider implementations while keeping the same provider name. This allows your identities to reference a single provider (e.g., `acme-corp`) that behaves differently depending on the active profile:

- **Developers** authenticate via SSO in their browser
- **CI/CD pipelines** authenticate via GitHub OIDC tokens
- **Platform engineers** use SSO with extended session durations

Because the provider name stays consistent, your identity configurations work unchanged across all environments.

Create a directory for each profile:

```
profiles/
├── dev/
│   └── auth.yaml
├── ci/
│   └── auth.yaml
└── platform/
    └── auth.yaml
```

### profiles/dev/auth.yaml

```yaml
# Profile for local development (SSO)
auth:
  providers:
    acme-corp:
      kind: aws/iam-identity-center
      region: us-east-1
      start_url: https://acme.awsapps.com/start
```

### profiles/ci/auth.yaml

```yaml
# Profile for CI/CD pipelines (OIDC)
auth:
  providers:
    acme-corp:
      kind: github/oidc
      region: us-east-1
```

### profiles/platform/auth.yaml

```yaml
# Profile for platform engineers (SSO with extended sessions)
auth:
  providers:
    acme-corp:
      kind: aws/iam-identity-center
      region: us-east-1
      start_url: https://acme.awsapps.com/start
      session:
        duration: 8h
```

Activate a profile with `--profile` or the `ATMOS_PROFILE` environment variable:

```bash
# Use the CI profile in GitHub Actions
ATMOS_PROFILE=ci atmos terraform apply myapp -s prod

# Use the platform profile for extended sessions
atmos --profile platform auth login
```

## Related Commands

## Tutorials

- [Azure Authentication](/tutorials/azure-authentication) — Complete guide for Azure interactive browser, device code, OIDC, and CLI authentication

## See Also

- [Identities](/cli/configuration/auth/identities) — Configure identities that use these providers
- [Profiles](/cli/configuration/profiles) — Environment-specific configuration overrides