Configuring IAM Identity Center (AWS SSO) authentication with the AWS CLI - A comprehensive guide covering setup, configuration, security best practices, and troubleshooting

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

1. AWS CLI v2 installed (aws --version)
2. Access to your AWS SSO portal (provided by your AWS administrator)
3. Your SSO Start URL and SSO Region
4. AWS Account IDs you need to access
5. 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"

Solution:

rm -rf ~/.aws/sso/cache/
aws sso login --profile Company-1-ReadOnly

Profile Not Found

Error: "Profile Company-1-ReadOnly not found"

Solution: Verify the profile name exists in ~/.aws/config

Configuration Reference

Profile Section

[profile PROFILE_NAME]
sso_session = SESSION_NAME          # References [sso-session] section
sso_account_id = 123456789012       # 12-digit AWS Account ID
sso_role_name = RoleName            # IAM Role name in AWS SSO
region = ap-southeast-2             # Default region for AWS commands
output = json                       # Output format (json, text, table)

SSO Session Section

[sso-session SESSION_NAME]
sso_start_url = https://d-xxxxx.awsapps.com/start   # SSO portal URL
sso_region = ap-southeast-2                         # Region where SSO is configured
sso_registration_scopes = sso:account:access        # Required scope

Common Role Names

Standard AWS managed roles include:

• AdministratorAccess - Full access to all services
• ReadOnlyAccess - Read-only access to all services
• PowerUserAccess - Full access except IAM permissions
• Custom roles defined by your organization