Tmp

AWS Credentials File: Configure and Use ~/.aws/credentials

Learn how to configure AWS CLI and SDK profiles in ~/.aws/credentials, use temporary and role-based credentials, select profiles, verify identities, and protect secrets.

The AWS shared credentials file lets the AWS CLI and many AWS SDKs find credentials for local development and command-line work. Its usual location is ~/.aws/credentials on macOS and Linux, or %UserProfile%\.aws\credentials on Windows.

This lesson explains profiles, the companion config file, credential provider precedence, temporary credentials, IAM Identity Center, role assumption, troubleshooting, and secure lifecycle management.

What AWS Credentials Do

AWS credentials are values or tokens used to authenticate requests to AWS. They identify an IAM principal, such as an IAM user or an assumed IAM role, and allow the AWS CLI or SDK to sign requests to AWS services.

Authentication answers “Who is making this request?” Authorization answers “What is that principal allowed to do?” Credentials help establish identity, while IAM policies, resource policies, permission boundaries, service control policies, and explicit denies determine authorization.

• Access key ID: The public identifier portion of an access key.
• Secret access key: The confidential value used to sign AWS requests. Never disclose it.
• Session token: An additional value required with temporary credentials.

A request made with an invalid identity can fail authentication. A request made with a valid identity that lacks permission can fail with AccessDenied.

Credential Types and Recommended Choices

Prefer credentials that are short-lived and supplied by an IAM role or a sign-in system. Long-term access keys should be a fallback for specific cases, not the default for human or workload access.

Do not create or use root user access keys for normal work. Protect the root user separately and use IAM roles or delegated identities for administration.

The Shared AWS Credentials File

The shared credentials file is an INI-style text file containing profile sections. A profile is a named set of credential and configuration settings. The default profile is selected when no other profile is specified.

Default locations are:

• macOS and Linux: ~/.aws/credentials
• Windows: %UserProfile%\.aws\credentials

A standard credentials file can contain a default profile and named profiles:

[default]
aws_access_key_id = AKIAEXAMPLE
aws_secret_access_key = example-secret-value

[development]
aws_access_key_id = AKIADEVEXAMPLE
aws_secret_access_key = example-development-secret

[temporary]
aws_access_key_id = ASIAEXAMPLE
aws_secret_access_key = example-temporary-secret
aws_session_token = example-session-token

The values beginning with example- are placeholders, not usable credentials. In a real file, the secret access key and session token are sensitive.

Credentials File Field Reference

Profile names in the credentials file do not use the profile prefix. Use [development], not [profile development].

The AWS Config File

The companion config file is normally ~/.aws/config on macOS and Linux, or %UserProfile%\.aws\config on Windows. It stores non-secret settings such as Region and output format, as well as role and IAM Identity Center configuration.

Its profile naming convention differs from the credentials file:

• Default profile: [default]
• Named profile: [profile development]
• Credentials file named profile: [development]

[default]
region = us-east-1
output = json

[profile development]
region = us-west-2
output = json

[profile production-role]
role_arn = arn:aws:iam::123456789012:role/ReadOnlyRole
source_profile = development
role_session_name = local-cli-session
region = us-east-1

When the CLI or SDK selects development, it combines credentials from [development] in the credentials file with settings from [profile development] in the config file. Keep credentials in the credentials file and general settings in the config file unless a supported authentication method requires another arrangement.

Creating and Selecting Profiles

The interactive commands create or update profiles without requiring manual editing:

aws configure
aws configure --profile development

The first command configures the default profile. The second configures a named profile. You can then edit the config file to set a Region and output format, or use the CLI configuration commands for those settings.

Use a profile explicitly for one command:

aws sts get-caller-identity --profile development
aws s3 ls --profile development

Use a profile for the current shell session:

export AWS_PROFILE=development
aws sts get-caller-identity

On Windows PowerShell, the equivalent session variable is:

$env:AWS_PROFILE = "development"

Use distinct profiles for separate AWS accounts, development and production environments, or different job roles. Explicit selection helps prevent an operation intended for one account from running in another.

Profile Selection Methods

Credential Provider Precedence

The AWS CLI and SDKs use a credential provider chain: an ordered collection of locations and mechanisms consulted for credentials. Exact ordering and supported providers vary by CLI or SDK version, but common sources include:

1. Command-line settings that select a profile or configure a command.
2. Environment credentials such as AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN.
3. The shared credentials and config files.
4. IAM Identity Center profile configuration and its cached sign-in tokens.
5. Process-based credential providers configured to obtain credentials from an external command.
6. Instance, container, or other workload role credentials supplied by the runtime.

Environment variables can unexpectedly override values you believe are coming from a profile. A shell, CI runner, IDE, container, or parent process may already define them. Always verify the effective identity instead of assuming which provider won.

aws configure list
aws sts get-caller-identity

Verifying the Active Identity

AWS STS GetCallerIdentity reports the account and principal associated with the credentials currently in use. It is a safe first check after changing profiles or credential sources:

aws sts get-caller-identity --profile development

The response includes an account ID, an ARN, and a user ID. Common ARN forms include:

• arn:aws:iam::123456789012:user/alice identifies an IAM user.
• arn:aws:sts::123456789012:assumed-role/ReadOnlyRole/session-name identifies temporary credentials from an assumed role.
• A federated identity ARN indicates access obtained through a federation or sign-in workflow.

For a sensitive command, verify the identity immediately before running it and confirm both the account ID and role or user name.

Temporary Credentials and Expiration

Temporary credentials have an expiration time. They commonly consist of an access key ID, secret access key, and session token. The session token must travel with the other two values; a manually copied temporary key without its token is incomplete.

Expired credentials commonly produce ExpiredToken, token-related authentication errors, or failures after a session worked earlier. Refresh depends on the source:

• IAM Identity Center: run aws sso login --profile workforce again.
• Assume-role workflows: renew the source credentials or create a new role session.
• External credential tools: run the tool's approved refresh or login workflow.
• Manually copied temporary values: obtain and copy a new complete set before expiration.

Assume-Role Profiles

An assumed role is a temporary identity obtained through AWS STS. A role profile normally belongs in the config file and names a role_arn and a source_profile. The source profile supplies credentials that are allowed to assume the target role.

[development]
aws_access_key_id = AKIADEVEXAMPLE
aws_secret_access_key = example-development-secret

[profile production-role]
role_arn = arn:aws:iam::123456789012:role/ReadOnlyRole
source_profile = development
role_session_name = local-cli-session
region = us-east-1

Use the role profile like this:

aws sts get-caller-identity --profile production-role
aws s3 ls --profile production-role

For cross-account access, the source principal belongs to one account and assumes a role trusted by the target account. The target role's trust policy and the source principal's permissions must both allow the operation. The resulting credentials are temporary and identify the assumed role, not the source user.

IAM Identity Center Integration

IAM Identity Center is a preferred interactive workforce authentication method. It lets a person sign in and receive access to assigned AWS accounts and roles without managing long-term IAM user keys locally.

aws configure sso
aws sso login --profile workforce
aws sts get-caller-identity --profile workforce

The CLI caches sign-in tokens locally so supported commands can obtain temporary credentials. Do not copy those tokens into the shared credentials file as permanent access keys. Sign in again when the cached session expires or when the CLI requests renewal.

Environment Variables and Alternate File Locations

Environment variables are useful for CI jobs, isolated test environments, and temporary command sessions:

• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY
• AWS_SESSION_TOKEN
• AWS_PROFILE
• AWS_DEFAULT_REGION
• AWS_SHARED_CREDENTIALS_FILE
• AWS_CONFIG_FILE

For example, use custom files in an isolated environment:

export AWS_SHARED_CREDENTIALS_FILE="$HOME/.config/aws/credentials"
export AWS_CONFIG_FILE="$HOME/.config/aws/config"

In CI, prefer the platform's secure secret mechanism, workload identity, or an OIDC-to-role workflow. Never put secrets directly in shell history, application source code, committed .env files, build logs, or command lines that other users can inspect.

Security and Operational Hygiene

• Apply least privilege: grant only the permissions needed for the task.
• Prefer IAM roles and short-lived credentials over long-term access keys.
• Restrict local file permissions. On macOS and Linux, use chmod 600 ~/.aws/credentials and chmod 600 ~/.aws/config.
• Do not use credential files on shared workstations or home directories with broad access unless the environment is properly isolated.
• Keep credential files out of source control and broadly accessible backups.
• Use secret scanning and appropriate AWS monitoring services to detect exposure and suspicious activity.
• Never publish credentials in documentation, support tickets, logs, screenshots, or terminal recordings.
• If a key is exposed, deactivate or delete it immediately, investigate its use, and replace it with a safer approved mechanism.

Credential Lifecycle Management

1. Create a long-term access key only when a documented need exists.
2. Record its owner, purpose, system, and expected lifetime.
3. Apply the smallest practical IAM permissions.
4. Rotate keys on the organization's schedule and immediately after suspected exposure.
5. Delete unused keys and obsolete profiles.
6. When an employee, project, or account changes, revoke access promptly and review role trust relationships and automation.

Practical Workflows

Default Local CLI Profile

Run aws configure, place the resulting credentials in the default profile, and set region = us-east-1 and output = json in the default config section. Then verify:

aws sts get-caller-identity

Development and Production Profiles

Create separate named profiles, select them explicitly, and verify the account before sensitive actions:

aws sts get-caller-identity --profile development
aws sts get-caller-identity --profile production-role

Use separate roles and least-privilege policies so that development credentials cannot accidentally perform production administration.

Isolated CI Task

Supply short-lived credentials through the CI platform's secure mechanism or attach a workload role. If custom paths are required, set AWS_SHARED_CREDENTIALS_FILE and AWS_CONFIG_FILE only within the job environment, and remove temporary files after the task.

Troubleshooting

Key Exam Notes

• The credentials file normally stores aws_access_key_id, aws_secret_access_key, and, for temporary credentials, aws_session_token.
• Credentials profile sections use [name]; named config sections use [profile name].
• --profile selects one command, while AWS_PROFILE affects the current process environment.
• Environment credentials can override profile-based credentials, so verify the effective identity.
• aws sts get-caller-identity reveals the account and principal currently in use.
• Temporary credentials expire and require a session token; refresh the originating login or role session.
• Use IAM roles, IAM Identity Center, and workload credentials instead of root keys or unnecessary long-term IAM user keys.

For continued reference, see AWS credentials file configuration.