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 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.

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:

atmos.yaml

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

  # Profile for DevOps/Platform engineers - cross-account access
  platform:
    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

  # Profile for CI/CD pipelines
  ci:
    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