🪴 Anil's Garden

AWS Authentication with IAM Identity Centre (Single Sign-On or SSO) - Claude

23 Nov 20257 min read

AWS SSO Configuration Guide

What is AWS SSO?

AWS Single Sign-On (now called AWS IAM Identity Center) allows you to authenticate once and access multiple AWS accounts without managing individual IAM users and access keys in each account. It’s more secure than long-lived access keys and is the recommended authentication method for organizations.

Prerequisites

Before using aws configure sso, you need:

  1. Your SSO start URL (provided by your AWS administrator)
  2. Your SSO region (where Identity Center is configured, e.g., eu-west-1)
  3. AWS CLI version 2.x (SSO support requires v2)

Basic Setup

Step 1: Initiate SSO Configuration

aws configure sso

You’ll be prompted for several pieces of information:

Step 2: Answer the Prompts

SSO session name (Recommended): my-sso
SSO start URL [None]: https://my-company.awsapps.com/start
SSO region [None]: eu-west-1
SSO registration scopes [None]: sso:account:access

Explanation of prompts:

SSO session name: A friendly name for this SSO session (new in AWS CLI v2.9+). This allows credential sharing across profiles. Examples: my-company, work, production-sso

SSO start URL: The portal URL where you log in. It looks like:

  • https://d-xxxxxxxxxx.awsapps.com/start (AWS-hosted)
  • https://my-company.awsapps.com/start (custom domain)
  • Get this from your AWS administrator or the email invitation

SSO region: The AWS region where IAM Identity Center is configured (NOT necessarily where your resources are). Common: us-east-1, eu-west-1, us-west-2

SSO registration scopes: Usually just press Enter to accept default (sso:account:access)

Step 3: Browser Authentication

After entering the above, the CLI will:

  1. Open your default web browser automatically
  2. Show you a code to verify (or auto-confirm)
  3. Prompt you to sign in via your organization’s identity provider (Okta, Azure AD, Google Workspace, etc.)
  4. Ask for permission to allow AWS CLI access

In the terminal, you’ll see:

Attempting to automatically open the SSO authorization page in your default browser.
If the browser does not open or you wish to use a different device to authorize this request, open the following URL:

https://device.sso.eu-west-1.amazonaws.com/

Then enter the code: XXXX-XXXX

In the browser:

  • Confirm the code matches
  • Sign in with your corporate credentials
  • Click “Allow” to grant CLI access

Step 4: Select Account and Role

After successful authentication, the CLI lists available accounts:

There are X AWS accounts available to you.
Using the account ID 123456789012
The only role available to you is: AdministratorAccess
Using the role name "AdministratorAccess"

If you have multiple accounts/roles, you’ll be prompted to choose:

> Account1 (123456789012)
  Account2 (210987654321)
  Account3 (555555555555)

Available roles:
> AdministratorAccess
  DataScientist
  ReadOnly

Step 5: Configure Default Region and Output

CLI default client Region [None]: eu-west-2
CLI default output format [None]: json

Default region: Where AWS CLI commands will execute by default (where your resources are) Output format: json, yaml, text, or table

Step 6: Choose Profile Name

CLI profile name [AdministratorAccess-123456789012]: my-dev-profile

This is the profile name you’ll use with --profile flag or AWS_PROFILE environment variable.

What Gets Created

The configuration is saved in two files:

~/.aws/config

[profile my-dev-profile]
sso_session = my-sso
sso_account_id = 123456789012
sso_role_name = AdministratorAccess
region = eu-west-2
output = json
 
[sso-session my-sso]
sso_start_url = https://my-company.awsapps.com/start
sso_region = eu-west-1
sso_registration_scopes = sso:account:access

~/.aws/sso/cache/ (directory) Contains cached credentials (temporary tokens) valid for several hours.

Using Your SSO Profile

Login to SSO

Before first use (or when credentials expire), login:

aws sso login --profile my-dev-profile

This opens the browser for authentication. Credentials are cached locally for ~8-12 hours (configurable by admin).

Alternative with SSO sessions (CLI v2.9+):

aws sso login --sso-session my-sso

This logs you into the SSO session, allowing all profiles using that session to share credentials.

Run AWS Commands

With profile flag:

aws s3 ls --profile my-dev-profile
aws ec2 describe-instances --profile my-dev-profile

With environment variable:

export AWS_PROFILE=my-dev-profile
aws s3 ls
aws ec2 describe-instances

With SDK (Python example):

import boto3
 
# Explicitly specify profile
session = boto3.Session(profile_name='my-dev-profile')
s3 = session.client('s3')
 
# Or set environment variable AWS_PROFILE=my-dev-profile before running
s3 = boto3.client('s3')  # Automatically uses default/env profile

Check Login Status

# List cached credentials
aws sso list-accounts --profile my-dev-profile
 
# Or check if logged in
aws sts get-caller-identity --profile my-dev-profile

If credentials expired:

Error: The SSO session associated with this profile has expired or is invalid.
To refresh this SSO session run aws sso login with the corresponding profile.

Logout

aws sso logout --profile my-dev-profile
 
# Or logout from entire SSO session
aws sso logout --sso-session my-sso

This deletes cached credentials.

Multiple Profiles for Different Accounts/Roles

You can configure multiple profiles for different accounts or roles:

# Profile 1: Dev account
aws configure sso --profile dev
# (Enter dev account details)
 
# Profile 2: Production account
aws configure sso --profile prod
# (Enter prod account details)
 
# Profile 3: Same account, different role
aws configure sso --profile data-science
# (Same account, but choose DataScientist role)

Resulting ~/.aws/config:

[profile dev]
sso_session = my-sso
sso_account_id = 111111111111
sso_role_name = AdministratorAccess
region = eu-west-2
 
[profile prod]
sso_session = my-sso
sso_account_id = 222222222222
sso_role_name = AdministratorAccess
region = eu-west-2
 
[profile data-science]
sso_session = my-sso
sso_account_id = 111111111111
sso_role_name = DataScientist
region = eu-west-2
 
[sso-session my-sso]
sso_start_url = https://my-company.awsapps.com/start
sso_region = eu-west-1
sso_registration_scopes = sso:account:access

Using different profiles:

aws s3 ls --profile dev
aws s3 ls --profile prod
aws s3 ls --profile data-science

After one aws sso login --sso-session my-sso, all three profiles work (CLI v2.9+).

Manual Configuration (Alternative)

You can also manually edit ~/.aws/config instead of using the interactive wizard:

nano ~/.aws/config
[profile my-profile]
sso_session = my-sso
sso_account_id = 123456789012
sso_role_name = AdministratorAccess
region = eu-west-2
output = json
 
[sso-session my-sso]
sso_start_url = https://my-company.awsapps.com/start
sso_region = eu-west-1
sso_registration_scopes = sso:account:access

Then login:

aws sso login --profile my-profile

Legacy SSO Configuration (CLI v2.0-2.8)

Older AWS CLI versions don’t support SSO sessions. Configuration looks like:

[profile my-profile]
sso_start_url = https://my-company.awsapps.com/start
sso_region = eu-west-1
sso_account_id = 123456789012
sso_role_name = AdministratorAccess
region = eu-west-2

Each profile must be logged into separately:

aws sso login --profile profile1
aws sso login --profile profile2

Recommendation: Update to CLI v2.9+ for better SSO session support.

Troubleshooting

”aws: command not found”

Install AWS CLI v2:

# macOS
brew install awscli
 
# Linux
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install

“SSO authorization page failed to open”

Manually open the URL shown and enter the code.

”Access denied” or “Invalid grant”

Your SSO session expired. Run:

aws sso login --profile my-profile

“Unable to locate credentials”

You haven’t logged in yet:

aws sso login --profile my-profile

Browser doesn’t open

Set environment variable:

export AWS_CLI_AUTO_PROMPT=on-partial
aws sso login --profile my-profile --no-browser

Then manually open the URL and enter the code.

Wrong account/role selected

Delete the profile from ~/.aws/config and run aws configure sso again, or manually edit the file to change sso_account_id and sso_role_name.

SSO vs Access Keys Comparison

FeatureSSOAccess Keys
Security✅ Temporary credentials (hours)❌ Long-lived (until rotated)
Rotation✅ Automatic❌ Manual
Revocation✅ Instant (admin control)❌ Must delete/deactivate
Multi-account✅ Easy switching❌ Need keys per account
Corporate IdP✅ Integrated❌ Separate
Best forHuman users, workstationsCI/CD, servers, automation

Recommendation: Use SSO for human access, use IAM roles (not access keys) for applications running on AWS, and use OIDC for CI/CD pipelines.

Best Practices

  1. Use SSO sessions (CLI v2.9+) to share credentials across profiles
  2. Name profiles clearly: dev-admin, prod-readonly, staging-deploy
  3. Set default profile: export AWS_PROFILE=dev in ~/.bashrc or ~/.zshrc
  4. Login at start of day: aws sso login when you begin work
  5. Logout when done: aws sso logout on shared/untrusted machines
  6. Never commit credentials: SSO tokens are in ~/.aws/sso/cache/ - add to .gitignore

Quick Reference

# Initial setup
aws configure sso
 
# Login (opens browser)
aws sso login --profile my-profile
 
# Login to SSO session (CLI v2.9+)
aws sso login --sso-session my-sso
 
# Use profile
aws s3 ls --profile my-profile
export AWS_PROFILE=my-profile
 
# Check identity
aws sts get-caller-identity --profile my-profile
 
# Logout
aws sso logout --profile my-profile
 
# List available accounts
aws sso list-accounts --profile my-profile
 
# Update profile configuration
aws configure sso --profile my-profile

Graph View

Backlinks