Using AWS AssumeRole with the AWS Terraform Provider

Introduction

This article details how to use the AWS provider for Terraform to manage resources in a secondary AWS account (Account B) by assuming a role from a primary AWS account (Account A). This method, known as AssumeRole, allows an IAM user to request temporary security credentials for another account, eliminating the need to manage separate credentials for each AWS account.

Prerequisites

• Two AWS accounts (a primary account, Account A, and a target account, Account B).
• An IAM user in Account A with permissions to call sts:AssumeRole.
• Terraform installed and configured locally, or access to an HCP Terraform or Terraform Enterprise environment.

Procedure

This procedure configures Terraform to authenticate to Account A, request temporary credentials for Account B, and then assume a role to manage resources within Account B.

1. Create an IAM Role in the Target Account (Account B)

   In the AWS account you want to manage (Account B), create a new IAM role that trusts the primary account (Account A).

   a. Navigate to IAM > Roles > Create role in the AWS console for Account B. b. Select Another AWS account as the trusted entity type. c. Enter the Account ID of Account A. d. (Optional) Select the box for Require external ID to add another layer of security. This ensures that requests from Account A are only successful if they include a specific external ID that you define. e. (Optional) Select the box for Require MFA to enforce that the IAM user in Account A has authenticated with multi-factor authentication. f. Attach the necessary permissions policies to the role to allow it to manage the intended resources in Account B. g. Complete the role creation process and note the role's ARN.

2. Configure the Terraform AWS Provider

   In your Terraform configuration, configure the AWS provider to use the credentials for Account A and specify the assume_role block to connect to Account B.

   provider "aws" {
     ## Credentials for the IAM user in AWS Account A.
     ## We recommend using environment variables or other dynamic methods
     ## instead of hardcoding credentials.
     access_key = "<YOUR_AWS_ACCESS_KEY>"
     secret_key = "<YOUR_AWS_SECRET_KEY>"
     region     = "us-east-1"
   
     ## (Optional) Session Token obtained from sts:GetSessionToken or sts:AssumeRole
     ## when MFA is configured.
     token = "<YOUR_AWS_SESSION_TOKEN>"
   
     assume_role {
       ## The ARN of the role in Account B to assume.
       role_arn = "arn:aws:iam::01234567890:role/role_in_account_b"
   
       ## (Optional) The external ID defined during role creation.
       external_id = "my_external_id"
     }
   }

3. Initialize and Apply the Configuration

   Run terraform init to initialize your configuration. You can perform this action using the Terraform CLI or within an HCP Terraform or Terraform Enterprise workspace.

   $ terraform init

4. Verify the Configuration

   Create a test resource in your configuration and run terraform apply. Verify that Terraform successfully creates the resource in the target AWS account (Account B).

   resource "aws_s3_bucket" "test_bucket" {
     bucket = "my-test-bucket-for-assume-role-verification"
   }

   $ terraform apply

Additional Information

For more details on the available arguments for the assume_role block, please refer to the official AWS provider documentation.