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.
- 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.
- 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!
Top comments (0)