Required

Mark identities as required: true so they are automatically authenticated before Terraform runs — without prompting or selection.

The Problem

When Terraform components use multiple AWS provider aliases for multi-account patterns (e.g., hub-spoke networking or cross-account peering), each provider assumes a different IAM role. In CI environments with OIDC authentication, only the primary identity's profile is written to the shared credentials file. The additional provider aliases fail because their AWS profiles don't exist.

Configuration

Set required: true on any identity that should be automatically authenticated:

atmos.yaml

auth:
  identities:
    core-network:
      kind: aws/assume-role
      default: true       # Primary identity (sets AWS_PROFILE)
      required: true      # Auto-authenticate without prompting
      # ... via, principal, etc. (see identities docs for full config)
    plat-prod:
      kind: aws/assume-role
      required: true      # Auto-authenticate as secondary
      # ... via, principal, etc.
    plat-staging:
      kind: aws/assume-role
      required: true      # Auto-authenticate as secondary
      # ... via, principal, etc.

note

These snippets only show the default and required fields. Each aws/assume-role identity also requires via and principal configuration. See Identities for complete examples.

The required and default fields are orthogonal:

• default: true — this is the PRIMARY identity (sets AWS_PROFILE, credential env vars). Only one allowed.
• required: true — auto-authenticate this identity without prompting. Multiple allowed.

All required identities must be defined in your identities configuration (either globally in atmos.yaml or via component-level overrides).

Behavior

required

A boolean field on an identity that marks it for automatic authentication. Before Terraform runs, Atmos authenticates the default identity as the primary, then authenticates every identity with required: true and writes all profiles to the shared AWS credentials file.

• The default identity is always the primary, setting AWS_PROFILE and default credential environment variables.
• Required non-default identities are authenticated as secondary — their profiles are written to the shared credentials file, making them available for Terraform provider aliases.
• The --identity CLI flag takes precedence over default for primary selection, but required identities are still authenticated as secondary.
• Failures for non-primary required identities are non-fatal — Atmos logs a warning and continues.

Example

A hub-spoke networking component that peers VPCs across three AWS accounts:

stacks/catalog/transit-gateway.yaml

components:
  terraform:
    transit-gateway:
      auth:
        identities:
          hub-network:
            kind: aws/assume-role
            default: true
            required: true
            # ... via, principal (see identities docs)
          spoke-production:
            kind: aws/assume-role
            required: true
            # ... via, principal
          spoke-staging:
            kind: aws/assume-role
            required: true
            # ... via, principal
      vars:
        hub_account_id: "111111111111"
        spoke_accounts:
          production: "222222222222"
          staging: "333333333333"

Each identity's AWS profile is available for the corresponding Terraform provider alias:

components/terraform/transit-gateway/providers.tf

provider "aws" {
  # Uses the default identity (hub-network) — automatically authenticated as primary
}

provider "aws" {
  alias   = "production"
  profile = "spoke-production"
}

provider "aws" {
  alias   = "staging"
  profile = "spoke-staging"
}

See Also

• Identities — Configure the identities used with required: true
• Providers — Configure authentication providers (SSO, OIDC, SAML)