# Atmos Auth > Authentication and identity management: providers (SSO/SAML/OIDC/GCP/Atmos Pro), identities, keyring, identity chaining, login/exec/shell/console, and github/sts for private GitHub access - Skill: `cloudposse/atmos-auth` (Agent Skill, multi-file: 5 files) - Install (CLI): `npx skillmds@latest add cloudposse/atmos-auth` - Raw SKILL.md: https://api.skillmd.com/api/skills/cloudposse/atmos-auth/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: cloudposse (https://skillmd.com/u/cloudposse) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/cloudposse/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, ACR, AKS, 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/ACR Docker login, EKS/AKS kubeconfig, GitHub STS). ```yaml auth: logs: level: Info # Debug, Info, Warn, Error file: /path/to/auth.log # Optional log file keyring: type: system # system, file, or memory providers: : kind: # Provider-specific fields identities: : kind: # Identity-specific fields integrations: : kind: aws/ecr # Integration-specific fields ``` ## Related Skills | Need | Load | |---|---| | Atmos Pro setup, uploads, workflow dispatch, drift detection | [atmos-pro](../atmos-pro/SKILL.md) | | Private GitHub remote imports and component source | [atmos-imports](../atmos-imports/SKILL.md) | | Native CI using OIDC | [atmos-ci](../atmos-ci/SKILL.md) | | GitOps repositories and signed commits | [atmos-git](../atmos-git/SKILL.md) | ## Provider Types ### AWS IAM Identity Center (SSO) The most common provider for AWS organizations. Requires `kind`, `region`, and `start_url`. ```yaml 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`. ```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 ``` ### 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`. ```yaml 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. ```yaml 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`. ```yaml 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. ```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 ``` 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). ```yaml 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. ```yaml 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. ```yaml 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. ```yaml 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. ```yaml 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. ```yaml 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`. ```yaml 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. ```yaml 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 | Type | Persistence | Security | Use Case | |------|-------------|----------|----------| | `system` | Yes | High (OS-managed) | Interactive workstations (Keychain, GNOME Keyring, Windows Credential Manager) | | `file` | Yes | Medium (AES-256 encrypted) | Headless servers, Docker containers, CI/CD | | `memory` | No | Low (in-process) | Testing, temporary sessions | File keyring password resolution: `ATMOS_KEYRING_PASSWORD` env var, then interactive prompt, then error. ## Commands Quick Reference | Command | Purpose | |---------|---------| | `atmos auth login [--identity ]` | Authenticate with SSO/SAML/OIDC/static credentials | | `atmos auth whoami [--identity ]` | Show current authentication status | | `atmos auth validate [--verbose]` | Validate auth configuration for syntax and logic errors | | `atmos auth shell [--identity ]` | Launch interactive shell with credentials pre-configured | | `atmos auth exec [--identity ] -- ` | Execute a single command with identity credentials | | `atmos auth env [--format bash\|json\|dotenv]` | Export credentials as environment variables | | `atmos auth console [--destination ]` | Open cloud provider web console in browser | | `atmos auth list [--format table\|tree\|json\|yaml\|graphviz\|mermaid]` | List providers and identities | | `atmos auth ecr-login [integration]` | Login to AWS ECR registries | | `atmos auth logout [identity] [--all] [--provider]` | Clear cached credentials | 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: ```bash atmos terraform plan mycomponent --stack=dev --identity=false ``` Or: ```bash export ATMOS_IDENTITY=false ``` Recognized disable values: `false`, `0`, `no`, `off` (case-insensitive). ## CI/CD Integration ### GitHub Actions with OIDC ```yaml 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: ```yaml 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-profiles/SKILL.md): ```bash 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/ACR and EKS/AKS Integrations Registry login (`aws/ecr`, `azure/acr`) and kubeconfig provisioning (`aws/eks`, `azure/aks`) auto-trigger on identity login when `auto_provision: true` (default). `spec.registry` and `spec.cluster` are single structs shared across both clouds — each integration's `kind` picks which fields matter (see the per-cloud references below): ```yaml auth: integrations: dev/ecr: { kind: aws/ecr, via: { identity: dev-admin }, spec: { registry: { account_id: "123456789012", region: us-east-2 } } } dev/acr: { kind: azure/acr, via: { identity: azure-dev }, spec: { registry: { name: myregistry } } } dev/eks: { kind: aws/eks, via: { identity: dev-admin }, spec: { cluster: { name: dev-cluster, region: us-east-2 } } } dev/aks: { kind: azure/aks, via: { identity: azure-dev }, spec: { cluster: { name: dev-cluster, resource_group: dev-rg } } } ``` Integration failures are non-blocking during `atmos auth login`; retry the per-integration login/update command. Command details — AWS: [atmos-aws-ecr](../atmos-aws-ecr/SKILL.md), [atmos-aws-eks](../atmos-aws-eks/SKILL.md); Azure: [references/azure-acr-integration.md](references/azure-acr-integration.md), [references/azure-aks-integration.md](references/azure-aks-integration.md). ## 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. ```yaml 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 | Variable | Purpose | |----------|---------| | `ATMOS_IDENTITY` | Default identity name, or `false` to disable auth | | `ATMOS_KEYRING_TYPE` | Override keyring backend (`system`, `file`, `memory`) | | `ATMOS_KEYRING_PASSWORD` | Password for file keyring | | `ATMOS_XDG_CONFIG_HOME` | Override config directory for AWS files | | `ATMOS_XDG_DATA_HOME` | Override data directory for file keyring | | `ATMOS_PRO_WORKSPACE_ID` | Atmos Pro workspace ID for `atmos/pro` | | `ATMOS_PRO_BASE_URL` | Override Atmos Pro base URL | | `ATMOS_PRO_GITHUB_TOKEN` | Preferred token for Atmos-native Git reads minted by `github/sts` | ## 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](references/providers-and-identities.md) -- Detailed provider and identity configuration patterns - [references/commands-reference.md](references/commands-reference.md) -- Complete command reference for all auth subcommands - [references/azure-aks-integration.md](references/azure-aks-integration.md) -- `azure/aks` integration: `atmos azure aks update-kubeconfig` / `token` (kubeconfig without `az`/`kubelogin`) - [references/azure-acr-integration.md](references/azure-acr-integration.md) -- `azure/acr` integration: `atmos azure acr login` (Docker login without `az`)