Right, let’s talk about aws configure sso. This is the command that saves you from the dark ages of managing IAM user access keys, which are basically a permanent security liability you have to stash somewhere safe. With AWS SSO, you log in once through a pretty portal, get temporary, scoped-down credentials, and the CLI handles the rest. It’s a vastly more secure and manageable way to do things. The first time you run it, it feels a bit like magic. The second time, you’ll wonder why all cloud auth isn’t this (relatively) sane.

Here’s the kicker: this isn’t your grandpa’s aws configure. That old command was for IAM users and their eternal keys. This is a different beast entirely. It sets up a named profile in your ~/.aws/config file that knows how to go through the SSO login dance to get those sweet, short-lived credentials.

The Initial Setup Dance

You’ll need a few things before you start: the SSO start URL (which your admin gives you, it looks like https://my-sso-portal.awsapps.com/start), the AWS Region where your SSO instance is deployed (e.g., us-east-1), and the name of the AWS account and permission set you want to access.

You run the command, and it becomes a conversational wizard. It’ll ask for these details and then pop open your default browser to authenticate you. The CLI isn’t actually logging you in; it’s handing off the heavy lifting to your browser where you can handle multi-factor authentication and identity provider logins like a civilized human. Once you approve it there, the CLI gets the green light and writes the configuration for you.

$ aws configure sso
SSO session name (Recommended): my-sso-session
SSO start URL [https://my-sso-portal.awsapps.com/start]:
SSO Region [us-east-1]:
SSO registration scopes [sso:account:access]:
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.us-east-1.amazonaws.com/

Then enter the code:

ABCD-EFGH

At this point, you complete the login in your browser. Once successful, the CLI continues:

There are 3 AWS accounts available to you.
> Account: AWS-Dev (123456789012)
  Account: AWS-Prod (210987654321)
  Account: Security-Tooling (987654321234)
Using the account ID 123456789012
There are 4 permission sets available to you.
> ReadOnlyAccess
  DeveloperPowerUser
  NetworkAdmin
  DatabaseAdmin
Using the permission set DeveloperPowerUser
CLI default client Region [None]: us-west-2
CLI default output format [None]: json
CLI profile name [DeveloperPowerUser-123456789012]: dev-profile

To use this profile, specify the profile name using --profile, as shown:

aws s3 ls --profile dev-profile

What Actually Got Configured?

Run this wizard once, and it does two key things. First, it creates a sso-session section in your shared ~/.aws/config file. This stores the details for the SSO portal itself. Then, it creates a profile that references that sso-session and specifies which account and role you want to assume. This separation is brilliant because you can define the SSO portal once and create multiple profiles that point to it for different accounts and roles.

Here’s what it added to my config file:

# ~/.aws/config
[sso-session my-sso-session]
sso_start_url = https://my-sso-portal.awsapps.com/start
sso_region = us-east-1
sso_registration_scopes = sso:account:access

[profile dev-profile]
sso_session = my-sso-session
sso_account_id = 123456789012
sso_role_name = DeveloperPowerUser
region = us-west-2
output = json

See how clean that is? The dev-profile just points to the SSO session and says “use this to get access to this account with this role.” All the authentication state is managed separately.

The Annoying, Absolutely Critical Gotcha: The Login Token

Here’s the part they don’t always emphasize enough: those temporary credentials have a maximum lifetime, usually an hour. When they expire, the AWS CLI can’t just magically renew them itself. It needs you to re-authenticate. But it can’t just open a browser willy-nilly.

This is where aws sso login comes in. To refresh your credentials, you must run:

aws sso login --profile dev-profile

This will again open a browser (or give you a device code) to log you in and refresh the credentials cached in ~/.aws/sso/cache. This is the most common “it’s not working!” pitfall. Your commands start failing with auth errors? Your first instinct should be to run aws sso login. Not aws configure sso again—that’s for the initial setup. You log in with aws sso login.

Best Practices for the Real World

  1. Profile Names: Use intuitive profile names. DeveloperPowerUser-123456789012 is what the CLI suggests, but it’s garbage. Name it after the account’s purpose, like dev-profile or prod-readonly. You’ll thank yourself later.
  2. The AWS_DEFAULT_PROFILE Environment Variable: Instead of typing --profile dev-profile on every command, you can set export AWS_DEFAULT_PROFILE=dev-profile in your shell session. This makes all subsequent commands use that profile by default.
  3. Scripting with SSO: This is the rough edge. SSO profiles are designed for human interaction. They are not great for scripts running in CI/CD pipelines or on servers, because there’s no headless browser for the login flow. For automation, you’ll still need to use IAM roles or IAM users with access keys, which is a shame. The designers made a choice for user security over script convenience, which is the right call, but it does leave a gap.
  4. The Cache Directory: Don’t mess with the ~/.aws/sso/cache directory. But know it exists. If you ever get into a weird state where logins are failing, sometimes nuking this cache (rm -rf ~/.aws/sso/cache) and doing a fresh aws sso login can solve bizarre issues. It’s the “turn it off and on again” of AWS SSO.