Skip to main content

Authentication

The auth section of the atmos.yaml configures how Atmos authenticates with cloud providers. It supports AWS SSO, SAML, OIDC, GitHub Actions, GCP Workload Identity Federation, Azure, and static user credentials with a unified configuration model.

Quick Start​

atmos.yaml
auth:
  providers:
    my-sso:
      kind: aws/iam-identity-center
      region: us-east-1
      start_url: https://mycompany.awsapps.com/start

  identities:
    admin:
      kind: aws/permission-set
      default: true
      via:
        provider: my-sso
      principal:
        name: AdminAccess
        account:
          name: production

Configuration Reference​

Top-Level Structure​

atmos.yaml
auth:
  logs:
    level: Info                    # Debug, Info, Warn, Error
    file: /path/to/auth.log        # Optional log file

  keyring:
    type: system                   # system, file, or memory
    spec: {}                       # Type-specific configuration

  console:
    isolated_sessions: false       # Enable isolated browser sessions per identity

  providers:
    <provider-name>:               # Named provider configurations
      kind: <provider-kind>
      # Provider-specific fields...

  identities:
    <identity-name>:               # Named identity configurations
      kind: <identity-kind>
      # Identity-specific fields...

  integrations:
    <integration-name>:            # Named integration configurations
      kind: <integration-kind>     # aws/ecr, aws/eks, github/sts
      via:
        identity: <identity-name>  # or provider: <provider-name>
      spec: {}                     # Kind-specific configuration

Subpages​

  • Providers - Configure authentication providers (AWS SSO, SAML, GitHub OIDC, GCP, Azure)
  • Identities - Configure identities and identity chaining
  • Keyring - Configure credential storage backends
  • Logs - Configure auth-specific logging

Integrations​

Integrations are client-only credential materializations that derive from identities. They are automatically triggered during atmos auth login when auto_provision is enabled (the default). The github/sts integration additionally auto-provisions in CI before the first remote git read even when no stack claims its identity — see GitHub STS.

Supported integration kinds:

Integrations may bind to an identity (via.identity) or, when the provider itself yields usable credentials (e.g. atmos/pro), directly to a provider (via.provider). Exactly one of the two must be set.

github/sts (Atmos Pro)​

The github/sts integration uses Atmos Pro as a just-in-time GitHub token broker for CI. On atmos auth login it mints short-lived, scoped GitHub App installation tokens and materializes them as per-owner git URL rewrites in the child environment, so atmos vendor pull, Atmos source: components, and terraform init of private git::https://… modules authenticate transparently — with no .tf changes. Tokens are revoked at command-end (via atmos auth exec in CI) and on atmos auth logout.

It requires the atmos/pro provider (see Providers). Your GitHub Actions workflow only needs permissions: id-token: write.

Automatic in CI — no stack claim required

The atmos/pro identity isn't claimed by any stack (stacks claim cloud identities like AWS/Azure/GCP). So in CI, Atmos provisions github/sts lazily and automatically the first time it is about to read a remote git source — atmos vendor pull, a source: component, a remote import:, or terraform init of a private module — without an explicit atmos auth login. This is gated on running in CI plus having the atmos/pro + github/sts config present with auto_provision enabled (the default). Minted tokens are reused across Atmos invocations within the same job until they expire.

auth:
  providers:
    atmos-pro:
      kind: atmos/pro
      spec:
        workspace_id: <your-workspace-id>   # or ATMOS_PRO_WORKSPACE_ID
  identities:
    atmos-pro:
      kind: atmos/pro
      via:
        provider: atmos-pro
  integrations:
    github-sts:
      kind: github/sts
      via:
        provider: atmos-pro          # or identity: atmos-pro
      spec:
        auto_provision: true         # mint on login AND lazily in CI before the first remote read (default true)
        repos: [acme/modules]        # optional source repos
        policy_name: default         # optional trust policy name
        git_config_mode: env         # "env" (default, inline GIT_CONFIG_*) or "file" (write a 0600 gitconfig + include.path)
        revoke_on_exit: true         # auto-revoke at command-end in CI (default true); set false to keep creds for a separate step
        token_env: GH_TOKEN          # optional: also export the raw token as $GH_TOKEN (for gh/checkout/API). Default: ATMOS_PRO_GITHUB_TOKEN

spec fields:

auto_provision
Mint tokens automatically on atmos auth login, and — in CI — lazily before the first remote git read even when no stack claims the atmos/pro identity. Defaults to true. Set to false to disable both.
repos
Optional list of source repositories to request access to. Identity is derived server-side from your workspace trust policies — repos you aren't trusted for are excluded (with a reason logged).
policy_name
Optional trust policy name. Defaults to default.
git_config_mode
env (default) injects inline GIT_CONFIG_KEY_n/GIT_CONFIG_VALUE_n rewrites; file writes a 0600 gitconfig and emits an additive include.path so token values stay off the environment. Overrides settings.pro.git_sts.git_config_mode.
revoke_on_exit
Auto-revoke minted tokens at command-end in CI. Defaults to true. Set false to keep credentials alive for a separate CI step. Overrides settings.pro.git_sts.revoke_on_exit.
token_env

Env var name to export the raw minted token under, for consumers beyond git (gh CLI, actions/checkout, the REST API). Defaults to ATMOS_PRO_GITHUB_TOKEN so the single-owner token also reaches Atmos's own in-process git reads (vendoring, source:, remote import:) and composes with the default settings.inject_github_token: true — no workaround needed.

The value is either a literal name (e.g. GH_TOKEN), which requires exactly one minted token, or a Go template — the same {{ .field }} syntax used elsewhere in Atmos — rendered once per minted token, which is how a single mint populates one variable per owner in multi-org runs. Multi-owner mints under a literal name skip the raw export and rely on the transparent GIT_CONFIG_* rewrites. The rendered name is sanitized into a valid environment variable name (uppercased, with every character outside [A-Z0-9_] replaced by _).

Template variables:

.owner
The GitHub org/user the token is scoped to (e.g. acme). Example: token_env: GH_TOKEN_{{ .owner }} → GH_TOKEN_ACME.
.host
The git host the token is scoped to (e.g. github.com). Example: token_env: TOKEN_{{ .host }}_{{ .owner }} → TOKEN_GITHUB_COM_ACME.

For Atmos-native git operations (vendoring, source: provisioning, go-getter), when a single token is minted and token_env is left at its default, the token is exported as ATMOS_PRO_GITHUB_TOKEN (see token_env above); Atmos prefers it over ATMOS_GITHUB_TOKEN and GITHUB_TOKEN. When a github/sts GIT_CONFIG_* rewrite already covers a repo's owner, Atmos skips URL token injection for it so git's rewrite (carrying the correct least-privilege token) wins instead of being shadowed — so settings.inject_github_token can be left at its default true.

Mint in one step, consume in the next​

Set token_env and github/sts lets you mint a short-lived, least-privilege token in one step, then use it anywhere a GitHub token is accepted. The only workflow permission required is id-token: write.

permissions:
  id-token: write

steps:
  - name: Mint a GitHub token
    # OIDC → Atmos Pro → mint; writes GH_TOKEN to $GITHUB_ENV for later steps.
    run: atmos auth env --identity=atmos-pro --format=github --login

  - name: Check out a private repo
    uses: actions/checkout@v4
    with:
      repository: acme/private-repo
      token: ${{ env.GH_TOKEN }}

  - name: Use the GitHub CLI
    run: gh repo view acme/private-repo
    env:
      GH_TOKEN: ${{ env.GH_TOKEN }}

See atmos auth env for the full command reference.

Disabling Authentication​

In CI/CD environments, you may want to disable Atmos-managed authentication and use native cloud provider credentials.

# Via CLI flag
atmos terraform plan mycomponent --stack=dev --identity=false

# Via environment variable
export ATMOS_IDENTITY=false
atmos terraform plan mycomponent --stack=dev

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

When disabled:

  • Atmos skips all identity authentication
  • Falls back to standard cloud provider SDK credential resolution
  • Works even when atmos.yaml has identity configurations

Environment Variables​

ATMOS_IDENTITY
Default identity name, or false to disable.
ATMOS_KEYRING_TYPE
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 (and github/sts token state).
ATMOS_PRO_GITHUB_TOKEN
GitHub token preferred by Atmos-native git operations (vendoring, source: provisioning, go-getter), ahead of ATMOS_GITHUB_TOKEN and GITHUB_TOKEN.
ATMOS_PRO_WORKSPACE_ID
Atmos Pro workspace ID for the atmos/pro provider (alternative to spec.workspace_id).
ATMOS_PRO_BASE_URL
Atmos Pro base URL for the atmos/pro provider (alternative to spec.base_url).

Complete Example​

atmos.yaml
auth:
  logs:
    level: Info

  keyring:
    type: system

  console:
    isolated_sessions: true        # Open each identity in its own browser session

  providers:
    company-sso:
      kind: aws/iam-identity-center
      region: us-east-1
      start_url: https://company.awsapps.com/start
      session:
        duration: 4h
      console:
        session_duration: 12h

    github-oidc:
      kind: github/oidc
      region: us-east-1

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

    # Production access via role chaining
    prod-admin:
      kind: aws/assume-role
      via:
        identity: dev-admin
      principal:
        assume_role: arn:aws:iam::999999999999:role/ProductionAdmin

    # CI/CD access via GitHub OIDC
    github-deploy:
      kind: aws/assume-role
      via:
        provider: github-oidc
      principal:
        assume_role: arn:aws:iam::123456789012:role/GitHubActionsRole

    # Emergency break-glass access
    emergency:
      kind: aws/user
      credentials:
        region: us-east-1
        mfa_arn: arn:aws:iam::123456789012:mfa/emergency

  # Integrations derive credentials from identities
  integrations:
    # ECR login for container workflows
    dev/ecr:
      kind: aws/ecr
      via:
        identity: dev-admin
      spec:
        registry:
          account_id: "123456789012"
          region: us-east-2

    # EKS kubeconfig for kubectl access
    dev/eks:
      kind: aws/eks
      via:
        identity: dev-admin
      spec:
        cluster:
          name: dev-cluster
          region: us-east-2
          alias: dev-eks

Using Profiles​

Use Atmos profiles to define different authentication configurations for various use cases. Each profile is a directory containing YAML files.

Profile structure:

profiles/
├── developer/
│   └── auth.yaml      # Developer auth config
├── ci/
│   └── auth.yaml      # CI/CD auth config
└── platform/
    └── auth.yaml      # Platform engineer auth config
profiles/developer/auth.yaml
auth:
  identities:
    dev-access:
      kind: aws/permission-set
      default: true
      via:
        provider: company-sso
      principal:
        name: DeveloperAccess
        account:
          name: development
profiles/ci/auth.yaml
auth:
  providers:
    github-oidc:
      kind: github/oidc
      region: us-east-1
  identities:
    deploy:
      kind: aws/assume-role
      default: true
      via:
        provider: github-oidc
      principal:
        assume_role: arn:aws:iam::123456789012:role/GitHubActionsRole
profiles/platform/auth.yaml
auth:
  providers:
    company-sso:
      kind: aws/iam-identity-center
      region: us-east-1
      start_url: https://company.awsapps.com/start
      session:
        duration: 8h
# Activate a profile
atmos --profile developer terraform plan myapp -s dev
ATMOS_PROFILE=ci atmos terraform apply myapp -s prod

Tutorials​

See Also​