# 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

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

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

### Azure

## Device Code

For interactive browser-based authentication to Azure, similar to `az login --use-device-code`.

**File:** `atmos.yaml`

```yaml
auth:
  providers:
    azure-interactive:
      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.

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

## 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/device-code
      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.
:::

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

### 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 login
    azure-dev:
      kind: azure/device-code
      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 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