Skip to main content

Identities

Identities represent the user accounts or roles available from provider credentials. Configure identities in the auth.identities section of your atmos.yaml.

AWS Permission Set​

For AWS SSO permission sets.

atmos.yaml

auth:
  identities:
    dev-admin:
      kind: aws/permission-set
      default: true
      via:
        provider: company-sso
      principal:
        name: AdminAccess
        account:
          name: development        # Account name (resolved via SSO)
          # OR use account ID directly:
          # id: "123456789012"
kind
Required. Must be aws/permission-set.
default
Optional. If true, this identity is used when no identity is specified.
via.provider
Required. Name of the provider to use for authentication.
principal.name
Required. Name of the permission set.
principal.account.name
Account name/alias (resolved via SSO ListAccounts API).
principal.account.id
Numeric account ID (used directly, no lookup required).

AWS Assume Role​

For assuming IAM roles, either directly from a provider or chained from another identity.

atmos.yaml

auth:
  identities:
    prod-admin:
      kind: aws/assume-role
      via:
        identity: base-admin       # Chain through another identity
        # OR directly from provider:
        # provider: okta-saml
      principal:
        assume_role: arn:aws:iam::999999999999:role/ProductionAdmin
        session_name: atmos-prod   # Optional
kind
Required. Must be aws/assume-role.
via.identity
Name of another identity to chain from (mutually exclusive with via.provider).
via.provider
Name of a provider to use directly (mutually exclusive with via.identity).
principal.assume_role
Required. ARN of the IAM role to assume.
principal.session_name
Optional. Session name for CloudTrail auditing.

AWS Assume Root (Organizations)​

For centralized root access in AWS Organizations using sts:AssumeRoot. This allows privileged operations on member accounts without enabling root user credentials.

atmos.yaml

auth:
  identities:
    root-audit:
      kind: aws/assume-root
      via:
        identity: admin-base        # Chain through an existing identity
      principal:
        target_principal: "123456789012"           # 12-digit member account ID
        task_policy_arn: arn:aws:iam::aws:policy/root-task/IAMAuditRootUserCredentials
        duration: 15m                              # Optional (max 15m for AssumeRoot)
kind
Required. Must be aws/assume-root.
via.identity
Required. Name of another identity to chain from (must provide AWS credentials).
principal.target_principal
Required. 12-digit AWS account ID of the member account to assume root on.
principal.task_policy_arn
Required. AWS-managed root task policy ARN. See supported policies below.
principal.duration
Optional. Session duration (max 15 minutes for AssumeRoot).

Supported task policies:

  • arn:aws:iam::aws:policy/root-task/IAMAuditRootUserCredentials
  • arn:aws:iam::aws:policy/root-task/IAMCreateRootUserPassword
  • arn:aws:iam::aws:policy/root-task/IAMDeleteRootUserCredentials
  • arn:aws:iam::aws:policy/root-task/S3UnlockBucketPolicy
  • arn:aws:iam::aws:policy/root-task/SQSUnlockQueuePolicy
note

AssumeRoot requires AWS Organizations with centralized root access enabled and appropriate permissions on the base identity.

AWS User (Break-glass)​

For static IAM user credentials, typically used for emergency access.

atmos.yaml

auth:
  identities:
    emergency-user:
      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
kind
Required. Must be aws/user.
credentials.access_key_id
AWS access key ID. Use !env to reference environment variables.
credentials.secret_access_key
AWS secret access key. Use !env to reference environment variables.
credentials.region
AWS region for API calls.
credentials.mfa_arn
Optional. MFA device ARN. When set, Atmos prompts for TOTP code during authentication.
tip

Instead of storing credentials in configuration, use atmos auth user configure to store them securely in the system keyring.

Azure Subscription​

For targeting a specific Azure subscription using credentials from an Azure provider.

atmos.yaml

auth:
  identities:
    dev-subscription:
      kind: azure/subscription
      via:
        provider: azure-cli          # Reference to an Azure provider
      principal:
        subscription_id: "12345678-1234-1234-1234-123456789012"
        location: eastus             # Optional: default location
        resource_group: my-rg        # Optional: default resource group
kind
Required. Must be azure/subscription.
via.provider
Required. Name of an Azure provider to obtain credentials from.
principal.subscription_id
Required. Azure subscription ID to target.
principal.location
Optional. Default Azure region for resources.
principal.resource_group
Optional. Default resource group for resources.

The Azure subscription identity inherits credentials from the provider and sets subscription-specific environment variables (AZURE_SUBSCRIPTION_ID, ARM_SUBSCRIPTION_ID, etc.) for Terraform and other Azure tools.

Identity Chaining​

Identity chaining allows you to create complex authentication flows where one identity is used to obtain another.

atmos.yaml

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

  identities:
    # Base identity from SSO
    base-admin:
      kind: aws/permission-set
      via:
        provider: company-sso
      principal:
        name: AdminAccess
        account:
          name: core-identity

    # Cross-account role using base permissions
    prod-admin:
      kind: aws/assume-role
      via:
        identity: base-admin       # Chain through base-admin
      principal:
        assume_role: arn:aws:iam::999999999999:role/ProductionAdmin

    # Further chain for specific access
    prod-readonly:
      kind: aws/assume-role
      via:
        identity: prod-admin       # Chain through prod-admin
      principal:
        assume_role: arn:aws:iam::999999999999:role/ReadOnlyAccess

Chain Rules:

  • Chains can be arbitrarily deep: provider → identity → identity → ... → identity
  • via.provider and via.identity are mutually exclusive
  • aws/user identities don't require a via field
  • Circular dependencies are detected and rejected

Session Configuration​

Configure session durations at the identity level to override provider defaults.

atmos.yaml

auth:
  identities:
    high-security:
      kind: aws/user
      session:
        duration: 1h              # Override for this identity
      credentials:
        region: us-east-1
        mfa_arn: arn:aws:iam::123456789012:mfa/emergency

IAM user limits: 15m-12h (no MFA) or 15m-36h (with MFA)

Component-Level Overrides​

Override authentication settings for specific components in your stack configuration.

stacks/catalog/myapp.yaml

components:
  terraform:
    myapp:
      auth:
        identities:
          custom-role:
            kind: aws/assume-role
            via:
              provider: company-sso
            principal:
              assume_role: arn:aws:iam::123456789012:role/MyAppRole

Component auth configuration is deep-merged with global auth. Component identities override global identities with the same name.

Default Identity​

Mark one identity as the default to use when no identity is explicitly specified:

atmos.yaml

auth:
  identities:
    dev-admin:
      kind: aws/permission-set
      default: true              # This identity is used by default
      via:
        provider: company-sso
      principal:
        name: AdminAccess
        account:
          name: development

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

Only one identity should be marked as default. If multiple identities have default: true, the behavior is undefined.

Using Profiles for Role-Based Access​

Use Atmos profiles to define different identity configurations for various team roles. Each profile is a directory containing YAML configuration files.

Profile structure:

profiles/
├── developer/
│   └── auth.yaml      # Developer identity config
├── platform/
│   └── auth.yaml      # Platform engineer identity config
└── ci/
    └── auth.yaml      # CI/CD identity config

profiles/developer/auth.yaml

# Profile for developers - limited to dev/staging
auth:
  identities:
    dev-access:
      kind: aws/permission-set
      default: true
      via:
        provider: company-sso
      principal:
        name: DeveloperAccess
        account:
          name: development

profiles/platform/auth.yaml

# Profile for DevOps/Platform engineers - cross-account access
auth:
  identities:
    platform-admin:
      kind: aws/permission-set
      default: true
      via:
        provider: company-sso
      principal:
        name: AdminAccess
        account:
          name: core-identity

    prod-deploy:
      kind: aws/assume-role
      via:
        identity: platform-admin
      principal:
        assume_role: arn:aws:iam::999999999999:role/ProductionDeploy

profiles/ci/auth.yaml

# Profile for CI/CD pipelines
auth:
  identities:
    github-deploy:
      kind: aws/assume-role
      default: true
      via:
        provider: github-oidc
      principal:
        assume_role: arn:aws:iam::123456789012:role/GitHubActionsRole

Activate a profile based on your role:

# Developers use the developer profile
atmos --profile developer terraform plan myapp -s dev

# Platform engineers use the platform profile
atmos --profile platform terraform apply myapp -s prod --identity prod-deploy

# CI/CD uses the ci profile
ATMOS_PROFILE=ci atmos terraform apply myapp -s prod

See Also​

  • Providers — Configure the providers that identities use
  • Keyring — Configure credential storage for IAM users
  • Profiles — Environment-specific configuration overrides