atmos-auth

Atmos Authentication and Identity Management

Atmos Auth provides a unified authentication layer for multiple cloud providers. It consolidates AWS SSO, SAML, OIDC, GitHub Actions, GCP Workload Identity Federation, Azure, Atmos Pro, and static credentials into a single configuration model in atmos.yaml. Credentials are managed through providers (upstream authentication systems) and identities (the roles and accounts obtained from those providers), with support for identity chaining, keyring-based credential storage, and integrations like ECR, EKS, and GitHub STS.

Architecture Overview

The auth system has four layers configured under the auth: key in atmos.yaml:

1. Providers -- Upstream systems that issue initial credentials (SSO, SAML, OIDC, GCP ADC/WIF).
2. Identities -- Roles, permission sets, or accounts obtained from providers or chained from other identities.
3. Keyring -- Secure credential storage backend (system keyring, encrypted file, or in-memory).
4. Integrations -- Client-side credential materializations (ECR Docker login, EKS kubeconfig, GitHub STS).

auth:
  logs:
    level: Info                    # Debug, Info, Warn, Error
    file: /path/to/auth.log       # Optional log file
  keyring:
    type: system                   # system, file, or memory
  providers:
    <name>:
      kind: <provider-kind>
      # Provider-specific fields
  identities:
    <name>:
      kind: <identity-kind>
      # Identity-specific fields
  integrations:
    <name>:
      kind: aws/ecr
      # Integration-specific fields

Related Skills

Provider Types

AWS IAM Identity Center (SSO)

The most common provider for AWS organizations. Requires kind, region, and start_url.

auth:
  providers:
    company-sso:
      kind: aws/iam-identity-center
      region: us-east-1
      start_url: https://company.awsapps.com/start
      auto_provision_identities: true   # Auto-discover accounts and permission sets
      session:
        duration: 4h
      console:
        session_duration: 12h           # Web console session (max 12h)

When auto_provision_identities: true, Atmos queries sso:ListAccounts and sso:ListAccountRoles during login to automatically create identities for all assigned permission sets.

AWS SAML

For SAML-based IdPs (Okta, Google Apps, ADFS). The next identity in the chain must be aws/assume-role.

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

GitHub Actions OIDC

For CI/CD pipelines in GitHub Actions. Requires id-token: write permission in the workflow. Use this through a CI profile selected with ATMOS_PROFILE.

auth:
  providers:
    github-oidc:
      kind: github/oidc
      region: us-east-1
      spec:
        audience: sts.us-east-1.amazonaws.com   # Optional, defaults to STS endpoint

The cloud IAM trust policy must constrain GitHub OIDC sub claims to the intended repository and branch or GitHub environment, for example repo:ORG/REPO:ref:refs/heads/main or repo:ORG/REPO:environment:prod.

Atmos Pro Provider

Use kind: atmos/pro when the Atmos CLI needs to authenticate to Atmos Pro, including github/sts token minting.

auth:
  providers:
    atmos-pro:
      kind: atmos/pro
      spec:
        workspace_id: !env ATMOS_PRO_WORKSPACE_ID
  identities:
    atmos-pro:
      kind: atmos/pro
      via:
        provider: atmos-pro

In GitHub Actions, this uses the runner OIDC token. Grant permissions.id-token: write.

GCP Application Default Credentials

For local development using existing gcloud authentication. Requires gcloud auth application-default login.

auth:
  providers:
    gcp-adc:
      kind: gcp/adc
      project_id: my-gcp-project        # Optional, defaults to gcloud config
      region: us-central1               # Optional
      scopes:
        - https://www.googleapis.com/auth/cloud-platform

GCP Workload Identity Federation

For CI/CD using OIDC tokens. In GitHub Actions, token_source is auto-detected from environment variables.

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

For non-GitHub environments, configure token_source explicitly with type (url, file, or environment), the source location, audience, and allowed_hosts.

Identity Types

AWS Permission Set

Maps to an SSO permission set on a specific account. Use principal.account.name (resolved via SSO) or principal.account.id (direct).

auth:
  identities:
    dev-admin:
      kind: aws/permission-set
      default: true
      via:
        provider: company-sso
      principal:
        name: AdminAccess
        account:
          name: development

AWS Assume Role

Assumes an IAM role, either directly from a provider or chained from another identity.

auth:
  identities:
    prod-admin:
      kind: aws/assume-role
      via:
        identity: base-admin       # Chain from another identity
      principal:
        assume_role: arn:aws:iam::999999999999:role/ProductionAdmin
        session_name: atmos-prod   # Optional, for CloudTrail auditing

AWS Assume Root

Centralized root access in AWS Organizations using sts:AssumeRoot. Limited to 15-minute sessions.

auth:
  identities:
    root-audit:
      kind: aws/assume-root
      via:
        identity: admin-base
      principal:
        target_principal: "123456789012"
        task_policy_arn: arn:aws:iam::aws:policy/root-task/IAMAuditRootUserCredentials
        duration: 15m

Supported task policies: IAMAuditRootUserCredentials, IAMCreateRootUserPassword, IAMDeleteRootUserCredentials, S3UnlockBucketPolicy, SQSUnlockQueuePolicy.

AWS User (Break-glass)

Static IAM user credentials for emergency access. Use !env to reference environment variables.

auth:
  identities:
    emergency:
      kind: aws/user
      credentials:
        access_key_id: !env EMERGENCY_AWS_ACCESS_KEY_ID
        secret_access_key: !env EMERGENCY_AWS_SECRET_ACCESS_KEY
        region: us-east-1
        mfa_arn: arn:aws:iam::123456789012:mfa/username   # Optional MFA

Azure Subscription

Targets a specific Azure subscription. Sets AZURE_SUBSCRIPTION_ID, ARM_SUBSCRIPTION_ID, etc.

auth:
  identities:
    dev-subscription:
      kind: azure/subscription
      via:
        provider: azure-cli
      principal:
        subscription_id: "12345678-1234-1234-1234-123456789012"
        location: eastus
        resource_group: my-rg

GCP Service Account

Impersonates a GCP service account. Requires roles/iam.serviceAccountTokenCreator on the base identity.

auth:
  identities:
    terraform:
      kind: gcp/service-account
      default: true
      via:
        provider: gcp-adc
      principal:
        service_account_email: terraform@my-project.iam.gserviceaccount.com
        project_id: my-project
        lifetime: 3600s

GCP Project

Sets GCP project context. Sets GOOGLE_CLOUD_PROJECT, CLOUDSDK_CORE_PROJECT, GOOGLE_CLOUD_REGION.

auth:
  identities:
    prod-project:
      kind: gcp/project
      via:
        provider: gcp-adc
      principal:
        project_id: production-project
        region: us-central1
        zone: us-central1-a

Identity Chaining

Chains can be arbitrarily deep: provider -> identity -> identity -> ... -> identity. Use via.provider to start from a provider or via.identity to chain from another identity. They are mutually exclusive. Circular dependencies are detected and rejected.

auth:
  identities:
    base-admin:
      kind: aws/permission-set
      via:
        provider: company-sso
      principal:
        name: AdminAccess
        account:
          name: core-identity
    prod-admin:
      kind: aws/assume-role
      via:
        identity: base-admin
      principal:
        assume_role: arn:aws:iam::999999999999:role/ProductionAdmin
    prod-readonly:
      kind: aws/assume-role
      via:
        identity: prod-admin
      principal:
        assume_role: arn:aws:iam::999999999999:role/ReadOnlyAccess

Keyring Backends

File keyring password resolution: ATMOS_KEYRING_PASSWORD env var, then interactive prompt, then error.

Commands Quick Reference

All commands accepting --identity support three modes: with value (use that identity), without value (interactive selector), or omitted (use default or prompt). The -i alias works for all.

Disabling Authentication

Disable Atmos-managed auth to use native cloud provider credentials:

atmos terraform plan mycomponent --stack=dev --identity=false

Or:

export ATMOS_IDENTITY=false

Recognized disable values: false, 0, no, off (case-insensitive).

CI/CD Integration

GitHub Actions with OIDC

jobs:
  deploy:
    permissions:
      id-token: write
      contents: read
    env:
      ATMOS_PROFILE: github
    steps:
      - uses: actions/checkout@v6
      - run: atmos terraform deploy mycomponent -s prod

For AWS OIDC, configure github/oidc provider with aws/assume-role identity. For GCP WIF, configure gcp/workload-identity-federation provider -- token_source is auto-detected in GitHub Actions. Do not add a routine atmos auth login step to non-interactive OIDC workflows; Atmos exchanges the OIDC token when the command runs.

Disabling Auth in CI

When the CI platform provides credentials natively:

env:
  ATMOS_IDENTITY: false
run: atmos terraform apply mycomponent --stack=prod

Profiles for Environment Switching

Use Atmos profiles to swap provider and identity configurations while keeping names consistent. For profile directory layout, activation, and merge behavior, load atmos-profiles:

atmos --profile developer terraform plan myapp -s dev
ATMOS_PROFILE=ci atmos terraform apply myapp -s prod

Keep this skill focused on the auth sections inside a profile, such as providers, identities, and keyring settings.

ECR Integrations

ECR integrations auto-trigger on identity login when auto_provision: true (default):

auth:
  integrations:
    dev/ecr:
      kind: aws/ecr
      via:
        identity: dev-admin
      spec:
        auto_provision: true
        registry:
          account_id: "123456789012"
          region: us-east-2

Integration failures are non-blocking during atmos auth login. Use atmos auth ecr-login to retry.

GitHub STS Integration

Use kind: github/sts to mint short-lived, least-privilege GitHub App tokens through Atmos Pro. This is the preferred CI path for private GitHub vendoring, component source:, remote import:, Terraform private modules, atmos git, and other Git subprocesses.

auth:
  providers:
    atmos-pro:
      kind: atmos/pro
      spec:
        workspace_id: !env ATMOS_PRO_WORKSPACE_ID
  identities:
    atmos-pro:
      kind: atmos/pro
      via:
        provider: atmos-pro
  integrations:
    github-sts:
      kind: github/sts
      via:
        provider: atmos-pro
      spec:
        auto_provision: true
        repos: [acme/modules]
        policy_name: default
        git_config_mode: env
        revoke_on_exit: true
        token_env: ATMOS_PRO_GITHUB_TOKEN

In CI, github/sts can auto-provision lazily before the first private remote read when atmos/pro plus github/sts are configured and auto_provision is not disabled. The same minted credentials cover atmos vendor pull, remote import:, component source:, private Terraform module fetches, and managed Git operations. ATMOS_PRO_GITHUB_TOKEN is preferred for Atmos-native Git reads ahead of ATMOS_GITHUB_TOKEN and GITHUB_TOKEN.

Environment Variables

Security Best Practices

• Never commit credentials to version control. Use !env VAR_NAME for sensitive values.
• Use shortest practical session durations for high-security environments.
• Validate configurations regularly with atmos auth validate.
• Use identity chaining with least-privilege roles rather than broad permissions.
• Logout when switching contexts or ending sessions: atmos auth logout.
• Browser sessions with IdPs remain active after local logout -- sign out from the IdP separately.

Additional Resources

• references/providers-and-identities.md -- Detailed provider and identity configuration patterns
• references/commands-reference.md -- Complete command reference for all auth subcommands