Configuring IAM Identity Center (AWS SSO) authentication with the AWS CLI

AWS SSO provides centralized access to multiple AWS accounts using identity federation. This guide explains how to configure the AWS CLI to authenticate with AWS SSO.

Prerequisites

AWS CLI v2 installed (aws --version)
Access to your AWS SSO portal (provided by your AWS administrator)
Your SSO Start URL and SSO Region
AWS Account IDs you need to access
IAM Role names assigned to your user

Understanding AWS SSO Configuration

AWS SSO uses two configuration sections in ~/.aws/config:

[profile ...] - Maps a profile name to an AWS account, role, and region
[sso-session ...] - Defines connection parameters to your SSO service

The AWS CLI stores temporary credentials in ~/.aws/sso/cache/. These credentials expire after 8-12 hours.

Setup Process

Using the AWS CLI Wizard

Run the configuration wizard:

aws configure sso

The wizard asks for:

SSO session name (e.g., company-sso)
SSO start URL (e.g., https://d-1234567890.awsapps.com/start)
SSO region (e.g., ap-southeast-2)
AWS account selection
IAM role selection
Default region and output format
Profile name

Complete the wizard for each account and role combination you need.

Manual Configuration

Edit ~/.aws/config directly. Add sections for each profile and SSO session:

[profile Default]
sso_session = default-sso
sso_account_id = 111122223333
sso_role_name = Administrator
region = ap-southeast-2
output = json

[profile Company-1-ReadOnly]
sso_session = company-1-sso
sso_account_id = 222233334444
sso_role_name = ReadOnly
region = ap-southeast-2
output = json

[profile Company-1-Administrator]
sso_session = company-1-sso
sso_account_id = 222233334444
sso_role_name = Administrator
region = ap-southeast-2
output = json

[profile Company-2-ReadOnly]
sso_session = company-2-sso
sso_account_id = 333344445555
sso_role_name = ReadOnly
region = ap-southeast-2
output = json

[profile Company-2-Administrator]
sso_session = company-2-sso
sso_account_id = 333344445555
sso_role_name = Administrator
region = ap-southeast-2
output = json

[sso-session default-sso]
sso_start_url = https://d-1234567890.awsapps.com/start
sso_region = ap-southeast-2
sso_registration_scopes = sso:account:access

[sso-session company-1-sso]
sso_start_url = https://d-9876543210.awsapps.com/start
sso_region = ap-southeast-2
sso_registration_scopes = sso:account:access

[sso-session company-2-sso]
sso_start_url = https://d-555666777.awsapps.com/start
sso_region = ap-southeast-2
sso_registration_scopes = sso:account:access

Each AWS organization requires its own SSO session. Profiles within the same organization can share an SSO session. In this example, Company-1-ReadOnly and Company-1-Administrator share the same SSO session, as do Company-2-ReadOnly and Company-2-Administrator.

Daily Usage

Login

Authenticate with AWS SSO:

# Login to a specific profile
aws sso login --profile Default

# Login to all profiles sharing an SSO session
aws sso login --sso-session company-1-sso
aws sso login --sso-session company-2-sso

The first login opens your browser for authentication. Complete the login process in your browser.

Using Profiles

Specify a profile for individual commands:

aws s3 ls --profile Company-1-ReadOnly
aws ec2 describe-instances --profile Company-1-Administrator
aws s3 cp file.txt s3://bucket --profile Company-2-ReadOnly

Set a default profile for your session:

export AWS_PROFILE=Company-1-ReadOnly
aws s3 ls  # Uses Company-1-ReadOnly profile

Verify Authentication

Check your current identity:

aws sts get-caller-identity --profile Company-1-ReadOnly

Logout

Clear cached credentials:

# Logout specific profile
aws sso logout --profile Company-1-ReadOnly

# Logout all SSO sessions
aws sso logout

Security Considerations

SSO configuration in ~/.aws/config contains no secrets and can be backed up safely
Never commit ~/.aws/credentials to version control
Cached SSO tokens in ~/.aws/sso/cache/ contain temporary credentials
SSO eliminates the need for long-term access keys on your workstation

Security Best Practices

Token Management

Clear cached SSO tokens when not needed: aws sso logout
Tokens expire automatically after 8-12 hours but should be cleared manually when switching environments
Store tokens on encrypted storage when possible

Permission Management

Apply least privilege access: Use ReadOnly roles when administrative access is not required
Regularly audit assigned permissions in AWS SSO
Use time-limited permission sets when possible

Configuration Security

Protect the ~/.aws/config file with appropriate file permissions: chmod 600 ~/.aws/config
Do not share SSO session URLs or configuration files containing sensitive information
Use separate SSO sessions for different organizations to maintain isolation

Network Security

Use VPN connections when accessing sensitive AWS resources
Ensure your network connection is secure when authenticating with SSO
Enable MFA where possible in your identity provider

Credential Hygiene

Log out of SSO sessions when finished working: aws sso logout
Monitor AWS CloudTrail logs for unusual activity
Rotate IAM Identity Center user passwords regularly

Troubleshooting

Session Expired

Error: "The SSO session associated with this profile has expired"

Solution:

aws sso login --profile Company-1-ReadOnly

Corrupted Token Cache

Error: "Invalid grant provided"