Setting up Terraform with AWS SSO

Small world. Big idea!

Overview

This guide explains how to set up and use Terraform with AWS IAM Identity Center (SSO). It demonstrates how to configure Terraform versions using tfenv in a local environment and how to easily switch between different environments (dev, prd, ops) using AWS CLI with SSO profiles.

TLDR

Terraform CLI Version

⚠️ Important: To use AWS IAM Identity Center with the Terraform CLI, you must use Terraform v1.6.0 or higher. Earlier versions don't support AWS IAM Identity Center resources, so updating is essential for proper functionality.

To check your current Terraform version:

terraform version

If you need to update, you can easily do so using version management tools like tfenv:

tfenv use 1.6.0

For more details, refer to issue #32465.

Setup Instructions

Installing tfenv

tfenv is a version management tool that makes it easy to manage multiple Terraform versions. It's particularly useful when working with different projects that require specific Terraform versions.

If you're using Homebrew, you can install tfenv with:

brew install tfenv
tfenv -v

Setting Terraform Version

Set Terraform to version 1.6.0 or higher using tfenv:

tfenv use 1.6.0

Verify your local Terraform version:

$ tfenv list
* 1.6.0 (set by /opt/homebrew/Cellar/tfenv/3.0.0/version)
  1.3.2
$ terraform version
Terraform v1.6.0
on darwin_arm64

AWS SSO CLI Configuration

Before using AWS SSO with Terraform, you need to configure your AWS CLI profiles with SSO settings. You can do this in two ways:

Option 1: Interactive Configuration

Use the aws configure sso command to interactively set up your SSO profiles:

# Configure development profile
aws configure sso --profile dev

The command will prompt you for:

• SSO session name (e.g., ghost-company-sso)
• SSO start URL (e.g., https://<YOUR_SSO_DOMAIN>.awsapps.com/start/#)
• SSO region (e.g., ap-northeast-2)
• SSO registration scopes (default: sso:account:access)
• Account ID (e.g., 111122223333)
• Role name (your SSO role name)
• CLI default client region (e.g., ap-northeast-2)
• CLI default output format (e.g., json)

Repeat for additional profiles:

# Configure production profile
aws configure sso --profile prd

Option 2: Manual Configuration

Alternatively, you can manually edit your AWS CLI configuration file.

AWS CLI Configuration

After configuring SSO, verify your AWS CLI configuration file (~/.aws/config) contains the following:

#--------------------------------------------
# IAM Roles provided by IAM Identity Center
#--------------------------------------------
[profile dev]
sso_session = ghost-company-sso
sso_account_id = 111122223333
sso_role_name = AdministratorAccess
region = ap-northeast-2
output = json

[profile prd]
sso_session = ghost-company-sso
sso_account_id = 444455556666
sso_role_name = AdministratorAccess
region = ap-northeast-2
output = json

[sso-session ghost-company-sso]
sso_start_url = https://<YOUR_SSO_DOMAIN>.awsapps.com/start/#
sso_region = ap-northeast-2
sso_registration_scopes = sso:account:access

Testing

# check profile
aws configure list-profiles

# Test login
aws sso login --profile dev
aws sts get-caller-identity --profile dev

# Switch và test profile other
aws sso login --profile prd
aws sts get-caller-identity --profile prd

Using AWS SSO with Terraform

1. Set your AWS profile:

export AWS_PROFILE=dev

2. Log in to SSO:

aws sso login --profile dev

Alternatively, use the asp command for easier login:

# asp <PROFILE> login
asp dev login

Note: asp is a tool for managing AWS SSO profiles and automating login. It's built into the AWS Zsh plugin. If you're using Oh My Zsh, add the AWS plugin to your ~/.zshrc:

# $HOME/.zshrc
plugins=(
  aws
)

3. After successful SSO login, verify your assumed role:

$ aws sts get-caller-identity
{
    "UserId": "XYZX43YZ5XYZXYZXYZOXY:<REDACTED>",
    "Account": "111122223333",
    "Arn": "arn:aws:sts::111122223333:assumed-role/AWSReservedSSO_<REDACTED>_<REDACTED>/<REDACTED>"
}

4. Run Terraform commands:

terraform init
terraform plan
terraform apply

Switching Environments

During your SSO session, you can switch between environments without additional login:

Using export:

export AWS_PROFILE=prd
terraform init
terraform plan
terraform apply

Or using asp:

asp prd
terraform init
terraform plan
terraform apply

Additional Resources

For more detailed information, refer to the AWS documentation on IAM Identity Center and Terraform's AWS provider documentation.