IBM Support

Configure Per-Workspace IAM Roles for AWS in Terraform Enterprise

How To


Summary

This guide explains how to configure per-workspace AWS IAM roles in Terraform Enterprise using dynamic provider credentials and OpenID Connect (OIDC). This approach enhances security by replacing shared, long-lived credentials, such as a single EC2 instance profile, with temporary, role-based credentials for each workspace.

Objective

Configure each Terraform Enterprise workspace to authenticate with AWS using its own dedicated IAM role through dynamic provider credentials, replacing shared instance profiles with workspace-specific, temporary credentials.

Environment

  • A running Terraform Enterprise instance using the Flexible Deployment Options installation method.
  • An AWS account with administrative permissions to create and manage IAM roles and OIDC identity providers.
  • Familiarity with AWS IAM concepts, including roles, trust policies, and OIDC.

Steps

Follow these steps to configure an OIDC provider in AWS and link it to a specific Terraform Enterprise workspace.

  1. Configure the OIDC Provider in AWS.

    You must first register your Terraform Enterprise instance as a trusted OIDC identity provider in your AWS account. This allows AWS IAM to trust authentication tokens issued by your TFE instance.

    1. Navigate to the IAM console in AWS.
    2. Go to Identity providers and select Add provider.
    3. For the provider type, select OpenID Connect.
    4. For the Provider URL, enter the public URL of your Terraform Enterprise instance (e.g., https://tfe.your-company.com).
    5. Click Get thumbprint to automatically fetch the server certificate thumbprint.
    6. For the Audience, enter the hostname of your Terraform Enterprise instance (e.g., tfe.your-company.com).
    7. Add the provider.

    Important: The audience value you configure here must match the TFC_AWS_WORKLOAD_IDENTITY_AUDIENCE environment variable that you will set in your Terraform workspace in Step 4. This ensures the OIDC token requested by Terraform Enterprise matches the audience expected by AWS IAM. If you use a custom audience value (as shown above), the  TFC_AWS_WORKLOAD_IDENTITY_AUDIENCE variable is required.

  2. Create a Per-Workspace IAM Role.

    Next, create a dedicated IAM role that a specific Terraform workspace can assume. The role's trust policy must reference the OIDC provider you created in the previous step and include conditions to scope access to a specific organization and workspace.

    1. In the IAM console, navigate to Roles and click Create role.
    2. For the trusted entity type, select Web identity.
    3. Choose the OIDC identity provider you created.
    4. For the Audience, select the audience you configured for the provider.
    5. Proceed to the permissions step. You will attach a permissions policy in the next step.
    6. After creating the role, open it and edit the Trust relationships policy. Modify the JSON to include conditions that restrict which TFE workspace can assume this role. This is critical for security.

    Here is an example trust policy that limits access to the my-organization organization and the my-workspace workspace:

    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam::ACCOUNT_ID:oidc-provider/tfe.your-company.com"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringEquals": {
                    "tfe.your-company.com:organization_name": "my-organization",
                    "tfe.your-company.com:workspace_name": "my-workspace"
                }
            }
        }
    ]
}

  3. Attach Permissions to the IAM Role.

    Create and attach an IAM policy to the role that grants only the permissions required for the infrastructure managed by that workspace. This enforces the principle of least privilege.

    For example, if the workspace manages S3 buckets, create a policy like this:

    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket",
                "s3:GetObject",
                "s3:PutObject",
                "s3:DeleteObject"
            ],
            "Resource": "arn:aws:s3:::my-app-bucket/*"
        }
    ]
}

  4. Configure Terraform Workspace Variables.

    Finally, configure the workspace in Terraform Enterprise to use the new IAM role. Navigate to your workspace's Variables settings and add the following environment variables:

    • TFC_AWS_PROVIDER_AUTH: Set this to true. This variable enables the dynamic credentials feature for the AWS provider.
    • TFC_AWS_RUN_ROLE_ARN: Set this to the ARN of the IAM role you created in the previous steps (e.g., arn:aws:iam::ACCOUNT_ID:role/tfe-my-workspace-role).
    • TFC_AWS_WORKLOAD_IDENTITY_AUDIENCE: Set this to match the audience value you configured in the OIDC identity provider in Step 1 (e.g., tfe.your-compnay.com). This variable is required when using a non-default audience value and ensures the OIDC token requested by Terraform Enterprise matches the audience expected by AWS IAM.

    Ensure these variables are marked as Environment Variable.

  5. Verify the Configuration.

    To confirm the setup is working correctly, queue a new plan in the configured workspace. The run should proceed without any authentication errors. You can further verify that the correct role was assumed by checking the run's logs or by reviewing AWS CloudTrail logs for the sts:AssumeRoleWithWebIdentity event associated with the role.

After completing these steps, your Terraform Enterprise workspace is configured to use dynamic, short-lived credentials for each run. The AWS provider will automatically authenticate by requesting an OIDC token from the TFE environment and using it to assume the specified IAM role. This provides strong security isolation between workspaces and eliminates the need for shared, static credentials.

Additional Information

  • Security Benefits: This method significantly improves your security posture by ensuring each workspace has access to only the AWS resources it needs to manage. It also provides a clear and auditable trail of actions performed by each workspace.
  • Scalability: You can repeat this process for every workspace, creating a unique IAM role for each to maintain strict security boundaries as your use of Terraform Enterprise grows.
  • For more detailed information, refer to the official Terraform Enterprise documentation on Dynamic Provider Credentials for AWS.

Document Location

Worldwide

[{"Type":"MASTER","Line of Business":{"code":"LOB77","label":"Automation Platform"},"Business Unit":{"code":"BU048","label":"IBM Software"},"Product":{"code":"SSGH5YK","label":"IBM Terraform Self-Managed"},"ARM Category":[{"code":"a8mgJ0000000DjdQAE","label":"Terraform"}],"ARM Case Number":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"1.0.0;1.0.1;1.0.2;1.0.3;1.1.0;1.1.1;1.1.2;1.1.3;1.1.4;1.2.0;1.2.1;1.2.2;2.0.0;2025.03;2025.04;2025.05;2025.06;2025.07"}]

Document Information

Modified date:
11 May 2026

UID

ibm17271703

Page Feedback