Skip to main content

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

IAM Identity Center (SSO)​

The most common provider for AWS organizations using SSO.

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

{
  "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.

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

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

Atmos Pro​

The atmos/pro provider authenticates the Atmos CLI to Atmos Pro (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. v1 is OIDC-only and requires a GitHub Actions environment.

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

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

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

# 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

Tutorials​

See Also​

  • Identities — Configure identities that use these providers
  • Profiles — Environment-specific configuration overrides