The AWS CLI in Practice: Profiles, SSO, Assume-Role & Fixing Credential Errors

You run one command — aws s3 ls — and the terminal answers with a wall of red: Unable to locate credentials. Or worse, it works, lists buckets happily, and only twenty minutes later do you realise those were production buckets and you meant to be in the sandbox account. The AWS CLI is the single most-used tool in a cloud engineer’s day, and almost none of its pain comes from the commands themselves. It comes from one deceptively simple question the CLI has to answer before every single call: who are you, and in which account? That answer is assembled from a chain of sources — command-line flags, environment variables, an assume-role hop, an SSO token, two dotfiles in ~/.aws, and, on a server, the instance’s own role — and the first source that produces a usable credential wins. Understand that chain and you can debug any credential error in under a minute. Ignore it and you will lose hours to a stale environment variable you exported last Tuesday.

This is a practitioner’s guide to the parts of the AWS CLI that actually break: the ~/.aws/config and ~/.aws/credentials files and every key they hold, named profiles, the credential provider chain and its exact precedence, SSO profiles backed by IAM Identity Center, assume-role profiles for cross-account work, the environment variables that quietly override everything, and the global options — --region, --output, pagination, --query, --dry-run — that shape every command. We treat credential errors the way an on-call engineer must: as a small set of symptom classes, each with a precise root cause you confirm with aws configure list and aws sts get-caller-identity, then fix. Every mechanism gets both the aws command and a Terraform equivalent where infrastructure is involved, and the reference tables are built to keep open in a second window while you work.

By the end you will stop guessing about identity. When a command fails you will know whether the CLI never found a credential, found the wrong one, found an expired one, or found a valid credential that simply isn’t allowed to do the thing you asked. You will set up a plain access-key profile, an SSO profile and an assume-role profile from scratch, prove each one with sts get-caller-identity, and read the credential chain the way it actually resolves rather than the way you assumed it did. That difference — knowing which source won — is the whole game.

What problem this solves

The AWS CLI hides a genuinely complex authentication and authorization system behind a two-word command. That abstraction is a gift right up until it breaks, and then the error message tells you almost nothing useful: Unable to locate credentials does not say which of eight credential sources it checked, and AccessDenied does not say whether you are the wrong identity or the right identity lacking a permission. The information you need is real and knowable, but it is spread across two config files, your shell environment, a token cache directory, and, on a server, the instance metadata service. If you do not know which of those the CLI consults, in what order, you burn time editing the wrong file.

What breaks without this knowledge is predictable and expensive. An engineer exports temporary keys into their shell to test something, forgets, and for the next week every --profile flag is silently ignored because static environment variables outrank profile files — they ship a change to the wrong account. A team rotates to IAM Identity Center but never learns that the SSO token expires every few hours, so every morning starts with a confusing ExpiredToken and a support ping. A CI job assumes a role but the source credentials it chains from have expired, producing an error that names the target role and sends everyone debugging the wrong policy. None of these are hard once you can see the chain; all of them are hours-long mysteries when you cannot.

Who hits this: everyone who touches AWS from a terminal, from a first-week junior running aws configure to the platform engineer wiring an assume-role graph across twelve accounts. It bites hardest on people juggling multiple accounts (the wrong-profile trap), teams migrating from long-lived IAM keys to SSO (the token-expiry surprise), and anyone running the CLI on EC2 or in a container (where the credential source is the instance role and the failure mode is metadata reachability, not a missing file). The fix is almost never “run aws configure again” — it is “find which link in the chain answered, and why.”

Here is the whole field in one frame: every credential symptom class this article covers, the question it forces, and the first command to run.

Learning objectives

By the end of this article you can:

• Install the AWS CLI v2 on macOS, Linux and Windows, verify the version, and keep it current — and explain why v2 (not v1) is the only sane choice for SSO.
• Read and hand-edit ~/.aws/config and ~/.aws/credentials, and say exactly which setting belongs in which file and why the [profile name] vs [name] header difference exists.
• Create and select named profiles with --profile and AWS_PROFILE, and predict which one a given command will actually use.
• Recite the credential provider chain in precedence order and use it to explain any “wrong credential” bug in one pass.
• Stand up an SSO profile with aws configure sso, understand the sso-session block, and refresh it with aws sso login.
• Build an assume-role profile with role_arn plus source_profile or credential_source, and wire in external_id, mfa_serial and duration_seconds correctly.
• Drive the global options fluently: --region, --output (json/table/text/yaml), pagination (--no-cli-pager, --max-items, --page-size), server-side --filters vs client-side --query JMESPath, and --dry-run.
• Diagnose and fix every common credential error with aws configure list and aws sts get-caller-identity as your two-command diagnostic kit.

Prerequisites & where this fits

You need an AWS account you can log into (the free tier is plenty — nothing here provisions billable resources beyond trivial API calls), a terminal on macOS, Linux or Windows, and permission to install a package. For the SSO section you need an organization using IAM Identity Center (formerly AWS SSO); if you do not have one, the plain-profile and assume-role paths stand on their own. Basic comfort with a shell — editing a dotfile, exporting an environment variable, reading JSON — is assumed. You do not need to understand IAM policy internals; when a call is denied for permissions rather than identity, that is a different topic and we will point you to it.

This article sits at the Foundations layer of the AWS track: it is the tool you use to exercise everything else. It assumes the account and identity model from AWS Organizations and IAM Foundations: Accounts, OUs and Roles sits above it — accounts, OUs, IAM Identity Center, roles and trust policies are the what; this article is the how you reach them from a keyboard. It pairs directly with three siblings you will meet again in the troubleshooting section: AWS cross-account roles and AssumeRole, hands-on for the role graph an assume-role profile rides on, IAM Identity Center and SSO permission sets for what an SSO profile is actually mapped to, and IAM policy evaluation and AccessDenied troubleshooting for the day a credential is valid but the action is refused.

A quick map of where each credential source lives, who owns it, and what failure it can cause — so mid-incident you know which layer to poke:

Core concepts

Before any command runs, the AWS CLI must resolve two things independently: credentials (who you are — an access key, a session token, or a promise of one via a role/SSO) and configuration (region, output format, retry behaviour, and which profile to read). These come from overlapping-but-different sources, which is the root of most confusion. Getting the mental model right makes the rest mechanical.

Profiles: a named bundle of settings

A profile is a named set of credential and configuration values. The magic word default is just the profile used when you name none. You select a non-default profile with --profile NAME on a command or AWS_PROFILE=NAME in the environment. A profile can carry static credentials (an access key), or it can carry instructions for obtaining credentials (an SSO login, an assume-role directive) — and the second kind is what every modern setup uses, because static long-lived keys on a laptop are the number-one AWS credential leak.

Two files, two jobs

Configuration lives in ~/.aws/config; credentials can live in ~/.aws/credentials. The split is historical and slightly leaky (SSO and assume-role settings live in config even though they yield credentials), but the rule of thumb holds: secrets (aws_access_key_id, aws_secret_access_key) go in credentials; everything else (region, output, sso, role_arn, source_profile) goes in config. On Windows the files sit under %USERPROFILE%\.aws\.

The single most common beginner cut is the header mismatch: in config a non-default profile is [profile dev], but in credentials the same profile is [dev] (no profile word). Put [profile dev] in credentials and the CLI looks for a profile literally named profile dev and reports it cannot be found.

The credential provider chain

When the CLI needs a credential it walks an ordered list of providers and stops at the first one that returns something usable. This is the concept. Memorise the order and you can explain every “it used the wrong identity” bug by asking: which provider higher in the list answered first? The table below is the resolution order the AWS CLI v2 uses; higher rows win.

Two subtleties worth internalising now, because they cause the nastiest bugs. First, --profile (row 1) is not a credential — it selects which profile the file-based providers (rows 3–7) read, but static credential environment variables (row 2) still outrank a profile’s file credentials. So aws --profile prod ... can still run as whoever your exported AWS_ACCESS_KEY_ID belongs to. Second, the assume-role provider (row 3) needs a source of credentials to make the sts:AssumeRole call; when it fails, the error frequently names the target role while the real problem is the source — an expired SSO token or stale keys one hop back.

Kinds of profile

Not all profiles are the same shape. The CLI infers the type from which keys a profile contains, and that type decides which provider handles it.

Installing and updating the AWS CLI v2

There are two major versions in the wild. AWS CLI v1 is Python-pip-installed and does not support aws configure sso in the way v2 does; AWS CLI v2 ships as a self-contained bundle (its own embedded Python), installs from a platform package, and is the only version you should run today. If aws --version prints aws-cli/1.x, you are on the legacy line and should replace it.

Installing per platform

Pick the installer for your OS. Each lands the aws binary and an aws_completer for shell tab-completion.

On Linux the zip bundle is worth understanding because it is also how you update: the ./aws/install script refuses to clobber an existing install, so to upgrade you pass the update flag.

# Fresh install
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o awscliv2.zip
unzip awscliv2.zip
sudo ./aws/install

# Update an existing v2 in place (point --bin-dir/--install-dir at the current ones)
sudo ./aws/install --update --bin-dir /usr/local/bin --install-dir /usr/local/aws-cli

Keeping it current

The AWS CLI v2 has no built-in self-update command — there is no aws upgrade. You keep it current by re-running the installer (with --update on Linux) or via your package manager. Do not let it drift: new AWS services and options appear only in newer CLI builds, and some SSO/OIDC fixes are version-gated.

$ aws --version
aws-cli/2.17.0 Python/3.11.9 Darwin/24.5.0 source/arm64

If that prints aws-cli/1.*, or your shell finds an old binary first, check which -a aws — a pip-installed v1 in ~/.local/bin shadowing the v2 in /usr/local/bin is a common “I installed v2 but SSO still fails” cause.

The config and credentials files, decoded

Everything the CLI knows about you, absent environment variables, lives in these two files. Learn every key and you can hand-craft any profile without the interactive wizard — which matters because the wizard cannot express assume-role chains or credential_process.

~/.aws/config — the full key reference

A minimal config looks like this; the annotated table follows.

[default]
region = ap-south-1
output = json

[profile dev]
region = ap-south-1
output = table
cli_pager =

[profile prod]
region = us-east-1
role_arn = arn:aws:iam::222222222222:role/PowerUser
source_profile = sso-base

~/.aws/credentials — the credential keys

This file holds only credentials and is deliberately small.

[default]
aws_access_key_id = AKIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

[ci-runner]
aws_access_key_id = AKIAI44QH8DHBEXAMPLE
aws_secret_access_key = je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY

Profile naming, file locations and overrides

The header rules trip up everyone once. Here they are exhaustively.

You can move the files themselves with environment variables — useful for isolating CI or for direnv-style per-project credentials.

The equivalent Terraform provider block references the same profile — infrastructure code should point at a profile name, never inline keys:

provider "aws" {
  region  = "ap-south-1"
  profile = "prod"          # reads ~/.aws/config [profile prod]
}

# Or, for assume-role directly in the provider (no profile needed):
provider "aws" {
  region = "us-east-1"
  assume_role {
    role_arn     = "arn:aws:iam::222222222222:role/Terraform"
    session_name = "terraform-ci"
    external_id  = "KLOUDVIN-7f3a"
  }
}

Named profiles and the resolution order

A profile is selected, in order of precedence: the --profile flag beats the AWS_PROFILE environment variable, which beats the literal default profile. But selecting a profile is not the same as selecting credentials — remember rows 1 and 2 of the chain: exported static keys still win. This section makes that concrete.

Selecting a profile

aws s3 ls --profile dev            # explicit, per-command — clearest
export AWS_PROFILE=dev             # sticky for the shell session
aws s3 ls                          # now uses dev
aws configure list-profiles        # enumerate every profile you have

How one setting — region — resolves across sources

Region is the clearest illustration of precedence because it comes from six places. The CLI takes the first it finds, top-down.

The same top-down rule governs output (via --output → AWS_DEFAULT_OUTPUT → profile → default) and credentials (via the provider chain above). Internalise “first match wins, flags beat env, env beats files” and you never have to guess.

SSO profiles (IAM Identity Center)

For humans working across multiple accounts, IAM Identity Center (the service formerly called AWS SSO) is the right answer: you log in once via a browser to your org’s portal, and the CLI mints short-lived credentials per account/role on demand — no long-lived keys on the laptop. An SSO profile stores where to log in and which account/role to request; the actual credentials are cached and refreshed from an SSO token.

The aws configure sso wizard

Running the wizard is the easiest way to create both the reusable sso-session block and a profile that references it.

$ aws configure sso
SSO session name (Recommended): kloudvin
SSO start URL [None]: https://kloudvin.awsapps.com/start
SSO region [None]: ap-south-1
SSO registration scopes [sso:account:access]: sso:account:access
# → browser opens; you approve the device authorization
The following accounts are available:
> 333333333333 (Sandbox)
  222222222222 (Production)
Using the role name "AdministratorAccess"
CLI default client Region [None]: ap-south-1
CLI default output format [None]: json
CLI profile name [AdministratorAccess-333333333333]: sandbox-admin

The result on disk — note the two blocks:

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

[profile sandbox-admin]
sso_session = kloudvin
sso_account_id = 333333333333
sso_role_name = AdministratorAccess
region = ap-south-1
output = json

sso-session block vs legacy inline SSO

Older guides show sso_start_url directly in the profile. That still works but is not refreshable — the token cannot silently renew, so you re-login more often. Prefer the sso-session form.

Logging in and the token cache

aws sso login --profile sandbox-admin      # or: --sso-session kloudvin
# browser opens, approve; token cached in ~/.aws/sso/cache/
aws sts get-caller-identity --profile sandbox-admin
aws sso logout                              # clears cached tokens

The SSO access token (portal login) and the per-account role credentials have different lifetimes; when either lapses you get an SSO-expiry error and the fix is always aws sso login. There are no long-lived secrets to rotate — that is the whole point.

Assume-role profiles

AssumeRole is how you cross an account boundary or elevate privilege: a base identity calls sts:AssumeRole on a target role and receives temporary ASIA… credentials scoped to that role. An assume-role profile automates this — you name the role_arn and where the base credentials come from, and the CLI performs the STS call transparently and caches the result.

The keys, end to end

[profile prod-admin]
role_arn = arn:aws:iam::222222222222:role/Admin
source_profile = sso-base          # where base creds come from
external_id = KLOUDVIN-7f3a         # if the trust policy requires it
mfa_serial = arn:aws:iam::111111111111:mfa/vinod
duration_seconds = 3600
role_session_name = vinod-cli
region = us-east-1

source_profile vs credential_source

These are mutually exclusive and answer the same question — where do the base credentials for the AssumeRole call come from? — differently.

The aws sts assume-role call underneath, which the profile automates, is also runnable by hand — invaluable for debugging (you see the real error before the CLI reframes it):

aws sts assume-role \
  --role-arn arn:aws:iam::222222222222:role/Admin \
  --role-session-name vinod-debug \
  --external-id KLOUDVIN-7f3a \
  --profile sso-base
# → returns Credentials{AccessKeyId ASIA…, SecretAccessKey, SessionToken, Expiration}

The Terraform equivalent, when a pipeline assumes the role, mirrors the same fields:

provider "aws" {
  region = "us-east-1"
  assume_role {
    role_arn     = "arn:aws:iam::222222222222:role/Admin"
    session_name = "terraform-ci"
    external_id  = "KLOUDVIN-7f3a"
    duration     = "1h"
  }
}

Why assume-role fails (preview)

Because the failure so often points at the wrong thing, keep this small map handy; the full playbook expands it later.

Environment variables reference

Environment variables sit above the config files in precedence (rows 1–2 and various config overrides), which makes them powerful and dangerous. This is the exhaustive list you will actually meet.

Two you will lean on constantly: AWS_PROFILE (clean account switching) and — for debugging — deliberately unset-ting AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN to remove the number-one shadowing culprit.

Global options: region, output, pagination, query, dry-run

Independent of who you are, a handful of global flags shape every command’s behaviour and output. Master these and the CLI becomes a data tool, not just an API poker.

--output formats

aws ec2 describe-instances --output table
aws ec2 describe-instances --output text
aws ec2 describe-instances --output yaml

Pagination

By default the CLI paginates for you (fetching all pages) and pipes long output into a pager (less). Both behaviours surprise people — the “hang” is just less waiting; press q.

--max-items and --page-size differ in a way that matters for throttling: --page-size controls how many the service returns per call (smaller = more calls but gentler on rate limits), while --max-items caps how many the CLI shows you and prints a NextToken to continue.

--query (client-side JMESPath)

--query runs a JMESPath expression over the JSON response after it arrives — so it works on any field, any service. These are real, useful expressions:

--filters (server-side) vs --query (client-side)

They look similar and are frequently confused; the difference is where the work happens and how much data crosses the wire.

# Server-side filter (less data) THEN client-side shape (nicer output):
aws ec2 describe-instances \
  --filters "Name=instance-state-name,Values=running" "Name=tag:Env,Values=prod" \
  --query "Reservations[].Instances[].{ID:InstanceId,IP:PrivateIpAddress}" \
  --output table

--dry-run

Some mutating EC2 commands accept --dry-run: the CLI sends the request with a dry-run flag so the service checks permissions without doing the action.

$ aws ec2 run-instances --image-id ami-0abcd1234 --instance-type t3.micro --dry-run
An error occurred (DryRunOperation) when calling the RunInstances operation: Request would have succeeded, but DryRun flag is set.

“Who am I?” — the two commands that end most arguments

$ aws configure list
      Name                    Value             Type    Location
      ----                    -----             ----    --------
   profile                sandbox-admin           manual    --profile
access_key     ****************ABCD              sso    sso
secret_key     ****************wxyz              sso    sso
    region                ap-south-1      config-file    ~/.aws/config

$ aws sts get-caller-identity
{
    "UserId": "AROA...:vinod",
    "Account": "333333333333",
    "Arn": "arn:aws:sts::333333333333:assumed-role/AWSReservedSSO_AdministratorAccess_.../vinod"
}

The Type/Location columns in aws configure list are the single most useful diagnostic in this whole article: they tell you exactly which source supplied each value. If access_key shows Type=env, an environment variable is winning — that is your bug, right there, before you touch a config file.

Architecture at a glance

The diagram is not a network path — it is the credential provider chain, drawn left to right in precedence order. Read it as a waterfall: the CLI asks each source in turn, and the first one that hands back a usable credential wins, so nothing to its right is ever consulted. Start at CLI flags + environment: --profile/--region select which block to read, but exported static keys (AWS_ACCESS_KEY_ID) short-circuit everything — badge 1, the wrong-account trap. If no static creds are present, the chosen profile may declare an assume-role directive (role_arn + source_profile), which makes an STS call using base creds one hop back — badge 2, where a stale source masquerades as a target-role problem. Failing that, an SSO profile reads its cached IAM Identity Center token — badge 3, the daily aws sso login. Then the shared files (~/.aws/config + credentials) — badge 4, the [profile x] vs [x] header and “Unable to locate credentials.” On a server the chain ends at the instance or container role via IMDS/ECS — badge 5, the IMDSv2 hop-limit starvation. Whatever wins is then signed with SigV4 and sent to the AWS API, where sts get-caller-identity proves which source actually answered — badge 6, the place InvalidClientTokenId, a missing region, or clock skew rejects an otherwise-resolved credential.

Follow the six badges and you have the entire failure map in resolution order: a shadowing env var (1), a broken assume-role hop (2), an expired SSO token (3), a missing or mis-headered profile (4), a starved workload role (5), and an API-level rejection (6). The legend narrates each as symptom · confirm · fix — the same method as the rest of the article: localise to a link in the chain, read the cause, run the named check, apply the fix.

Real-world scenario

KloudVin Retail, a mid-size e-commerce team, runs three AWS accounts: sandbox (333333333333), staging, and production (222222222222). For years every engineer had a long-lived IAM user with AKIA… keys in ~/.aws/credentials, and deployments ran from a laptop with those keys exported into the shell for convenience. It worked until the Tuesday a senior engineer, Priya, shipped a config change intended for staging that landed in production — because six days earlier she had exported production keys to run a one-off migration and never unset them. Her --profile staging flag had been silently ignored the whole time; static environment credentials (row 2 of the chain) outranked the profile file (row 6). The change took the checkout page down for eleven minutes.

The post-incident fix was structural, and it is the exact setup this article teaches. First, they killed long-lived keys for humans entirely and moved to IAM Identity Center. Each engineer now runs aws configure sso once to create an sso-session block (kloudvin) and a per-account profile — sandbox-admin, staging-deploy, prod-readonly. A morning starts with a single aws sso login --sso-session kloudvin, and every profile on that session is good for the day; there are no AKIA… secrets on any laptop to leak or to shadow anything.

Second, production writes go through an explicit assume-role profile, prod-deploy, whose source_profile is the low-privilege prod-readonly SSO profile and whose role_arn points at a Deployer role gated by external_id = KLOUDVIN-7f3a and mfa_serial. Elevation is now a deliberate act: the CLI prompts for an MFA code, and CloudTrail records role_session_name = <engineer>-deploy on every privileged call, so “who changed production” is answerable in one query. The deploy pipeline itself uses credential_source = Ec2InstanceMetadata from a CI runner’s instance role — no keys anywhere in the pipeline config.

Third, they made the chain visible. Every deploy script now begins with aws sts get-caller-identity and asserts the returned Account equals the intended one before doing anything mutating; a mismatch aborts the run. A shell prompt plugin shows the active AWS_PROFILE in colour — red for prod-*. The reusable habit that came out of the incident is one sentence long and worth stealing: before any command that changes state, run aws sts get-caller-identity and read the account number out loud. Eleven minutes of downtime bought a workflow where the wrong-account class of error simply cannot recur silently — the identity is asserted, not assumed.

Advantages and disadvantages

The AWS CLI’s credential model is powerful because it is layered; it is confusing for exactly the same reason. Weigh it honestly.

When does each side matter? The advantages dominate for teams with more than one account and more than one engineer — profiles plus SSO plus assume-role is simply how professional AWS is done. The disadvantages bite hardest on newcomers (the file/precedence rules) and on anyone mixing static env keys with profiles (unset them and half the pain evaporates). The mitigation for nearly every disadvantage is the same two-command diagnostic — aws configure list and aws sts get-caller-identity — which is why this article treats them as the core skill.

Hands-on lab

You will set up three profiles — a plain (static-key) profile, an SSO profile, and an assume-role profile — and verify each with aws sts get-caller-identity, then run a real --query example. Nothing here provisions billable resources; the only calls are STS and a describe. Where a step needs org-specific values (an SSO start URL, a role ARN), substitute your own. There is no teardown required beyond optionally removing the profiles you added.

Prerequisites for the lab:

Step 1 — Confirm your starting point

aws --version
aws configure list-profiles      # what you already have

Expected: a version line beginning aws-cli/2. and a (possibly empty) list of profile names. If aws is not found or shows 1.x, fix that first with the install table.

Step 2 — Create a plain (static-key) profile

aws configure --profile lab-plain
# AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE
# AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
# Default region name [None]: ap-south-1
# Default output format [None]: json

This writes [lab-plain] into ~/.aws/credentials (the keys) and [profile lab-plain] into ~/.aws/config (region + output). Verify identity:

$ aws sts get-caller-identity --profile lab-plain
{
    "UserId": "AIDA................",
    "Account": "333333333333",
    "Arn": "arn:aws:iam::333333333333:user/lab-user"
}

Expected: an Arn of the form …:user/<name> and your sandbox Account. Now prove the source of each value:

$ aws configure list --profile lab-plain
      Name                    Value             Type    Location
      ----                    -----             ----    --------
   profile                  lab-plain           manual    --profile
access_key     ****************MPLE   shared-credentials-file
    region                ap-south-1      config-file    ~/.aws/config

The shared-credentials-file type confirms the key came from ~/.aws/credentials, not an env var.

Step 3 — Create an SSO profile

If your org has IAM Identity Center, run the wizard; otherwise read this step and skip to Step 4.

aws configure sso --profile lab-sso
# SSO session name (Recommended): kloudvin
# SSO start URL [None]: https://YOUR-ORG.awsapps.com/start
# SSO region [None]: ap-south-1
# SSO registration scopes [sso:account:access]:
# (browser opens → approve device authorization)
# choose an account + role when prompted
# CLI default client Region [None]: ap-south-1
# CLI default output format [None]: json

Log in and verify — note the assumed-role ARN, the hallmark of temporary SSO credentials:

$ aws sso login --profile lab-sso
$ aws sts get-caller-identity --profile lab-sso
{
    "UserId": "AROA................:vinod",
    "Account": "333333333333",
    "Arn": "arn:aws:sts::333333333333:assumed-role/AWSReservedSSO_.../vinod"
}

Expected: the ARN is an assumed-role, not a user — you are running on short-lived credentials with no secret on disk. aws configure list --profile lab-sso will show Type=sso for the keys.

Step 4 — Create an assume-role profile

Point a profile at a role you are allowed to assume, chaining from a base profile (use lab-plain or lab-sso as the source_profile). Add these lines to ~/.aws/config:

[profile lab-assume]
role_arn = arn:aws:iam::333333333333:role/ReadOnlyLab
source_profile = lab-plain
role_session_name = lab-assume-demo
region = ap-south-1

Verify — the CLI performs the STS call for you and returns the assumed identity:

$ aws sts get-caller-identity --profile lab-assume
{
    "UserId": "AROA................:lab-assume-demo",
    "Account": "333333333333",
    "Arn": "arn:aws:sts::333333333333:assumed-role/ReadOnlyLab/lab-assume-demo"
}

Expected: the Arn ends with assumed-role/ReadOnlyLab/lab-assume-demo and the session name you set. If instead you see AccessDenied, the role’s trust policy does not allow your lab-plain principal to assume it — that is a policy fix, covered in the cross-account roles hands-on, not a CLI fix.

Step 5 — Run a real --query example across profiles

Prove the profiles work for a normal read call, and shape the output:

# Regions enabled for your account, as plain text
aws ec2 describe-regions \
  --query "Regions[].RegionName" --output text --profile lab-plain

# Your account's S3 buckets as a table (works on whichever profile has access)
aws s3api list-buckets \
  --query "Buckets[].{Name:Name,Created:CreationDate}" \
  --output table --profile lab-sso

Expected: a tab-separated list of region names, and an ASCII table of bucket names and creation dates. Swap --profile values to confirm each identity independently.

Step 6 (optional) — Clean up

No AWS resources were created, so there is nothing billable to delete. To remove the lab profiles, delete their sections from ~/.aws/config and ~/.aws/credentials, or:

aws sso logout                     # clear cached SSO tokens if you did Step 3
# then hand-edit the [lab-*] sections out of ~/.aws/{config,credentials}

Common mistakes & troubleshooting

This is the heart of the article. Credential errors reduce to a small set of symptom classes; each has a precise root cause you confirm with one command. Your two-tool kit is aws configure list (which source supplied each value) and aws sts get-caller-identity (who AWS thinks you are). Work the table top-down.

The playbook

Error / status reference

The error string AWS returns tells you the category before you read anything else. Keep this next to the playbook.

Decision table — from symptom to the right file

The three nastiest failures, in prose

The env-var shadow (playbook #2) is the one that costs the most, because nothing looks wrong. You pass --profile staging, the command runs, results come back — they are simply from the wrong account. The cause is that static credential environment variables sit at row 2 of the chain, above every profile file, so a long-forgotten export AWS_ACCESS_KEY_ID=… from a debugging session weeks ago wins over your explicit --profile. There is exactly one reliable tell: aws configure list prints Type env next to access_key. Make it a reflex — before any state-changing command, run aws sts get-caller-identity and read the account number. The permanent fix is cultural: never export long-lived keys; use AWS_PROFILE (which selects a profile rather than injecting credentials) or SSO, and keep a shell function that unsets the three credential vars in one shot.

The assume-role misattribution (playbook #11) sends people debugging the wrong thing. When an assume-role profile fails, the CLI surfaces an error mentioning the target role_arn, so the instinct is to edit that role’s permissions. But the AssumeRole call needs source credentials, and the failure is frequently that the source_profile — an SSO login or base key one hop back — has expired or is itself denied. Confirm by running the underlying call by hand: aws sts assume-role --role-arn <target> --role-session-name debug --profile <source>. If that errors with ExpiredToken, your source is stale (aws sso login); if it errors with AccessDenied … sts:AssumeRole, the target role’s trust policy doesn’t list your source principal (or wants an external_id you didn’t supply). The error text lies about which end is broken; the manual call tells the truth.

Clock skew (playbook #10) produces errors that look like authentication failures but are physics. AWS SigV4 signatures embed a timestamp and are rejected if your clock differs from AWS’s by more than about five minutes — you get Signature expired or “the difference between the request time and the current time is too large,” which reads like a credential problem and sends you rotating keys that were never bad. It bites laptops that slept for days, VMs whose clock drifted, and containers on a host with a wrong clock. Confirm in one command — date -u and compare to real time — and fix by forcing an NTP sync (sudo chronyc makestep, or enabling host time sync). No credential change will ever fix a clock problem.

Best practices

• Never put long-lived keys on a laptop. Use IAM Identity Center (SSO) for humans and instance/task roles for workloads. Static AKIA… keys are the single most-leaked AWS secret.
• One profile per account-role, named for what it is (prod-readonly, staging-deploy), never default for anything privileged. Ambiguity is how the wrong-account incident happens.
• Assert identity before mutating. Begin deploy scripts with aws sts get-caller-identity and check the Account matches the intended one; abort on mismatch.
• Prefer AWS_PROFILE over exporting keys. AWS_PROFILE selects a profile (safe); AWS_ACCESS_KEY_ID injects credentials that shadow everything (dangerous).
• Keep a unset shell function — one command to clear AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN — and run it whenever a command “ignores” your profile.
• Use the sso-session block, not inline sso_* — it enables token refresh and is reusable across profiles.
• Chain assume-role from SSO, not from static keys. source_profile = <sso-base> keeps the whole chain key-less.
• Gate privileged roles with external_id and mfa_serial and set a meaningful role_session_name so CloudTrail attributes every action to a human.
• Set a region in every profile to avoid You must specify a region, and set output = json for scriptability.
• Disable the pager in automation (AWS_PAGER="" or cli_pager=) so scripts never hang waiting on less.
• Show the active profile in your shell prompt, colour-coded (red for prod), so you always see which account you are in.
• Keep the CLI current — version drift silently breaks new services and SSO fixes; script brew upgrade awscli or the --update install.
• Never commit ~/.aws/* and add it to global gitignore; treat account IDs and start URLs as sensitive too.

Security notes

The CLI’s credential model is a security control surface; configure it defensively.

The Terraform for an IMDSv2-only, hop-limit-tuned instance — the workload side of the chain — is worth pinning:

resource "aws_instance" "app" {
  ami                  = "ami-0abcd1234"
  instance_type        = "t3.micro"
  iam_instance_profile = aws_iam_instance_profile.app.name
  metadata_options {
    http_tokens                 = "required"   # IMDSv2 only
    http_put_response_hop_limit = 2            # allow one container hop
    http_endpoint               = "enabled"
  }
}

Cost & sizing

The AWS CLI itself is free, and so are the identity mechanics around it — but a few adjacent things do cost, and it is worth knowing which.

There is no “sizing” in the compute sense, but two operational costs are real: time (a credential mystery can eat an hour — the two-command diagnostic is the mitigation) and risk (a leaked static key can cost a great deal — SSO and instance roles are the mitigation). In INR terms the tool and identity layer are effectively ₹0; the only line items that appear on a bill are the resources your commands create, which is precisely why --dry-run and an identity assertion before mutating are cheap insurance.

Interview & exam questions

Q1. What is the AWS CLI credential provider chain, and why does its order matter? It is the ordered list of sources the CLI checks for credentials — command-line options, environment variables, assume-role, web-identity, SSO, the shared credentials file, the config file, and finally container/instance metadata — stopping at the first that returns a usable credential. Order matters because a higher source silently wins: exported static keys (env) override any profile file, which is the classic wrong-account bug. (CLF-C02, SAA-C03)

Q2. Why can aws --profile prod s3 ls still run against the wrong account? Because --profile selects which profile block the file-based providers read, but static credential environment variables (AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY) sit higher in the chain and are used directly. aws configure list showing Type env confirms it; unset the variables to fix. (SOA-C02)

Q3. What is the difference between ~/.aws/config and ~/.aws/credentials? credentials holds static keys (aws_access_key_id/aws_secret_access_key) with [name] headers; config holds configuration and credential sources (region, output, sso, role_arn) with [profile name] headers. The header difference — [profile x] in config vs [x] in credentials — is a frequent error. (CLF-C02)

Q4. How do you configure an SSO profile, and what refreshes it? Run aws configure sso to create an sso-session block (start URL, SSO region, scopes) and a profile referencing it (sso_account_id, sso_role_name). aws sso login opens the browser and caches a token in ~/.aws/sso/cache/; when it expires you re-run aws sso login. No long-lived keys are stored. (SAA-C03, SCS-C02)

Q5. Explain source_profile vs credential_source in an assume-role profile. Both supply the base credentials for the sts:AssumeRole call; source_profile names another profile (typical on a laptop), while credential_source uses Environment, Ec2InstanceMetadata, or EcsContainer (typical in CI/on a server). They are mutually exclusive. (SAA-C03)

Q6. An assume-role profile returns ExpiredToken — where is the problem? Almost always in the source, not the target: the source_profile (an SSO or base credential) has expired, even though the error mentions the target role. Confirm by running aws sts assume-role by hand from the source profile; fix by refreshing the source (aws sso login). (SOA-C02)

Q7. What does aws sts get-caller-identity return and why is it the most useful debugging command? It returns the Account, UserId, and Arn that AWS actually sees for your current credentials — cutting through every layer of the chain to answer “who am I, really.” An assumed-role ARN means temporary creds; a user ARN means static keys. (CLF-C02)

Q8. How do server-side --filters and client-side --query differ? --filters is processed by the AWS service (service-defined keys, reduces data over the wire, only some services support it); --query is a JMESPath expression evaluated by the CLI after the full response arrives (works on any command/field). Best practice: filter server-side, then shape with --query. (DVA-C02)

Q9. What causes You must specify a region and how do you resolve it? No region resolved from any source: no --region flag, no AWS_REGION/AWS_DEFAULT_REGION, and no region in the selected or default profile. Fix by passing --region or setting region in the profile. (CLF-C02)

Q10. You get Signature expired / a time-difference error. Is it a credential problem? No — it is clock skew. SigV4 signatures embed a timestamp rejected if your clock differs from AWS by more than ~5 minutes. Confirm with date -u; fix by syncing NTP. Rotating keys will not help. (SOA-C02)

Q11. Why prefer IAM Identity Center over IAM users with access keys for CLI access? SSO issues short-lived, per-account credentials with no long-lived secret on the laptop, supports MFA and central permission sets, and removes the top credential-leak vector. IAM user keys are long-lived, must be rotated, and are frequently committed or exported by accident. (SAA-C03, SCS-C02)

Q12. What does --dry-run do on an EC2 command? It sends the request with a dry-run flag so the service checks permissions only: DryRunOperation means you would be allowed (re-run without the flag), UnauthorizedOperation means you lack permission. It is a safe way to test IAM before performing a mutating action. (DVA-C02)

Quick check

1. In the credential provider chain, which wins: a static AWS_ACCESS_KEY_ID in your shell, or the profile you pass with --profile?
2. Where does aws_secret_access_key belong — ~/.aws/config or ~/.aws/credentials — and what is the section header for a profile named dev in that file?
3. Your SSO command fails with “the SSO session has expired.” What single command fixes it?
4. An assume-role profile returns ExpiredToken. Which end — source or target — do you investigate first, and with what manual command?
5. A describe command “hangs” with no output and no error. What is happening and how do you stop it?

Answers

1. The static environment variable wins — env credentials (chain row 2) outrank profile-file credentials. --profile selects the block but does not override exported static keys. Confirm with aws configure list (Type env); fix by unsetting the variable.
2. In ~/.aws/credentials, under the header [dev] (no profile word — that prefix is only used in config, as [profile dev]).
3. aws sso login --profile <name> (or --sso-session <name>) — it re-opens the browser and refreshes the cached token.
4. Investigate the source first; the error names the target but the source_profile creds have usually lapsed. Run aws sts assume-role --role-arn <target> --role-session-name debug --profile <source> to see the real error.
5. Output has opened in the pager (less) and is waiting for you. Press q to return to the prompt; disable it with --no-cli-pager or export AWS_PAGER="".

Glossary

Next steps

• Build the role graph an assume-role profile rides on in AWS cross-account roles and AssumeRole, hands-on.
• Understand what an SSO profile is actually mapped to in IAM Identity Center and SSO permission sets.
• When a credential is valid but the action is refused, work through IAM policy evaluation and AccessDenied troubleshooting.
• Ground the whole identity model in AWS Organizations and IAM Foundations: Accounts, OUs and Roles.
• Put the CLI to work provisioning with confidence — pair it with an infrastructure-as-code workflow so every command you learned here runs the same way in automation.