AWS CLI Setup Best Practices

Q: Where should region live?

In ~/.aws/config, inside each profile's block. Region is not a secret and does not belong in the credentials file.

Q: How should I name profiles?

By account and role, for example prod-readonly or staging-deploy. Descriptive names prevent running a command against the wrong account.

Q: How do I rotate a long-lived key safely?

Create the new key, update the profile, verify with aws sts get-caller-identity, then delete the old key. Never delete first.

Q: Why set region explicitly for v3 credential providers?

fromIni and fromSSO return only credentials, not region. Without region on the client or AWS_REGION, a v3 client throws a region error.

Q: How do I confirm which identity a shell will use?

Run aws sts get-caller-identity. It returns the account and ARN the current environment resolves to.

Q: How do I keep one login covering many accounts?

Use an sso-session block that multiple profiles reference. A single aws sso login then serves every profile pointing at it.

A checklist of habits that keep your AWS CLI and SDK credentials secure, portable, and easy to reason about across accounts.

How to Use This List

Walk the categories top to bottom; A (identity) and B (secrets) matter most.
Treat each - [ ] as a rule to verify against your current setup.
Prefer the more secure option even when the quick one works today.
Revisit after any new account, teammate, or CI pipeline is added.
These apply equally to the CLI, boto3, and the AWS SDK for JavaScript v3 - they share the same config.

A - Identity & Credential Source

Prefer IAM Identity Center (SSO) over long-lived keys. aws sso login issues short-lived credentials that expire and refresh, removing static secrets from disk.
Reserve static access keys for last resort. Use them only for a solo experiment or where SSO is not available, and delete them afterward.
Use role assumption for cross-account access. A role_arn + source_profile profile beats copying a second account's keys around.
Use instance or container roles in production. Code running inside AWS should never read copied key files - let the runtime provide credentials.
Require MFA on sensitive roles. Add mfa_serial to role-assumption profiles so a code is required before elevation.

B - Protecting Secrets

Never commit ~/.aws/credentials or ~/.aws/config. Add .aws/ patterns to your global gitignore; a leaked key is a breach.
Never hardcode keys in application code. Let the default credential provider chain resolve them so no secret lives in the repo.
Keep secrets out of shell history. Prefer aws configure prompts or SSO over exporting keys inline where they land in .bash_history.
Restrict file permissions. The shared files should be readable only by your user (chmod 600 ~/.aws/credentials).
Scope keys minimally. Grant each identity only the permissions it needs, so a leak has a small blast radius.

C - Profile Naming & Organization

Name profiles by account and role. prod-readonly, staging-deploy, and dev-admin communicate intent far better than profile1.
Keep region in the config file, not credentials. Region is not a secret and belongs in each profile's config block.
Use an sso-session block for SSO profiles. One shared login covers many account/role profiles instead of repeating the start URL.
Verify names before risky commands. Run aws configure list-profiles so a typo does not point you at the wrong account.
Set a sensible default profile. Make the least-privileged identity your default so an unqualified command is safe.

D - Rotation & Hygiene

Rotate long-lived keys on a schedule. Create the new key, update the profile, verify, then delete the old key.
Delete unused keys and profiles. Every dormant credential is attack surface; remove identities you no longer use.
Audit with get-caller-identity before acting. Confirm which identity a shell resolves to before running anything destructive.
Log out of SSO on shared machines. aws sso logout clears the cached token when you step away.
Upgrade to and stay on AWS CLI v2. Version 1 is end-of-support and lacks SSO and sso-session features.

E - Working With the SDKs

Let the chain resolve credentials. Build clients with no keys so the same code runs locally and in production unchanged.
Select accounts with AWS_PROFILE, not code edits. Keep profile choice in the environment so scripts stay portable.
Set region explicitly for v3 credential providers. fromIni/fromSSO supply credentials only, so pass region or set AWS_REGION.
Do not cache temporary credentials as literals. Resolve through a profile or provider so expired credentials refresh automatically.
Match local and CI credential sources. Use short-lived, injected credentials (OIDC role assumption) in CI rather than static keys.

Here is the secret-free client both SDKs should aim for.

# --- Python (boto3) ---
import boto3
 
# No keys, no region literal: resolved from the profile/env the CLI set up.
# The same code runs on a laptop (SSO/profile) and in production (instance role).
s3 = boto3.client("s3")
print([b["Name"] for b in s3.list_buckets()["Buckets"]])

// --- TypeScript (AWS SDK v3) ---
import { S3Client, ListBucketsCommand } from "@aws-sdk/client-s3";
 
// No keys: resolved from the profile/env the CLI set up. Region comes from
// AWS_REGION or the active profile, so the same code is portable.
const s3 = new S3Client({});
const out = await s3.send(new ListBucketsCommand({}));
console.log(out.Buckets?.map((b) => b.Name));

FAQs

Why prefer SSO over long-lived access keys?

SSO credentials are short-lived and refresh automatically, so a leaked value expires quickly. Long-lived keys never expire on their own and are the biggest local security risk.

Where should region live?

In ~/.aws/config, inside each profile's block. Region is not a secret and does not belong in the credentials file.

How should I name profiles?

By account and role, for example prod-readonly or staging-deploy. Descriptive names prevent running a command against the wrong account.

What is the single most important rule here?

Never commit the shared files or hardcode keys. A leaked credential in git is a direct breach.

How do I rotate a long-lived key safely?

Create the new key, update the profile, verify with aws sts get-caller-identity, then delete the old key. Never delete first.

Should application code ever contain access keys?

No. Build clients with no credentials and let the default provider chain resolve them, so the same code is portable and secret-free.

Why set region explicitly for v3 credential providers?

fromIni and fromSSO return only credentials, not region. Without region on the client or AWS_REGION, a v3 client throws a region error.

How do I confirm which identity a shell will use?

Run aws sts get-caller-identity. It returns the account and ARN the current environment resolves to.

What should CI use for credentials?

Short-lived credentials from OIDC-based role assumption, or securely injected temporary credentials. Avoid static keys in CI.

How do I keep one login covering many accounts?

Use an sso-session block that multiple profiles reference. A single aws sso login then serves every profile pointing at it.

Do I need to worry about file permissions?

Yes. Restrict the credentials file to your user with chmod 600 ~/.aws/credentials so other local users cannot read it.

Why stay on AWS CLI v2?

Version 1 is end-of-support and lacks SSO login and the sso-session format. Version 2 is the current, supported major.

AWS CLI Setup Basics - install the CLI and create your first profile.
Named Profiles & Multi-Account Config - profile layout and role assumption.
AWS SSO / IAM Identity Center CLI Login - the preferred short-lived credential source.
Environment Variables vs Config File Precedence - which credential source wins.

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+).

AWS CLI Setup Best Practices

A checklist of habits that keep your AWS CLI and SDK credentials secure, portable, and easy to reason about across accounts.

How to Use This List

Walk the categories top to bottom; A (identity) and B (secrets) matter most.
Treat each - [ ] as a rule to verify against your current setup.
Prefer the more secure option even when the quick one works today.
Revisit after any new account, teammate, or CI pipeline is added.
These apply equally to the CLI, boto3, and the AWS SDK for JavaScript v3 - they share the same config.

A - Identity & Credential Source

Prefer IAM Identity Center (SSO) over long-lived keys. aws sso login issues short-lived credentials that expire and refresh, removing static secrets from disk.
Reserve static access keys for last resort. Use them only for a solo experiment or where SSO is not available, and delete them afterward.
Use role assumption for cross-account access. A role_arn + source_profile profile beats copying a second account's keys around.
Use instance or container roles in production. Code running inside AWS should never read copied key files - let the runtime provide credentials.
Require MFA on sensitive roles. Add mfa_serial to role-assumption profiles so a code is required before elevation.

B - Protecting Secrets

Never commit ~/.aws/credentials or ~/.aws/config. Add .aws/ patterns to your global gitignore; a leaked key is a breach.
Never hardcode keys in application code. Let the default credential provider chain resolve them so no secret lives in the repo.
Keep secrets out of shell history. Prefer aws configure prompts or SSO over exporting keys inline where they land in .bash_history.
Restrict file permissions. The shared files should be readable only by your user (chmod 600 ~/.aws/credentials).
Scope keys minimally. Grant each identity only the permissions it needs, so a leak has a small blast radius.

C - Profile Naming & Organization

Name profiles by account and role. prod-readonly, staging-deploy, and dev-admin communicate intent far better than profile1.
Keep region in the config file, not credentials. Region is not a secret and belongs in each profile's config block.
Use an sso-session block for SSO profiles. One shared login covers many account/role profiles instead of repeating the start URL.
Verify names before risky commands. Run aws configure list-profiles so a typo does not point you at the wrong account.
Set a sensible default profile. Make the least-privileged identity your default so an unqualified command is safe.

D - Rotation & Hygiene

Rotate long-lived keys on a schedule. Create the new key, update the profile, verify, then delete the old key.
Delete unused keys and profiles. Every dormant credential is attack surface; remove identities you no longer use.
Audit with get-caller-identity before acting. Confirm which identity a shell resolves to before running anything destructive.
Log out of SSO on shared machines. aws sso logout clears the cached token when you step away.
Upgrade to and stay on AWS CLI v2. Version 1 is end-of-support and lacks SSO and sso-session features.

E - Working With the SDKs

Let the chain resolve credentials. Build clients with no keys so the same code runs locally and in production unchanged.
Select accounts with AWS_PROFILE, not code edits. Keep profile choice in the environment so scripts stay portable.
Set region explicitly for v3 credential providers. fromIni/fromSSO supply credentials only, so pass region or set AWS_REGION.
Do not cache temporary credentials as literals. Resolve through a profile or provider so expired credentials refresh automatically.
Match local and CI credential sources. Use short-lived, injected credentials (OIDC role assumption) in CI rather than static keys.

Here is the secret-free client both SDKs should aim for.

# --- Python (boto3) ---
import boto3
 
# No keys, no region literal: resolved from the profile/env the CLI set up.
# The same code runs on a laptop (SSO/profile) and in production (instance role).
s3 = boto3.client("s3")
print([b["Name"] for b in s3.list_buckets()["Buckets"]])

// --- TypeScript (AWS SDK v3) ---
import { S3Client, ListBucketsCommand } from "@aws-sdk/client-s3";
 
// No keys: resolved from the profile/env the CLI set up. Region comes from
// AWS_REGION or the active profile, so the same code is portable.
const s3 = new S3Client({});
const out = await s3.send(new ListBucketsCommand({}));
console.log(out.Buckets?.map((b) => b.Name));

FAQs

Why prefer SSO over long-lived access keys?

SSO credentials are short-lived and refresh automatically, so a leaked value expires quickly. Long-lived keys never expire on their own and are the biggest local security risk.

Where should region live?

In ~/.aws/config, inside each profile's block. Region is not a secret and does not belong in the credentials file.

How should I name profiles?

By account and role, for example prod-readonly or staging-deploy. Descriptive names prevent running a command against the wrong account.

What is the single most important rule here?

Never commit the shared files or hardcode keys. A leaked credential in git is a direct breach.

How do I rotate a long-lived key safely?

Create the new key, update the profile, verify with aws sts get-caller-identity, then delete the old key. Never delete first.

Should application code ever contain access keys?

No. Build clients with no credentials and let the default provider chain resolve them, so the same code is portable and secret-free.

Why set region explicitly for v3 credential providers?

fromIni and fromSSO return only credentials, not region. Without region on the client or AWS_REGION, a v3 client throws a region error.

How do I confirm which identity a shell will use?

Run aws sts get-caller-identity. It returns the account and ARN the current environment resolves to.

What should CI use for credentials?

Short-lived credentials from OIDC-based role assumption, or securely injected temporary credentials. Avoid static keys in CI.

How do I keep one login covering many accounts?

Use an sso-session block that multiple profiles reference. A single aws sso login then serves every profile pointing at it.

Do I need to worry about file permissions?

Yes. Restrict the credentials file to your user with chmod 600 ~/.aws/credentials so other local users cannot read it.

Why stay on AWS CLI v2?

Version 1 is end-of-support and lacks SSO login and the sso-session format. Version 2 is the current, supported major.

AWS CLI Setup Basics - install the CLI and create your first profile.
Named Profiles & Multi-Account Config - profile layout and role assumption.
AWS SSO / IAM Identity Center CLI Login - the preferred short-lived credential source.
Environment Variables vs Config File Precedence - which credential source wins.

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+).

AWS CLI Setup Best Practices

Buscar na documentação

AWS CLI Setup Best Practices