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.

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: include AWS tags from permission sets as labels
      include_tags: 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.
include_tags
Optional. When true (and auto_provision_identities is enabled), Atmos retrieves AWS tags from permission sets and includes them as labels on the auto-provisioned identities. Requires additional IAM permissions. 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

Tag/Label Support (Optional)​

If you enable tag discovery (include_tags: true in provider configuration), additional permissions are required:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "sso:ListAccounts",
        "sso:ListAccountRoles"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "sso:ListInstances",
        "sso:DescribePermissionSet",
        "sso:ListPermissionSets",
        "sso:ListTagsForResource"
      ],
      "Resource": "*"
    }
  ]
}

Additional APIs Used:

  • sso:ListInstances - Finds the SSO instance ARN
  • sso:DescribePermissionSet - Gets permission set details
  • sso:ListPermissionSets - Finds permission set ARNs
  • sso:ListTagsForResource - Retrieves AWS tags from permission sets

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
      idp_arn: arn:aws:iam::123456789012:saml-provider/okta-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.
idp_arn
Required. ARN of the SAML provider in IAM.
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.

Multiple Providers​

You can configure multiple providers for different use cases:

atmos.yaml

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

    # SAML for legacy systems
    okta-saml:
      kind: aws/saml
      region: us-east-1
      url: https://company.okta.com/app/amazon_aws/abc123/sso/saml
      idp_arn: arn:aws:iam::123456789012:saml-provider/okta

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

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