AWS SSO / IAM Identity Center CLI Login

IAM Identity Center (formerly AWS SSO) gives you short-lived, auto-refreshing credentials instead of long-lived access keys. You log in once with aws sso login, and both SDKs use the result.

Summary

IAM Identity Center is AWS's single sign-on service for workforce access across accounts. It replaces static keys with browser-based login.

You configure it once with aws configure sso, which writes an sso-session and a profile into ~/.aws/config. No secret key is ever stored on disk.

Running aws sso login opens a browser, you approve the device, and the CLI caches a short-lived SSO token. From that token it fetches temporary role credentials.

boto3 and the AWS SDK for JavaScript v3 read the same SSO profile from the shared config. When their credentials expire, they refresh from the cached SSO token automatically.

This is the recommended setup for any team or organization. Long-lived keys should be a last resort.

Recipe

Configure once, then log in whenever your session expires.

# One-time interactive setup - writes ~/.aws/config
aws configure sso
# SSO start URL: https://my-org.awsapps.com/start
# SSO region: us-east-1
# then pick an account + role, and name the profile (e.g. "dev-sso")
 
# Log in (opens a browser); refresh this when the session expires
aws sso login --profile dev-sso
 
# Verify
aws sts get-caller-identity --profile dev-sso

When to reach for this:

• Your company uses IAM Identity Center or an external IdP wired into it.
• You want to stop storing long-lived access keys on laptops.
• You need access to several accounts and roles behind one login.
• You want credentials that expire automatically instead of living forever.

Working Example

After aws sso login, both SDKs use the SSO profile with no keys in code.

The profile it wrote looks like this:

# ~/.aws/config
[sso-session my-org]
sso_start_url = https://my-org.awsapps.com/start
sso_region = us-east-1
sso_registration_scopes = sso:account:access
 
[profile dev-sso]
sso_session = my-org
sso_account_id = 111111111111
sso_role_name = DeveloperAccess
region = us-east-1
output = json

Now the SDK code:

# --- Python (boto3) ---
import boto3
 
# Uses the SSO profile; boto3 reads the cached SSO token and
# fetches short-lived role credentials automatically.
session = boto3.Session(profile_name="dev-sso")
sts = session.client("sts")
 
identity = sts.get_caller_identity()
print("SSO identity:", identity["Arn"])

// --- TypeScript (AWS SDK v3) ---
import { fromSSO } from "@aws-sdk/credential-providers";
import { STSClient, GetCallerIdentityCommand } from "@aws-sdk/client-sts";
 
// Uses the SSO profile; v3 reads the cached SSO token and
// fetches short-lived role credentials automatically.
const sts = new STSClient({
  region: "us-east-1",
  credentials: fromSSO({ profile: "dev-sso" }),
});
 
const identity = await sts.send(new GetCallerIdentityCommand({}));
console.log("SSO identity:", identity.Arn);

What this demonstrates:

• boto3 resolves an SSO profile transparently through the default chain when you name the profile.
• v3 uses the fromSSO provider from @aws-sdk/credential-providers to resolve the same profile.
• Neither snippet holds a secret; the credentials come from the cached SSO login.
• If the SSO session has expired, the call fails until you re-run aws sso login.

Deep Dive

How It Works

• aws configure sso records where to log in (the sso-session) and which account/role a profile maps to.
• aws sso login performs the OAuth device-authorization flow in a browser and caches an SSO token under ~/.aws/sso/cache/.
• When a tool needs credentials, it exchanges that token for temporary role credentials via the sso:GetRoleCredentials API.
• Those role credentials are short-lived; the SDKs re-fetch them from the still-valid SSO token without a new browser step.
• When the SSO token itself expires, any request fails until the next aws sso login.

sso-session vs Legacy SSO Profiles

Modern setup uses a shared [sso-session ...] block that multiple profiles reference.

• The sso-session centralizes the start URL and SSO region so many account/role profiles reuse one login.
• Legacy profiles embedded sso_start_url and sso_region directly in each profile block; those still work but are being phased out.
• Prefer the sso-session form - one login covers every profile that points at it.

Useful SSO Commands

Gotchas

• Session expired mid-work - Calls suddenly fail with an SSO token error after hours of use. Fix: run aws sso login --profile <p> again; the token has a limited lifetime.
• v3 needs the SSO provider - A v3 client that does not use fromSSO (or set the profile via AWS_PROFILE) may not resolve an SSO profile. Fix: use fromSSO({ profile }) or set AWS_PROFILE and let the default chain resolve it.
• Old AWS CLI v1 - SSO login support and the sso-session format require AWS CLI v2. Fix: upgrade to v2; v1 is end-of-support.
• Missing region on v3 client - fromSSO supplies credentials, not the client region. Fix: set region on the client or AWS_REGION.
• Wrong account/role in the profile - sso_account_id or sso_role_name typos yield authorization failures even after a successful login. Fix: re-run aws configure sso and pick from the presented list.
• Assuming credentials are permanent - SSO role credentials are temporary; caching them in a long-running process without refresh eventually breaks. Fix: let the SDK resolve through the profile so it can refresh, rather than copying keys out.

Alternatives

FAQs

aws sso logout

Related

• The AWS CLI as the SDK's Shared Credential Backbone - why SSO profiles reach your SDK code.
• Named Profiles & Multi-Account Config - profiles and role assumption alongside SSO.
• Environment Variables vs Config File Precedence - where SSO sits in the resolution order.
• AWS CLI Setup Best Practices - why short-lived SSO beats static keys.

Stack versions: This page was written for the AWS CLI v2, boto3 1.43.x (Python 3.10+), and the AWS SDK for JavaScript v3 (Node.js 18+).