Step-by-Step Guide to Setting Up Terraform, AWS CLI, and Your AWS Environment

Setting up your local development environment is one of the first and most important steps when getting started with Infrastructure as Code (IaC).

When working with Terraform and AWS, how you manage authentication matters just as much as how you write your infrastructure code. Hardcoding AWS access keys into Terraform provider configurations might seem convenient initially, but it introduces unnecessary security risks and makes credential management more difficult.

A better approach is to use AWS IAM Identity Center (formerly AWS SSO) to manage short-lived credentials and integrate them with the AWS CLI, Terraform, and VS Code.

In this guide, I'll walk you through the exact setup process I used, including:

Configuring AWS IAM Identity Center.
Setting up AWS CLI authentication using SSO.
Managing AWS profiles with aws-sso-util.
Configuring Terraform in VS Code.
Handling PowerShell command-line issues.
Improving the workflow with automated credential checks.

Let's get started!

1. Defining the Architecture and Key Decisions

Before running any terminal commands, I made three important decisions regarding the development environment.

1.1 Authentication Strategy: AWS IAM Identity Center

Instead of using static AWS access keys, I chose AWS IAM Identity Center (AWS SSO).

This approach provides several advantages:

Uses temporary credentials instead of long-lived access keys.
Reduces the risk of accidentally exposing secrets.
Simplifies authentication across AWS accounts.
Supports centralized access management through AWS permission sets.

Security note: Temporary credentials improve security, but they don't eliminate all risks. Always follow the principle of least privilege and avoid assigning administrator permissions unless they are genuinely required.

1.2 Primary AWS Region
For this setup, I selected:

us-east-1

This region was used as the default region for my AWS CLI and Terraform configuration.

Important: IAM Identity Center is configured in a specific AWS Region, and the SSO configuration must use the region where your IAM Identity Center instance is deployed. Your workload resources can be deployed in other regions as needed.

1.3 Tooling Stack

Here are the tools used in this setup:

Tool Purpose
AWS CLI v2 AWS authentication and command-line management
Terraform CLI Infrastructure as Code
aws-sso-util AWS SSO profile management and credential workflows
Visual Studio Code Development environment
HashiCorp Terraform Extension Terraform syntax highlighting and editor support

With the tools and authentication strategy defined, let's configure the AWS environment.

2. Setting Up AWS IAM Identity Center

The first step is to configure IAM Identity Center from the AWS Management Console.

Step 1: Log In to the AWS Management Console

Log in using an account with the permissions required to configure IAM Identity Center.

For a new AWS environment, this may involve the AWS account's management or administrative setup.

Step 2: Enable IAM Identity Center
Open the AWS Management Console.
Search for IAM Identity Center.
Open the service.
Click Enable if it has not already been activated.

Once enabled, you can manage users, permission sets, and account assignments.

Step 3: Create a Dedicated User

Navigate to:

IAM Identity Center → Users → Add user

Enter the required user information, including your name and email address.

AWS will send an email invitation or activation workflow, depending on your configuration.

Step 4: Create a Permission Set

Navigate to:

IAM Identity Center → Permission sets → Create permission set

For this setup, I selected:

Predefined permission set → AdministratorAccess

Security recommendation: AdministratorAccess grants broad permissions. For production environments, consider creating a custom permission set with only the permissions required for your Terraform workflows.

Step 5: Assign Account Access

Navigate to the AWS accounts section.

Select the AWS account you want to access.
Choose your IAM Identity Center user.
Assign the AdministratorAccess permission set.
Complete the account assignment.

Your user should now be able to authenticate through the AWS access portal.

Step 6: Retrieve the AWS Access Portal URL

From the IAM Identity Center settings dashboard, copy the AWS access portal URL.

It should look similar to:

https://d-xxxxxxxxx.awsapps.com/start

Important: Use the AWS access portal URL when configuring SSO. Do not substitute the IAM Identity Center instance ARN for the start URL.

3. Configuring the AWS CLI Using SSO
With IAM Identity Center configured, the next step is to connect your local machine to AWS.

I used the integrated terminal in VS Code for this setup.

Step 1: Start the AWS SSO Configuration Wizard

Run the following command:

aws configure sso

The AWS CLI will guide you through the configuration process.

Step 2: Provide the Configuration Details

During the setup, you will be prompted for values similar to the following:

Configuration Value
SSO session name my-org
SSO start URL Your AWS access portal URL
SSO region us-east-1 (if applicable to your Identity Center instance)
SSO registration scopes sso:account:access

For the start URL, use your actual AWS access portal URL:

https://d-xxxxxxxxx.awsapps.com/start

The AWS CLI will open a browser window for authorization.

After authentication:

Select the target AWS account.
Select the available permission set.
Enter a profile name when prompted.

For this setup, I used:

dev-profile
Step 3: Verify the AWS Session

Once configuration is complete, verify that your profile can authenticate successfully:

aws sts get-caller-identity --profile dev-profile

If authentication is successful, AWS will return information such as:

Account ID.
IAM role or assumed-role ARN.
Caller identity ID.

This confirms that the AWS CLI is using the configured profile.

4. Automating Profile Management with aws-sso-util
Managing multiple AWS accounts and SSO profiles manually can become difficult, especially when working across different environments.

To simplify this workflow, I installed aws-sso-util, a Python-based command-line utility designed to assist with AWS SSO configuration and credential management.

Step 1: Install aws-sso-util

Run:

pip install aws-sso-util

Tip: Consider using a Python virtual environment when installing Python CLI tools to avoid conflicts with other projects.

Step 2: Configure AWS SSO Profiles

The following command was used to populate AWS SSO profile configuration:

aws-sso-util configure populate --sso-start-url https://d-xxxxxxxxx.awsapps.com/start --sso-region us-east-1 --region us-east-1

Replace the example start URL with your actual AWS access portal URL.

My recommendation: When working with long commands in PowerShell, use a single-line command when practical. It reduces the risk of line-continuation and formatting errors.

Step 3: Start the SSO Session

After configuring the profiles, initiate the login process:

aws-sso-util login

Follow the prompts provided by the utility to authenticate.

Note: The exact behavior of aws-sso-util depends on the installed version and your AWS configuration. Verify the utility's current documentation if a command behaves differently in your environment.

5. Configuring Terraform in VS Code

Now that AWS authentication is configured, the next step is to connect Terraform to the AWS environment.

One of the advantages of using SSO-based authentication is that your Terraform provider configuration can remain simple without embedding static access keys.

Step 1: Create provider.tf

Inside your Terraform project, create a file named:

provider.tf

Add the following configuration:

terraform {
required_version = ">= 1.5.0"

required_providers {
aws = {
source = "hashicorp/aws"
version = "~> 5.0"
}
}
}

provider "aws" {
region = "us-east-1"
profile = "dev-profile"
}
Understanding the Configuration

Terraform version constraint

required_version = ">= 1.5.0"

This specifies the minimum Terraform version supported by the configuration.

AWS provider

source = "hashicorp/aws"
version = "~> 5.0"

This identifies the AWS provider and specifies a compatible version range within the 5.x release series.

AWS region

region = "us-east-1"

This sets the default region for AWS resources managed through the provider.

AWS profile

profile = "dev-profile"

This tells Terraform to use the AWS CLI profile named dev-profile.

Step 2: Initialize Terraform

Open the integrated terminal in VS Code and run:

terraform init

This command initializes the Terraform working directory and downloads the required provider plugins.

Step 3: Validate the Terraform Configuration

Run:

terraform validate

This checks whether the Terraform configuration is syntactically valid and internally consistent.

Step 4: Run a Terraform Plan

Next, run:

terraform plan

This generates an execution plan showing the infrastructure changes Terraform intends to make.

If your configuration includes AWS resources, Terraform will need valid credentials and the required permissions to read the relevant AWS APIs.

Important: terraform plan is not just a general credential test. It evaluates the configuration and may make AWS API calls depending on the resources and data sources involved.

How Terraform Uses the AWS SSO Credentials
Terraform's AWS provider can use credentials supplied through the AWS shared configuration and credential files.

When the configured AWS profile contains valid temporary credentials, the provider can use them to authenticate with AWS.

This means you do not need to place static credentials directly inside your Terraform provider block.

Security principle:

Never hardcode AWS access keys or secret keys in Terraform configuration files.

1. Automating the Terraform Workflow (Pro Tip)

One of the challenges of using temporary AWS credentials is that sessions eventually expire.

Instead of manually checking the session every time, you can create a shell wrapper that checks whether your credentials are still valid before running Terraform.

The implementation depends on your shell.

Option 1: Bash or Zsh

For Bash or Zsh, you can add a function to your shell configuration file, such as:

~/.zshrc

Example:

tf() {
if ! aws sts get-caller-identity --profile dev-profile > /dev/null 2>&1; then
echo "SSO session expired. Refreshing..."
aws sso login --profile dev-profile
fi

command terraform "$@"
}

After adding the function, reload your shell configuration:

source ~/.zshrc

You can then run:

tf plan

or:

tf apply
Option 2: PowerShell

Since I primarily use VS Code with PowerShell, here's a PowerShell equivalent:

function tf {
$profileName = "dev-profile"

aws sts get-caller-identity --profile $profileName *> $null

if ($LASTEXITCODE -ne 0) {
    Write-Host "SSO session expired or unavailable. Refreshing..."

    aws sso login --profile $profileName

    if ($LASTEXITCODE -ne 0) {
        Write-Error "AWS SSO login failed."
        return
    }
}

terraform @args

}

You can add this function to your PowerShell profile:

notepad $PROFILE

If the profile file does not exist, create it first:

New-Item -ItemType File -Path $PROFILE -Force

After saving the function, reload your PowerShell profile:

. $PROFILE

Now you can use:

tf plan

The wrapper checks whether AWS credentials are valid. If the session is unavailable, it prompts you to authenticate through AWS SSO before proceeding.

Important: The wrapper only handles the login check. You should still review your Terraform plan carefully before applying infrastructure changes.

7. Common Issues and Lessons Learned
Setting up Terraform with AWS SSO is relatively straightforward, but a few details can cause confusion.

7.1 PowerShell and Bash Are Not the Same

Commands copied from Linux tutorials may not work as expected in PowerShell.

Feature Bash PowerShell
Multiline continuation \ Backtick (`)
Output redirection /dev/null $null or PowerShell redirection
Shell profile ~/.bashrc or ~/.zshrc $PROFILE

Always adapt commands to the shell you are using.

7.2 Use the Correct SSO Start URL

The AWS SSO start URL is not the same as the IAM Identity Center instance ARN.

Use the access portal URL:

https://d-xxxxxxxxx.awsapps.com/start
7.3 Avoid Hardcoded Credentials

Do not store the following directly in your Terraform provider configuration:

access_key = "YOUR_ACCESS_KEY"
secret_key = "YOUR_SECRET_KEY"

Use AWS's supported credential mechanisms instead, such as IAM Identity Center, environment-based credentials, or IAM roles.

7.4 Check Your Permission Sets

A successful SSO login does not automatically mean you have permission to perform every Terraform operation.

Ensure that your assigned permission set grants the permissions required for the resources you are managing.

1. Final Workflow Summary

Here is the workflow I use to connect AWS SSO, Terraform, and VS Code:

AWS Management Console
│
▼
AWS IAM Identity Center
│
▼
Configure AWS CLI with SSO
│
▼
Create and authenticate AWS profile
│
▼
Configure Terraform provider
│
▼
terraform init
│
▼
terraform validate
│
▼
terraform plan
│
▼
Review and apply infrastructure changes

The goal is to establish a secure and repeatable workflow for managing AWS infrastructure without relying on static access keys in Terraform configuration files.

Conclusion

Setting up Terraform and AWS correctly from the beginning can save you a lot of time and prevent avoidable security mistakes.

By combining AWS IAM Identity Center, AWS CLI, Terraform, and VS Code, you can build a workflow that supports temporary credentials, cleaner infrastructure code, and more manageable AWS authentication.

The PowerShell issues I encountered also reinforced an important lesson: understanding your development environment matters. A command that works perfectly in Bash may require adjustments in PowerShell.

If you're learning Terraform or preparing for real-world cloud engineering projects, getting your authentication workflow right is a valuable first step.

What's your preferred way of managing AWS credentials for Terraform: IAM Identity Center, IAM roles, or another approach?

Share your experience in the comments!