AWS
Security
Tutorials
How to Set Up AWS CLI with IAM Identity Center (2026)
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.AWS IAM Identity Center (renamed from AWS Single Sign-On in July 2022 per AWS announcement) centralizes SSO access to multiple AWS accounts. 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.
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.
Frequently Asked Questions #
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.Want help getting started? Join the CloudQuery community or contact our team.
