Configure the AWS CLI for Multiple Accounts, Profiles, and SSO

The AWS CLI is the fastest way to automate deployments, debug permissions, and script one-off fixes—until credentials leak, profiles point at the wrong account, or SSO sessions expire mid-pipeline. Most “aws cli configure” headaches are not about memorizing flags; they are about how identity is stored, selected, and rotated.

Here is a practical setup for developers and operators who juggle multiple accounts, including named profiles, SSO, and the guardrails that keep production safer.

What aws configure actually writes

Running aws configure (or aws configure --profile myapp) updates files in your home directory:

• ~/.aws/credentials — access keys (long-term IAM user keys or temporary session tokens)
• ~/.aws/config — default region, output format, and profile metadata (including SSO settings)

Modern workflows often skip long-term access keys on laptops entirely and use IAM Identity Center (SSO) instead. Both patterns coexist; know which one your organization mandates.

Minimal interactive setup

aws configure --profile dev-personal
# AWS Access Key ID: ...
# AWS Secret Access Key: ...
# Default region name: us-east-1
# Default output format: json

Invoke any command with:

aws s3 ls --profile dev-personal

Set a default for your shell session:

export AWS_PROFILE=dev-personal

Prefer SSO over static keys when you can

For enterprise AWS accounts, admins usually provision IAM Identity Center permission sets. Configure once per profile:

aws configure sso --profile corp-prod-readonly

The wizard stores SSO start URL, SSO region, account ID, and role name in ~/.aws/config. Login before commands expire:

aws sso login --profile corp-prod-readonly

Why this matters: SSO sessions rotate automatically; you are not copying access keys into Slack. When the session dies, the CLI error is explicit—run aws sso login again.

Multiple accounts without mistakes

A common layout in ~/.aws/config:

[profile shared-dev]
sso_start_url = https://my-org.awsapps.com/start
sso_region = us-east-1
sso_account_id = 111111111111
sso_role_name = DeveloperAccess
region = us-east-1

[profile shared-prod]
sso_start_url = https://my-org.awsapps.com/start
sso_region = us-east-1
sso_account_id = 222222222222
sso_role_name = ReadOnlyAccess
region = us-east-1

Use distinct profile names that encode environment (-prod, -staging). Color your shell prompt with $AWS_PROFILE so a prod tab is obvious.

Assume-role chains

If your security team forbids direct prod keys, a jump profile assumes a role:

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

The CLI uses credentials from corp-sso-base to call sts:AssumeRole. ExternalId and session tagging may be required—your internal runbook should document them.

Regions and endpoints

aws configure set region eu-west-1 --profile eu-app avoids passing --region on every call. For LocalStack or custom endpoints, use profiles with endpoint_url (supported in AWS CLI v2 via services block or environment variables depending on version)—check your tooling version before relying on exotic setups.

Credentials for CI/CD (different rules)

Laptops use SSO; build agents should use OIDC federation (GitHub Actions → IAM role) or instance/task roles—not an IAM user named jenkins-keys. If you must configure access keys in CI, store them in a secrets manager and inject at runtime; rotate on a schedule.

Never commit ~/.aws/credentials to git. If you did, rotate immediately—bots scan public repos within minutes.

Useful configuration tweaks

# Faster tab completion (enable once per machine)
complete -C aws_completer aws

# Consistent JSON for jq pipelines
aws configure set cli_pager "" --profile dev-personal

Disabling the pager stops less from hijacking scripted output.

Named credential processes (advanced)

The credential_process setting lets the CLI call a helper binary (e.g., your vault or cloud-specific token broker). This keeps secrets out of plaintext files when your security team provides a supported fetcher.

Verifying who you are

Before destructive commands:

aws sts get-caller-identity --profile shared-prod

The returned Account and Arn should match intent. Wrap dangerous scripts with a guard that compares account ID to an allowlist.

Troubleshooting frequent errors

Symptom	Likely cause	Fix
Unable to locate credentials	No profile exported / empty credentials file	Set AWS_PROFILE or run aws configure / aws sso login
ExpiredToken	SSO or STS session timed out	aws sso login --profile ...
AccessDenied on correct account	SCP or permission boundary	Escalate IAM; test with simulate-principal-policy
Wrong region empty list	Resources live elsewhere	aws configure get region --profile ...

Enable debug when needed—sparingly, since logs may include sensitive ARNs:

aws s3 ls --debug 2>&1 | tail -n 30

Hardening habits

• Use least-privilege permission sets; prod read-only for daily work
• Separate personal sandbox accounts from employer orgs
• Turn on MFA for any remaining IAM users
• Prefer role assumption with auditable CloudTrail entries over shared root-account keys (there should be no root keys)

FAQ

Should I use access keys for local development?
Only if SSO is unavailable. Otherwise SSO plus short-lived credentials reduces blast radius.

Does the CLI respect AWS_ACCESS_KEY_ID environment variables?
Yes—they override profiles unless combined carefully. CI systems often set env vars explicitly.

Can I merge config from a team template?
Yes—check in a sanitized config snippet without secrets and document required sso login steps.

What about AWS CLI v1 vs v2?
Use v2; SSO and newer auth features are better supported.

Working with multiple tools (Terraform, CDK, SAM)

Infrastructure tools read the same credential chain as the CLI. When terraform plan hits AccessDenied but your manual aws sts get-caller-identity works, compare:

• Whether Terraform uses a different profile via AWS_PROFILE in the shell vs IDE task
• Whether assume role sessions expired mid-apply
• Whether region in ~/.aws/config mismatches the provider block

Explicitly export profile in scripts:

export AWS_PROFILE=shared-staging
terraform plan

For CDK, cdk deploy inherits the active profile; document required SSO login in your README so onboarding is not tribal knowledge.

Session duration and automation tokens

SSO sessions expire based on admin policy—often eight to twelve hours. Long-running local jobs should refresh credentials or use role-based CI instead of tethering to a laptop login.

For local scripts that outlive a session, catch ExpiredToken and prompt re-login rather than retrying blindly (rate limits and audit noise add up).

Rotating access keys without downtime

If policy still requires IAM user keys for a legacy integration, rotate with two active keys only during the swap window: create key B, deploy configs, validate traffic, deactivate key A, delete A after bake time. Document the rotation in your change management system; CloudTrail CreateAccessKey events should tie to a ticket.

Never embed keys in mobile apps or browser bundles—the CLI docs are for operators and backends, not client-side code.

Quick reference: files and environment variables

Variable / file	Purpose
AWS_PROFILE	Selects named profile for this shell
AWS_REGION	Overrides default region
~/.aws/credentials	Access keys and session tokens
~/.aws/config	Regions, SSO, assume-role chains
aws configure list	Shows active source of credentials

Running aws configure list after switching profiles is a zero-cost sanity check before terraform destroy.

Cross-platform notes

Paths differ on Windows (%UserProfile%\.aws\) but the format is the same. WSL users should keep one .aws directory shared or deliberately separate—mixing leads to “it works in WSL but not PowerShell” confusion.

Closing thoughts

Configuring the AWS CLI is really configuring identity: who you are, which account you touch, and how long that trust lasts. Invest ten minutes in clean profiles and SSO login habits—it saves hours of incident response after the wrong bucket was deleted from the wrong terminal tab.