How to Configure AWS SSO CLI Access for Windows PowerShell

A complete guide to setting up AWS Single Sign-On (SSO) with the AWS CLI on Windows

Introduction

AWS Single Sign-On (AWS SSO), now known as AWS IAM Identity Center, provides a centralized way to manage access to multiple AWS accounts and applications. Instead of managing individual IAM users with long-term credentials, SSO allows you to authenticate once and access all your permitted AWS accounts seamlessly.

This guide walks you through configuring AWS SSO for CLI access on Windows using PowerShell, including an optional utility that makes managing multiple profiles a breeze.

Prerequisites

Before you begin, ensure you have:

• Windows 10/11 with PowerShell 5.1 or later
• Administrator access to install software
• Your organization’s AWS SSO start URL (e.g., https://your-company.awsapps.com/start)
• Your SSO region (typically us-east-1)

Step 1: Install AWS CLI v2

AWS CLI version 2 includes built-in SSO support. Install it using Windows Package Manager (winget):

winget install Amazon.AWSCLI

Alternatively, download the MSI installer from the AWS CLI website.

Verify Installation

After installation, refresh your PATH and verify:

# Refresh environment variables
$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")

# Verify AWS CLI
aws --version

Expected output:

aws-cli/2.x.x Python/3.x.x Windows/11 exe/AMD64

Step 2: Configure AWS SSO Profile

Option A: Interactive Configuration (Built-in)

Use the AWS CLI’s built-in SSO configuration wizard:

aws configure sso

You’ll be prompted for:

After entering these details, a browser window opens for authentication. Once authenticated, you’ll see a list of available accounts and roles. Select one to create your profile.

Option B: Manual Configuration

You can also manually edit the AWS config file. Open it in Notepad:

notepad $env:USERPROFILE\.aws\config

Add a profile section:

[profile my-dev-account]
sso_start_url = https://my-company.awsapps.com/start
sso_region = us-east-1
sso_account_id = 123456789012
sso_role_name = AdministratorAccess
region = us-east-1
output = json

Step 3: Login to AWS SSO

Authenticate with your SSO profile:

aws sso login --profile my-dev-account

A browser window opens. Complete the authentication:

1. Enter your corporate credentials
2. Approve the authorization request
3. Return to the terminal

Verify Authentication

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

Expected output:

{
    "UserId": "AROAEXAMPLEID:user@company.com",
    "Account": "123456789012",
    "Arn": "arn:aws:sts::123456789012:assumed-role/AdministratorAccess/user@company.com"
}

Step 4: Set Default Profile (Optional)

To avoid typing --profile with every command, set a default:

Per-Session (Environment Variable)

$env:AWS_PROFILE = "my-dev-account"

Permanent (User Environment Variable)

[System.Environment]::SetEnvironmentVariable("AWS_PROFILE", "my-dev-account", "User")

Or add to your PowerShell profile:

# Open PowerShell profile
notepad $PROFILE

# Add this line:
$env:AWS_PROFILE = "my-dev-account"

Advanced: Using aws-sso-util for Multiple Profiles

If you have access to many AWS accounts, manually configuring each profile is tedious. aws-sso-util is a Python utility that automatically populates all your accessible profiles.

Install Python

winget install Python.Python.3.12

Refresh PATH:

$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")

Install aws-sso-util

pip install aws-sso-util

Verify:

aws-sso-util --version

Populate All Profiles Automatically

This command discovers all accounts and roles you have access to and creates profiles for each:

aws-sso-util configure populate `
    --sso-start-url https://my-company.awsapps.com/start `
    --sso-region us-east-1 `
    --region us-east-1

A browser opens for authentication. After login, profiles are created automatically.

Customize Profile Naming

Use these options for cleaner profile names:

aws-sso-util configure populate `
    --sso-start-url https://my-company.awsapps.com/start `
    --sso-region us-east-1 `
    --account-name-case lower `
    --role-name-case lower `
    --trim-role-name "(?<=admin)istratoraccess" `
    --trim-role-name "^aws" `
    --trim-role-name "(?<=readonly)access" `
    --trim-role-name "(?<=poweruser)access" `
    --region us-east-1

This creates profiles like dev-account.admin instead of Dev-Account.AdministratorAccess.

Login to All Profiles at Once

aws-sso-util login

Working with Multiple Accounts

List All Configured Profiles

aws configure list-profiles

Switch Between Profiles

# Set for current session
$env:AWS_PROFILE = "production.admin"

# Or use --profile flag
aws s3 ls --profile production.admin

Create PowerShell Function for Easy Switching

Add to your PowerShell profile (notepad $PROFILE):

function Set-AWSProfile {
    param(
        [Parameter(Mandatory=$true)]
        [string]$ProfileName
    )
    $env:AWS_PROFILE = $ProfileName
    Write-Host "AWS Profile set to: $ProfileName" -ForegroundColor Green
    aws sts get-caller-identity
}

# Usage: Set-AWSProfile dev-account.admin

Common Use Cases

Use with Docker and ECR

Authenticate Docker with Amazon ECR:

# Login to SSO first
aws sso login --profile my-account.admin

# Authenticate Docker
aws ecr get-login-password --region us-east-1 --profile my-account.admin | docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com

Use with Terraform

Set the profile before running Terraform:

$env:AWS_PROFILE = "infrastructure.admin"
terraform init
terraform plan

Or configure in provider.tf:

provider "aws" {
  profile = "infrastructure.admin"
  region  = "us-east-1"
}

Use with AWS CDK

$env:AWS_PROFILE = "dev-account.admin"
cdk deploy

Use with boto3 (Python)

import boto3

session = boto3.Session(profile_name='dev-account.admin')
s3 = session.client('s3')
buckets = s3.list_buckets()

Understanding AWS Config Files

AWS stores configuration in two files in your home directory:

Config File (~\.aws\config)

Contains profile settings including SSO configuration:

[profile dev-account.admin]
sso_start_url = https://my-company.awsapps.com/start
sso_region = us-east-1
sso_account_id = 123456789012
sso_role_name = AdministratorAccess
region = us-east-1

Credentials File (~\.aws\credentials)

Contains static credentials (not used with SSO, but may contain other profiles):

[legacy-access]
aws_access_key_id = AKIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

View Config File

Get-Content $env:USERPROFILE\.aws\config

Edit Config File

notepad $env:USERPROFILE\.aws\config

Session Management

Check Current Session

aws sts get-caller-identity

SSO Token Expiration

SSO tokens typically last 8-12 hours. When expired, you’ll see:

Error: The SSO session associated with this profile has expired or is otherwise invalid.

Simply re-login:

aws sso login --profile my-account.admin

Logout

aws sso logout

This invalidates all cached SSO tokens.

Troubleshooting

“The SSO session has expired”

Re-authenticate:

aws sso login --profile your-profile

“Unable to locate credentials”

Ensure you’ve logged in and the profile name is correct:

# List available profiles
aws configure list-profiles

# Login to the correct profile
aws sso login --profile correct-profile-name

“An error occurred (ExpiredToken)”

Your session token has expired. Login again:

aws sso login --profile your-profile

Browser Doesn’t Open

If the browser doesn’t open automatically, the CLI displays a URL and code. Open the URL manually and enter the code.

PATH Issues After Installation

Refresh your session:

$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")

Or restart PowerShell.

Profile Not Found

Check the profile exists:

Select-String -Path "$env:USERPROFILE\.aws\config" -Pattern "your-profile"

Security Best Practices

1. Never share SSO tokens – They’re cached in ~\.aws\sso\cache\
2. Logout when done – Especially on shared machinesaws sso logout
3. Use least privilege – Request ReadOnly access for day-to-day work, Admin only when needed
4. Avoid static credentials – SSO provides temporary, rotating credentials
5. Don’t commit config files – Add .aws/ to .gitignore

Quick Reference

Conclusion

AWS SSO provides a secure, centralized way to access multiple AWS accounts without managing long-term credentials. With the AWS CLI v2’s built-in SSO support and tools like aws-sso-util, you can streamline your workflow and switch between accounts effortlessly.

Key takeaways:

• Use aws configure sso for basic setup
• Use aws-sso-util configure populate for organizations with many accounts
• Set AWS_PROFILE environment variable to avoid typing --profile repeatedly
• SSO tokens expire; simply run aws sso login to refresh

Happy cloud computing!