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 CLI Configuration

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 = <YOUR_SSO_ROLE_NAME>
region = ap-northeast-2
output = json

[profile prd]
sso_session = ghost-company-sso
sso_account_id = 444455556666
sso_role_name = <YOUR_SSO_ROLE_NAME>
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

Using AWS SSO with Terraform

  1. Set your AWS profile:
export AWS_PROFILE=dev
  1. Log in to SSO:
aws sso login

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
)
  1. 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>"
}
  1. 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.