Infra Notes

AWS SSO login: configure and verify a CLI profile

Configure an AWS CLI SSO profile, sign in with IAM Identity Center, select the correct account and role, and verify the active identity before running commands.

Published · Updated

AWSAWS SSOIAM Identity CenterAWS CLIProfile

Problem

You configured AWS SSO, but the AWS CLI still uses the wrong account, role, Region, or credential source. This usually happens when the profile used for aws sso login is different from the profile used by the next command.

AWS SSO is now called AWS IAM Identity Center, but the AWS CLI commands and configuration keys still use the sso name.

Quick answer

Create a named profile once, log in with that exact profile, and verify the caller identity before running any infrastructure command:

bash

aws configure sso --profile sandbox-sso
aws sso login --profile sandbox-sso
aws sts get-caller-identity --profile sandbox-sso

The final command should return the expected AWS account ID and an ARN for the selected role. If either value is unexpected, stop before running Terraform, deployment, or administrative commands.

Prerequisites

  • AWS CLI version 2 is installed
  • Your organization has enabled IAM Identity Center
  • Your user has access to at least one AWS account and permission set
  • You know the IAM Identity Center start URL or issuer URL and its Region

Check the installed CLI version:

bash

aws --version

Configure an AWS SSO profile

Run the interactive configuration wizard with an explicit profile name:

bash

aws configure sso --profile sandbox-sso

The wizard asks for an SSO session name, start URL, SSO Region, AWS account, role, default client Region, output format, and profile name. Use a descriptive profile name such as sandbox-sso, staging-readonly, or production-admin.

A modern ~/.aws/config entry generated by the wizard looks similar to this:

ini

[profile sandbox-sso]
sso_session = company-sso
sso_account_id = 123456789012
sso_role_name = ReadOnlyAccess
region = ap-southeast-1
output = json

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

The profile selects the AWS account, permission-set role, default Region, and output format. The reusable sso-session section contains the settings used to obtain and refresh the SSO token.

Do not put SSO access tokens or temporary credentials into this file manually. The AWS CLI obtains and caches them after browser authentication.

Log in with the same profile

Authenticate using the profile you just created:

bash

aws sso login --profile sandbox-sso

The CLI normally opens a browser for authentication. For a device where that flow is unsuitable, follow the URL and instructions printed by the CLI. A session can remain usable until its IAM Identity Center authentication expires; after that, run the login command again.

Verify the active AWS account and role

Always verify the identity before making changes:

bash

aws sts get-caller-identity --profile sandbox-sso

Example response:

json

{
  "UserId": "AROAXAMPLE:username",
  "Account": "123456789012",
  "Arn": "arn:aws:sts::123456789012:assumed-role/ReadOnlyAccess/username"
}

Check both values:

  • Account must match the intended AWS account ID
  • Arn must contain the expected role or permission-set name

sts get-caller-identity returns the identity whose credentials are active, making it a useful safety check even when you do not yet need to call another AWS service.

Use the profile for subsequent commands

Choose one of these patterns and use it consistently.

Pass the profile to each command:

bash

aws s3 ls --profile sandbox-sso
aws eks list-clusters --profile sandbox-sso

Or set it for the current shell session:

bash

export AWS_PROFILE=sandbox-sso
aws sts get-caller-identity
aws s3 ls

An explicit command-line --profile applies to that command and is easier to audit in shell history. AWS_PROFILE is convenient for a sequence of commands, but remember that it remains active in the current shell until it is changed or unset.

bash

unset AWS_PROFILE

Inspect available profiles and configuration

List profile names known to the AWS CLI:

bash

aws configure list-profiles

Inspect which profile, credential source, and Region the CLI currently resolves:

bash

aws configure list --profile sandbox-sso

These commands help distinguish a missing profile from a valid profile that points to the wrong account or Region.

Common AWS SSO profile errors

The config profile could not be found

The profile name passed to --profile does not match a section in ~/.aws/config.

bash

aws configure list-profiles
aws configure sso --profile sandbox-sso

Remember that the file contains [profile sandbox-sso], while the command uses only --profile sandbox-sso.

The SSO session has expired or is invalid

Renew the browser session, then verify the identity again:

bash

aws sso login --profile sandbox-sso
aws sts get-caller-identity --profile sandbox-sso

The command uses the wrong AWS account

Check for a different --profile, an existing AWS_PROFILE value, or other AWS credential environment variables in the current shell. Then rerun get-caller-identity with the intended profile explicitly.

bash

env | grep '^AWS_'
aws sts get-caller-identity --profile sandbox-sso

Avoid printing or sharing the values of credential variables such as access keys, secret keys, or session tokens.

The browser does not open

Use the authorization URL printed by the CLI, or use the device authorization option when required by your environment:

bash

aws configure sso --profile sandbox-sso --use-device-code

The Region is wrong

The SSO Region identifies where IAM Identity Center is configured. The profile's region is the default Region for service commands. They can be different, so verify both values in ~/.aws/config.

Sign out

When using a shared or sensitive workstation, clear locally cached IAM Identity Center sessions:

bash

aws sso logout

This signs out cached SSO sessions, not only one named profile.

Recommended workflow

bash

# Configure once
aws configure sso --profile sandbox-sso

# Repeat when the SSO session expires
aws sso login --profile sandbox-sso

# Verify before every sensitive operation
aws sts get-caller-identity --profile sandbox-sso

# Run the intended command explicitly
aws s3 ls --profile sandbox-sso

Use one clearly named profile per account and access level. Names such as production-readonly and production-admin make accidental privilege or environment selection easier to notice than generic names such as aws-sso or default.

When not to use this pattern

Interactive AWS SSO profiles are designed for people working from local terminals. For CI/CD, workloads, and other non-interactive automation, use an appropriate IAM role or workload identity instead of scripting a browser-based SSO login or storing long-lived IAM user keys.

References