# 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:

**File:** `atmos.yaml`

```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](/cli/configuration/auth/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](/cli/configuration/auth/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:

**File:** `stacks/catalog/transit-gateway.yaml`

```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:

**File:** `components/terraform/transit-gateway/providers.tf`

```hcl
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](/cli/configuration/auth/identities) — Configure the identities used with `required: true`
- [Providers](/cli/configuration/auth/providers) — Configure authentication providers (SSO, OIDC, SAML)