Atmos Auth

Atmos Auth provides seamless authentication to AWS using IAM Identity Center or GitHub OIDC. It automatically handles credential management and session refresh.

Overview

In the previous steps, we deployed Identity Center with Permission Sets for human users and IAM roles for machine access (GitHub Actions). Now we map those Permission Sets and roles to groups of users using Atmos profiles. These profiles are preconfigured in the reference architecture.

For daily usage, see Login to AWS. For detailed commands and the latest documentation, see Atmos Auth.

Profiles

Profiles define role-based access patterns for different user types. Each profile configures which AWS SSO Permission Sets a user can assume across different accounts.

Available Profiles

Profile	Description	Root	Core Accounts	Dev/Sandbox	Staging/Prod
managers	Full access to all accounts	Write	Write	Write	Write
devops	Full access to most accounts	Read	Write	Write	Write
developers	Limited access	State	State	Write	Read
github-plan	CI/CD plan operations	State	Read	Read	Read
github-apply	CI/CD apply operations	State	Write	Write	Write

Access Levels:

1. Write — Full access including AdministratorAccess or PowerUserAccess permission sets, plus TerraformApplyAccess roles
2. Read — Read-only access via ReadOnlyAccess permission sets or TerraformPlanAccess roles
3. State — Access via TerraformStateAccess permission set, used for reading Terraform outputs from components deployed in that account

Setting Your Profile

Set the ATMOS_PROFILE environment variable to the appropriate profile for your group (e.g., managers, devops, or developers):

export ATMOS_PROFILE=devops

Add this to your shell configuration (~/.zshrc or ~/.bashrc) to make it persistent.

Configuration

Atmos Auth is configured in your profile's atmos.yaml file located in profiles/<profile>/atmos.yaml:

# profiles/devops/atmos.yaml
auth:
  providers:
    sso:
      kind: aws/iam-identity-center
      region: us-east-1
      start_url: https://your-org.awsapps.com/start
      auto_provision_identities: true

  identities:
    # Terraform identities for each account
    plat-dev/terraform:
      kind: aws/permission-set
      via:
        provider: sso
      principal:
        name: TerraformApplyAccess
        account:
          name: plat-dev

    core-identity/terraform:
      kind: aws/permission-set
      via:
        provider: sso
      principal:
        name: TerraformApplyAccess
        account:
          name: core-identity

Identity Naming Convention

Identities follow the format <account>/<permission-set>:

1. Static Terraform identities — Preconfigured identities like plat-dev/terraform that map the correct Permission Set or IAM role for Terraform operations (plan, apply, or state access) for each stack. Defined in stack defaults (e.g., stacks/orgs/acme/plat/dev/_defaults.yaml)
2. Auto-provisioned Permission Sets — When auto_provision_identities: true is set, Atmos automatically populates all Permission Sets available to the user (e.g., plat-dev/ReadOnlyAccess, plat-prod/AdministratorAccess) for console and CLI access

Next Steps

Start using AWS

With Atmos Auth configured and profiles ready, learn how to access AWS and deploy Terraform using Atmos. Login to AWS