iam_web_identity_token

unitoptional(string)

Usage

The iam_web_identity_token attribute works with iam_role to assume a role using AssumeRoleWithWebIdentity, and has no effect without it. Set it to either the token value (typically using get_env()) or the path to a file on disk.

AssumeRoleWithWebIdentity lets you run Terragrunt in your CI/CD pipelines without static AWS credentials.

Precedence

Terragrunt uses the first of these that is set:

1. The --iam-assume-role-web-identity-token flag.
2. The TG_IAM_ASSUME_ROLE_WEB_IDENTITY_TOKEN environment variable.
3. iam_web_identity_token in the unit’s terragrunt.hcl.
4. iam_web_identity_token in a file the unit includes.

Git provider configuration

To use AssumeRoleWithWebIdentity in your CI/CD environment, you must first configure an AWS OpenID Connect provider to trust the OIDC service provided by your Git provider.

Follow the instructions for whichever Git provider you use:

• GitLab: Configure OpenID Connect in AWS to retrieve temporary credentials
• GitHub: Configuring OpenID Connect in Amazon Web Services
• CircleCI: Using OpenID Connect tokens in jobs

Once you have configured your OpenID Connect provider and the trust policy of your IAM role, configure Terragrunt to use the Web Identity Token as shown in the examples below.

Examples

If your Git provider provides the OIDC token as an environment variable, read it with get_env().

terragrunt.hcl

iam_role = "arn:aws:iam::<AWS account number>:role/<IAM role name>"

iam_web_identity_token = get_env("<variable name>")

If your Git provider provides the OIDC token as a file, pass the file’s path.

terragrunt.hcl

iam_role = "arn:aws:iam::<AWS account number>:role/<IAM role name>"

iam_web_identity_token = "/path/to/token/file"