identity

The identity field authenticates an Atmos auth identity before a custom command runs. This is useful when commands need to interact with cloud resources that require specific credentials or elevated permissions.

Using Authentication with Custom Commands

When an identity is specified, Atmos will:

1. Authenticate using the specified identity (prompting for MFA if required)
2. Write temporary credentials to a file
3. Set environment variables for the temporary credential files (AWS_SHARED_CREDENTIALS_FILE, AWS_CONFIG_FILE) and profile selection (AWS_PROFILE, etc.)
4. Execute all command steps with these environment variables

Example: Custom Command with Authentication

commands:
  - name: deploy-infra
    description: Deploy infrastructure with superadmin privileges
    identity: superadmin  # Authenticate as superadmin before running
    arguments:
      - name: component
        description: Component to deploy
        required: true
    flags:
      - name: stack
        shorthand: s
        description: Stack to deploy to
        required: true
    steps:
      - atmos terraform plan {{ .Arguments.component }} -s {{ .Flags.stack }}
      - atmos terraform apply {{ .Arguments.component }} -s {{ .Flags.stack }} -auto-approve

To execute this command:

atmos deploy-infra vpc -s plat-ue2-prod

Atmos will:

1. Authenticate as superadmin (prompting for MFA if configured)
2. Set up environment variables pointing to temporary credential files
3. Execute both terraform plan and terraform apply with those credentials

Example: Multi-Step Command with Authentication

commands:
  - name: audit-resources
    description: Audit cloud resources with auditor credentials
    identity: auditor
    flags:
      - name: region
        shorthand: r
        description: AWS region
        required: true
    steps:
      - |
        echo "Running audit in {{ .Flags.region }}..."
        aws sts get-caller-identity
      - |
        aws ec2 describe-instances --region {{ .Flags.region }} \
          --query 'Reservations[].Instances[].[InstanceId,State.Name,Tags[?Key==`Name`].Value|[0]]' \
          --output table
      - |
        aws s3 ls --region {{ .Flags.region }}

All steps in this command will execute with the auditor identity credentials.

Authentication with Component Config

You can combine identity authentication with component configuration:

commands:
  - name: provision-with-auth
    description: Provision component with specific identity
    identity: infrastructure-admin
    arguments:
      - name: component
        description: Component to provision
    flags:
      - name: stack
        shorthand: s
        description: Stack name
        required: true
    component_config:
      component: "{{ .Arguments.component }}"
      stack: "{{ .Flags.stack }}"
    env:
      - key: COMPONENT_REGION
        value: "{{ .ComponentConfig.vars.region }}"
    steps:
      - |
        echo "Provisioning {{ .Arguments.component }} in {{ .ComponentConfig.vars.region }}"
        echo "Using identity: infrastructure-admin"
        aws sts get-caller-identity
      - atmos terraform apply {{ .Arguments.component }} -s {{ .Flags.stack }}

tip

Configure identities in your atmos.yaml under the auth section. See the Authentication documentation for configuration details.

Overriding Identity at Runtime

You can override the identity specified in the command configuration using the --identity flag:

# Use the identity from command config
atmos deploy-infra vpc -s plat-ue2-prod

# Override with a different identity
atmos deploy-infra vpc -s plat-ue2-prod --identity developer

# Use no identity (skip authentication even if configured)
atmos deploy-infra vpc -s plat-ue2-prod --identity ""

The --identity flag is automatically added to all custom commands and takes precedence over the identity field in the command configuration.

note

The identity field applies to all steps in the custom command. If you need different identities for different operations, consider using separate custom commands or workflows with per-step identity configuration.