Authentication

Terragrunt and OpenTofu/Terraform need credentials for the cloud that holds your state and infrastructure. How you provide them depends on the cloud provider:

On any of them, an auth provider command can supply different credentials to each unit at runtime.

Auth provider command

The --auth-provider-cmd flag tells Terragrunt to run a command for each unit and use the credentials it returns. It takes more setup than the options on those pages, but the credentials can differ from one unit to the next. This is especially useful in the following circumstances:

In CI/CD pipelines, where you might want to use different role assumption mechanisms for different stages of the pipeline (like a read-only, plan role during pull request open, and a read-write, apply role during merge).
On a shared development repository, where you might want to use different roles for different developers, or even different roles for the same developer, depending on the task at hand.
In a setup where units in different accounts depend on each other, and you want to assume a different role for each account.

Pass the command with the flag:

terragrunt apply --auth-provider-cmd /path/to/auth-script.sh

As with all other flags, you can also set this as an environment variable:

export TG_AUTH_PROVIDER_CMD="/path/to/auth-script.sh"
terragrunt apply

When Terragrunt executes this script, it will expect a response in stdout that obeys the following schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://docs.terragrunt.com/schemas/auth-provider-cmd/v2/schema.json",
  "title": "Terragrunt Auth Provider Command Response Schema",
  "description": "Schema for the JSON response expected from an auth provider command",
  "type": "object",
  "properties": {
    "awsCredentials": {
      "type": "object",
      "description": "AWS credentials to set as environment variables",
      "properties": {
        "ACCESS_KEY_ID": {
          "type": "string",
          "description": "AWS access key ID"
        },
        "SECRET_ACCESS_KEY": {
          "type": "string",
          "description": "AWS secret access key"
        },
        "SESSION_TOKEN": {
          "type": "string",
          "description": "AWS session token (optional)"
        }
      },
      "required": [
        "ACCESS_KEY_ID",
        "SECRET_ACCESS_KEY"
      ],
      "additionalProperties": false
    },
    "awsRole": {
      "type": "object",
      "description": "AWS role to assume",
      "properties": {
        "roleARN": {
          "type": "string",
          "description": "The ARN of the IAM role to assume"
        },
        "roleSessionName": {
          "type": "string",
          "description": "The session name for the assumed role"
        },
        "duration": {
          "type": "integer",
          "description": "Duration in seconds for the assumed role session",
          "minimum": 0
        },
        "webIdentityToken": {
          "type": "string",
          "description": "Web identity token for OIDC-based role assumption"
        }
      },
      "required": [
        "roleARN"
      ],
      "additionalProperties": false
    },
    "envs": {
      "type": "object",
      "description": "Additional environment variables to set",
      "additionalProperties": {
        "type": "string"
      }
    }
  },
  "additionalProperties": false
}

All top-level objects are optional, and you can provide multiple.

awsCredentials is the standard AWS credential object, which can be used to set the AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and (optionally) AWS_SESSION_TOKEN environment variables before running OpenTofu/Terraform.
awsRole is the role assumption object, which can be used to dynamically perform role assumption on the roleARN role with the roleSessionName session name, for a duration of time, and with a webIdentityToken if needed. Terragrunt will automatically refresh this role assumption when the duration expires.
envs is a map of environment variables that will be set before running OpenTofu/Terraform. Return Azure and GCP credentials here, using the variables listed on the Azure and GCP pages.

This feature is integrated with the Gruntwork Pipelines product to provide a secure and flexible way to manage assumption of different roles in different accounts based on context.

Authentication

Auth provider command

Further Reading