AWS
Security
Tutorials
Set Up AWS CLI with SSO (IAM Identity Center) — Step by Step
TL;DR:
Use
aws configure sso with the sso-session format (CLI v2.22.0+) to get automatic token refresh across multiple AWS accounts. One login grants access to all accounts sharing the same SSO session, and CloudQuery Platform reads the same credentials without extra setup.How to Configure AWS CLI with SSO in 5 Steps #
The complete setup takes under 5 minutes once IAM Identity Center is enabled in your AWS account.
- Enable IAM Identity Center — An AWS admin enables the service in your organization and connects it to your Identity Provider (Okta, Microsoft Entra ID, or Google Workspace).
- Install AWS CLI v2.22.0+ — Run
aws --versionto confirm. Download from aws.amazon.com/cli if needed. - Run
aws configure sso— The CLI prompts for your SSO start URL, region, and a session name. It opens a browser window for authentication. - Set your CLI profile — After authenticating, select an AWS account and role. The CLI writes an
sso-sessionblock and aprofileblock to~/.aws/config. - Test with
aws sso login— Runaws sso login --sso-session my-ssoto confirm access. All profiles sharing that session are now active.
For multi-account setups, add additional profiles that reference the same
sso-session — you log in once and access all accounts. Full details for each step are below.AWS IAM Identity Center (renamed from AWS Single Sign-On in July 2022 per AWS announcement) centralizes SSO access to multiple AWS accounts. For a deeper look at how Identity Center fits into your AWS access architecture, see our complete AWS IAM Identity Center guide. It moves authentication to your Identity Provider (IdP) and removes the need for static, long-lived access keys.
AWS CLI v2 supports IAM Identity Center natively. With the recommended
sso-session configuration (available since CLI v2.22.0), you get automatic token refresh and can work across multiple accounts without re-authenticating for each one.Note: AWS still uses
sso in CLI commands and configuration keys for backward compatibility. If you see references to "AWS SSO" in older guides, they refer to the same service now called IAM Identity Center.What Are the Prerequisites? #
How Do You Set Up IAM Identity Center with an IdP? #
Before configuring the CLI, someone with admin access needs to enable IAM Identity Center and connect it to an external Identity Provider. AWS supports SAML 2.0 and SCIM with the following IdPs, among others:
- Okta: Supports both SAML authentication and SCIM automatic provisioning of users and groups. See the AWS guide for Okta integration.
- Microsoft Entra ID (formerly Azure AD): Supports SAML and SCIM for users and groups. See the AWS guide for Microsoft Entra ID.
- Google Workspace: Supports SAML and SCIM for user provisioning (group provisioning is not supported). See the AWS guide for Google Workspace.
If you use Google Workspace, we have a detailed walkthrough: AWS SSO Tutorial with Google Workspace as an IdP.
After connecting your IdP, create permission sets in IAM Identity Center and assign them to users or groups for each AWS account they need to access.
How Do You Install AWS CLI v2? #
Install AWS CLI v2 on your local machine. The SSO session features require version 2.22.0 or later. Verify your version:
aws --version
# aws-cli/2.x.x Python/3.x.x ...
How Do You Configure an SSO Profile? #
Run
aws configure sso to create an SSO session and profile interactively. This is the recommended approach because it creates an sso-session block that supports automatic token refresh.aws configure sso
The CLI prompts you for the following values:
SSO session name (Recommended): my-sso
SSO start URL [None]: https://your-org.awsapps.com/start
SSO region [None]: us-east-1
SSO registration scopes [None]: sso:account:access
- SSO session name: A label for this session. Multiple profiles can share the same session.
- SSO start URL: Your IAM Identity Center portal URL (or the issuer URL, which works interchangeably since CLI v2.22.0).
- SSO region: The AWS region where IAM Identity Center is enabled.
- SSO registration scopes: Use
sso:account:accessto allow the CLI to list accounts and roles.
The CLI then opens your browser for authentication (using PKCE authorization by default in v2.22.0+):
After you authenticate, the CLI lists the AWS accounts available to you:
There are 6 AWS accounts available to you.
Using the account ID xxxxxxxxxxxx
The only role available to you is: AdministratorAccess
Using the role name "AdministratorAccess"
CLI default client Region [None]: us-east-1
CLI default output format [None]: json
CLI profile name [AdministratorAccess-xxxxxxxxxxxx]: cq-dev-admin
Test the profile:
aws s3 ls --profile cq-dev-admin
What Does the sso-session Configuration Look Like? #
The
aws configure sso command writes two blocks to ~/.aws/config: the sso-session block (shared connection details) and the profile block (account-specific settings). This is the recommended format per AWS docs:[sso-session my-sso]
sso_start_url = https://your-org.awsapps.com/start
sso_region = us-east-1
sso_registration_scopes = sso:account:access
[profile cq-dev-admin]
sso_session = my-sso
sso_account_id = xxxxxxxxxxxx
sso_role_name = AdministratorAccess
region = us-east-1
output = json
What About the Legacy Configuration Format? #
Older guides may show a format where each profile contains
sso_start_url and sso_region directly, without an sso-session block:# Legacy format - does NOT support automatic token refresh
[profile cq-dev-admin]
sso_start_url = https://your-org.awsapps.com/start
sso_region = us-east-1
sso_account_id = xxxxxxxxxxxx
sso_role_name = AdministratorAccess
This legacy format still works but does not support automatic token refresh. We recommend migrating to the
sso-session format. You can do this by running aws configure sso again or by editing ~/.aws/config manually.How Do You Manage Multiple AWS Accounts? #
One of the most useful features of IAM Identity Center is that a single login grants access to all accounts that share the same SSO session. Add additional profiles that reference the same
sso-session:[sso-session my-sso]
sso_start_url = https://your-org.awsapps.com/start
sso_region = us-east-1
sso_registration_scopes = sso:account:access
[profile cq-dev-admin]
sso_session = my-sso
sso_account_id = 111111111111
sso_role_name = AdministratorAccess
region = us-east-1
[profile cq-staging-readonly]
sso_session = my-sso
sso_account_id = 222222222222
sso_role_name = ReadOnlyAccess
region = us-west-2
[profile cq-prod-deploy]
sso_session = my-sso
sso_account_id = 333333333333
sso_role_name = PowerUserAccess
region = us-east-1
Log in once:
aws sso login --sso-session my-sso
Then use any profile without logging in again:
aws s3 ls --profile cq-dev-admin
aws ec2 describe-instances --profile cq-staging-readonly
aws ecs list-clusters --profile cq-prod-deploy
You can also log in by profile name:
aws sso login --profile cq-dev-admin
How Does Token Caching Work? #
The CLI caches authentication tokens in
~/.aws/sso/cache/. Key details from the AWS docs:- With the sso-session format, the access token is checked hourly and refreshed automatically using a refresh token. This means you typically log in once at the start of your workday.
- With the legacy format, there is no automatic refresh. You must run
aws sso logineach time the token expires. - The permission set session duration (set by your admin) controls how long CLI credentials are valid per role, with a minimum of 1 hour and maximum of 12 hours. The default is 1 hour.
- The IAM Identity Center portal session controls how long you stay authenticated overall, with a default of 8 hours and maximum of 90 days.
How Do You Troubleshoot Common Issues? #
"Token has expired and refresh failed" #
This is the most common error. It means your SSO session or refresh token has expired. To fix it:
aws sso login --sso-session my-sso
If you are using the legacy configuration format, you will see this error more frequently because automatic token refresh is not available. Migrating to the
sso-session format (see above) significantly reduces how often this happens.Clearing the Token Cache #
If login fails unexpectedly, corrupted cached credentials may be the cause. Clear the cache and try again:
rm -rf ~/.aws/sso/cache/*
aws sso login --sso-session my-sso
Browser Does Not Open During Login #
If
aws sso login does not open a browser (common in headless environments or SSH sessions), use the --use-device-code flag to get a URL and code you can enter on any device with a browser:aws sso login --sso-session my-sso --use-device-code
Wrong Account or Role Listed #
If
aws configure sso does not show the expected accounts or roles, confirm with your IAM Identity Center admin that your user or group has been assigned the correct permission sets for those accounts.AWS CLI Version Too Old #
SSO session features require CLI v2.22.0 or later. If you see errors about unrecognized
sso-session configuration, update your CLI:aws --version
# If below 2.22.0, update: https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html
How Do You Log Out? #
Run
aws sso logout to clear all cached SSO tokens:aws sso logout
This invalidates all sessions and profiles. In practice, you rarely need to log out manually because tokens expire based on the session duration configured by your admin.
AWS IAM Identity Center vs AWS SSO — What Changed and What Stayed the Same #
In July 2022, AWS renamed AWS Single Sign-On (AWS SSO) to AWS IAM Identity Center. The name change was purely cosmetic — the underlying service, its API, and all CLI commands are identical. If you followed guides written before 2022 that reference "AWS SSO," they still apply today.
Here is a quick reference for what stayed the same despite the rename:
AWS kept the
sso keyword in all CLI commands and configuration files for backward compatibility. Scripts and pipelines written for AWS SSO work without modification. The IAM Identity Center console URL changed, but the sso_start_url value you configured before the rename still resolves correctly.Why did AWS rename it? The name "Single Sign-On" described only one dimension of the service. IAM Identity Center also manages permissions, access assignments, and multi-account access — capabilities that single sign-on alone doesn't capture. The new name reflects the service's role as a centralized identity hub for AWS organizations.
If you are setting up the AWS CLI for the first time in 2026, use "IAM Identity Center" when navigating the AWS Console, but continue using
aws sso login, aws configure sso, and sso_start_url in your CLI configuration — exactly as shown throughout this guide.How Do You Use SSO Credentials with CloudQuery? #
If you use CloudQuery Platform to sync AWS resources, your SSO credentials work without any extra setup. Set the
AWS_PROFILE environment variable to your SSO profile name:export AWS_PROFILE=cq-dev-admin
aws sso login --sso-session my-sso
cloudquery sync aws.yml
CloudQuery reads credentials from the same
~/.aws/config and ~/.aws/sso/cache/ files that the AWS CLI uses. This means you get the same short-lived credentials and automatic token refresh without managing static access keys.For multi-account syncs, you can configure CloudQuery to assume roles across accounts, all authenticated through your single SSO session. See the CloudQuery AWS source integration docs for details on multi-account configuration.
Sync AWS Resources with IAM Identity Center
CloudQuery Platform reads IAM Identity Center credentials directly from your AWS CLI configuration — no static keys needed. Connect multiple AWS accounts through one SSO session.
Frequently Asked Questions #
What Does aws configure sso Do? #
The
aws configure sso command creates an IAM Identity Center (formerly AWS SSO) session and profile in your ~/.aws/config file. It prompts for your SSO start URL, AWS region, and registration scopes, then opens a browser window for authentication. After setup, running aws sso login --profile <name> authenticates you and caches an SSO access token for that session. When you run AWS CLI commands with an SSO profile, the CLI retrieves temporary role credentials for the configured account and role as needed. The sso-session format used by CLI v2.22.0+ supports automatic token refresh, so you stay authenticated without re-running aws sso login for each account.Does AWS SSO Still Exist? #
Yes, but it was renamed to IAM Identity Center in July 2022. The CLI still uses
sso in commands and configuration keys for backward compatibility.Do I Need AWS CLI v2 for SSO? #
Yes. SSO support is only available in AWS CLI v2. The
sso-session format with automatic token refresh requires v2.22.0 or later.Can I Use SSO Credentials with Terraform? #
Yes. Set
AWS_PROFILE to your SSO profile name, run aws sso login, and Terraform will pick up the credentials from ~/.aws/config and the cached SSO tokens. No static access keys needed.How Often Do I Need to Re-Authenticate? #
With the
sso-session format, the CLI refreshes tokens automatically. You typically log in once per workday. The portal session duration (set by your admin) can be up to 90 days.Can I Use SSO with CI/CD Pipelines? #
SSO is designed for interactive use because it requires browser-based authentication. For CI/CD, AWS recommends using IAM roles with OIDC federation (for GitHub Actions, GitLab CI, etc.) or IAM roles for service accounts rather than SSO profiles.
How Do I Switch Between Multiple SSO Organizations? #
Create separate
sso-session blocks in ~/.aws/config, each with a different sso_start_url and session name. Then reference the appropriate session in each profile. You can be logged into multiple sessions simultaneously.Does CloudQuery Work with SSO Credentials? #
Yes. Set
AWS_PROFILE to your SSO profile name and CloudQuery reads the same cached credentials as the AWS CLI. No additional credential configuration is needed. See the CloudQuery AWS source integration docs for multi-account setup.What replaced AWS SSO? #
Nothing replaced AWS SSO — it was renamed to AWS IAM Identity Center in July 2022. The service, its features, and all CLI commands remain exactly the same. The
aws sso login, aws sso logout, and aws configure sso commands still work as they always did. The change was a rebranding to better reflect the service's role as a centralized identity and permissions hub for AWS organizations, not a product replacement.How do I configure AWS CLI with IAM Identity Center in 2026? #
Run
aws configure sso and follow the prompts: enter your IAM Identity Center start URL (found in the AWS Console under IAM Identity Center → Settings), your SSO region, and a session name. The CLI opens a browser for authentication and writes an sso-session block and a profile block to ~/.aws/config. Use CLI v2.22.0 or later to get automatic token refresh via the sso-session format. After setup, run aws sso login --sso-session <session-name> to authenticate and start using your SSO profiles.What is the aws configure sso command? #
aws configure sso is the AWS CLI v2 command that creates an IAM Identity Center (formerly AWS SSO) session and profile in your ~/.aws/config file. It prompts for your SSO start URL, AWS region, registration scopes, and a session name, then opens a browser window for interactive authentication. The result is a reusable SSO session that supports automatic token refresh — so you authenticate once and stay logged in for the duration of your portal session (up to 90 days depending on your administrator's settings).Is aws sso login still the right command to use? #
Yes.
aws sso login is the correct command in 2026. Despite the service being renamed to IAM Identity Center in 2022, AWS kept all CLI commands using the sso keyword for backward compatibility. There is no aws iam-identity-center login command. Use aws sso login --sso-session <session-name> to authenticate with the sso-session format, or aws sso login --profile <profile-name> to log in by profile.Do I need to reconfigure my AWS CLI after the IAM Identity Center rename? #
No. The rename from AWS SSO to IAM Identity Center in 2022 had no effect on existing CLI configurations. Your
~/.aws/config file, your sso_start_url values, your sso-session blocks, and your profile settings all continue to work without any changes. If your CLI is configured and working, there is nothing to update. The only change that might affect you is navigating the AWS Console, where the service now appears under "IAM Identity Center" instead of "Single Sign-On."What is the difference between aws sso login and aws sso login --sso-session? #
aws sso login without --sso-session logs in using a legacy profile-based method. aws sso login --sso-session <name> uses the newer sso-session format (introduced in CLI v2.22.0), which supports automatic token refresh across all profiles that share the session. If you are using the sso-session block format in ~/.aws/config, use the --sso-session flag. If your configuration uses the older sso_start_url directly on a profile (no separate sso-session block), use --profile instead.How do you troubleshoot "Error loading SSO Token" in AWS CLI? #
This error typically means your SSO token has expired or is missing from the cache. Run
aws sso login --sso-session <session-name> to re-authenticate. If the error persists, clear the cache at ~/.aws/sso/cache/ and try again. Check that the sso_start_url in your ~/.aws/config matches exactly what your AWS administrator provided — a mismatch here is a common cause. On shared machines, verify that the cache directory has the correct file permissions.