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

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

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

GCP Application Default Credentials​

For local development using existing gcloud authentication.

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

GCP Workload Identity Federation​

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

atmos.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
      token_source:
        type: url                     # GitHub Actions OIDC
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.type
Required. Token source type: url (GitHub Actions), file, or environment.
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. Defaults to GitHub Actions OIDC endpoint.
token_source.request_token
For type: url. Bearer token for authenticating to the OIDC token endpoint. For GitHub Actions, this is automatically populated from ACTIONS_ID_TOKEN_REQUEST_TOKEN. Required for non-GitHub OIDC providers.
token_source.audience
Optional. Audience for the OIDC token request.
scopes
Optional. OAuth scopes for the access token.

GitHub Actions Setup​

For GitHub Actions, use type: url which automatically uses the ACTIONS_ID_TOKEN_REQUEST_URL and ACTIONS_ID_TOKEN_REQUEST_TOKEN environment variables:

.github/workflows/deploy.yaml

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

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

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

    # GCP GitHub Actions
    gcp-wif:
      kind: gcp/workload-identity-federation
      project_number: "123456789012"
      workload_identity_pool_id: github-pool
      workload_identity_provider_id: github-provider
      token_source:
        type: url

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

See Also​

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