AWS Credentials File and Credential Management

Learn how AWS credentials, profiles, environment variables, IAM roles, and temporary sessions work in the AWS CLI and SDKs.

What AWS credentials do

AWS credentials authenticate an IAM principal when the AWS CLI, an SDK, or another tool calls an AWS service. An IAM principal is an identity that can make AWS requests, such as an IAM user, an assumed IAM role, or a federated session.

Programmatic authentication commonly uses these values:

AWS access key ID: The identifier for a programmatic access key.
Secret access key: The confidential value paired with the access key ID. It must be protected like a password.
Session token: An additional value required with temporary credentials.

Credentials are separate from authorization. Credentials identify the caller; IAM policies determine what that caller is allowed to do.

Long-term and temporary credentials

Type	Components	Lifetime	Recommended use
Long-term access key	Access key ID and secret access key	Until deactivated, deleted, or rotated	Limited local development cases; avoid for production workloads
Temporary session credentials	Access key ID, secret access key, and session token	Short, defined session period	IAM roles, federation, IAM Identity Center, and workloads

An IAM user can have long-term access keys, but persistent keys create a theft and rotation risk. An IAM role is an assumable identity that normally provides temporary credentials. AWS STS, the AWS Security Token Service, issues temporary credentials and can report the identity making a request.

The shared AWS credentials file

The shared credentials file is a local INI-style file containing access-key-based credential profiles. Its usual location is ~/.aws/credentials on Linux and macOS, and the equivalent .aws\credentials directory under the current user's home directory on Windows. The exact location can be changed by AWS tooling or environment configuration.

INI-style files use profile sections in square brackets and key-value entries. A credentials file can contain a default profile and multiple named profiles:

[default]
aws_access_key_id = EXAMPLEACCESSKEY
aws_secret_access_key = EXAMPLESECRETKEY

[development]
aws_access_key_id = DEVEXAMPLEACCESSKEY
aws_secret_access_key = DEVEXAMPLESECRETKEY

Do not treat example values as a safe way to test access. Use aws configure, federation, or a role-based method instead of manually copying secrets whenever possible.

Credentials file versus AWS config file

File	Typical location	Common settings	Profile section format
Shared credentials file	`~/.aws/credentials`	Access key ID, secret access key, and session token	`[default]` or `[development]`
AWS config file	`~/.aws/config`	Region, output format, role settings, SSO settings, and other profile configuration	`[default]` or `[profile development]`

The credentials file is primarily for credential values. The AWS config file is primarily for non-secret settings and role or federation configuration. AWS CLI configuration can use both files as one profile configuration. A named profile is written as [profile name] in the config file but as [name] in the credentials file.

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

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

Keep both files private. A local credentials file should not be committed to source control or copied into an application image.

Default and named profiles

A profile is a named set of AWS credential and configuration settings. The default profile is used when no other profile is selected. Named profiles allow different accounts, roles, Regions, environments, or identities to coexist without replacing one another.

For example, a developer might use development for an engineering account and an assume-role profile for read-only production access. Profile names reduce accidental reliance on one global identity, but you should still verify the active identity before making changes.

Method	Example	Scope	When to use
CLI profile option	`aws s3 ls --profile development`	One command	Safely run one operation with a non-default profile
`AWS_PROFILE`	`export AWS_PROFILE=development`	Current shell and processes started from it	Use one profile for a terminal session
Default profile	`aws s3 ls`	Command or application with no explicit selection	Simple local use; avoid assuming it is the intended account
SDK profile configuration	SDK-specific profile or session setting	One application process	Local development when a named profile is required

AWS_PROFILE selects a profile, while AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN provide credential values directly through the environment. Those credential variables can override the credentials you expected a profile to provide.

For details about environment variables exposed to a process, see environment inspection. Do not expose secret environment values in logs, diagnostic output, or shell history.

Credential provider chain and precedence

The credential provider chain is the ordered process used by the AWS CLI and SDKs to locate usable credentials. Exact ordering can vary by tool and SDK version, but common sources include explicit settings, environment variables, shared files, and runtime role providers.

Credential source	Typical use case	How it is selected	Security considerations
Explicit command or application settings	One command or a deliberately constructed SDK client	Command option, SDK session argument, or explicit credential configuration	Can bypass the profile you expected; never place secrets in scripts or source code
Environment variables	CI jobs, temporary shell sessions, and injected configuration	`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and optional `AWS_SESSION_TOKEN`	May override profiles and leak through logs, process diagnostics, or job output
Shared credentials and config files	Local CLI and SDK development	Default or selected named profile	Protect file permissions and exclude files from source control
Role-based sources	Assume-role profiles, IAM Identity Center, and federation	Profile configuration or login session	Prefer short-lived credentials and renew sessions safely
Container credentials	ECS tasks and compatible container runtimes	Runtime-provided endpoint and task role	Use task roles and restrict task permissions
EC2 instance metadata	Applications running on EC2	Instance profile and metadata service	Use an instance role and protect metadata access from untrusted processes

An unexpected source can win because it appears earlier in the provider chain. For example, an old AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY in a shell can cause a command to use those credentials even when AWS_PROFILE=development is set. Runtime credentials can similarly be used instead of a local file when an application runs on EC2, ECS, or Lambda.

Configuring AWS CLI credentials

Interactive configuration

Use the AWS CLI configuration command to create or update the default profile without manually editing files:

aws configure

The command asks for an access key ID, secret access key, default Region, and output format. To configure a named profile, use:

aws configure --profile development

Access-key values normally go to the shared credentials file. The default Region and output format normally go to the AWS config file. A Region controls where a regional service request is sent; it does not change the account or identity.

Inspecting the configuration

aws configure list-profiles
aws configure list --profile development

The first command lists profile names. The second displays the effective configuration and indicates where values came from. Treat command output as potentially sensitive because it can reveal credential-source details.

Temporary credentials and IAM roles

For production and workload authentication, prefer IAM roles, IAM Identity Center, workload identity, or another federation mechanism over persistent access keys. A role supplies temporary credentials and can limit both permissions and session duration.

An assume-role profile starts with a base identity, called the source profile, and requests temporary credentials for a target role identified by a role_arn. A target role must trust the source principal, and the source principal must be allowed to call sts:AssumeRole.

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

Some role trust policies require an external ID, especially for controlled third-party access. Others require MFA. The profile or tool must provide the required external ID or MFA information according to the role's configuration.

Temporary credentials expire. The CLI or SDK can refresh them when it owns the underlying session and the source authentication is still valid. An expired SSO login, MFA session, or federated session may require a new login before the role can be refreshed.

Using credentials with SDKs and tools

AWS SDKs generally use a default credential provider chain. This lets the same application obtain credentials from environment variables during a controlled test, a named local profile during development, or an IAM role when deployed.

An application can select a named profile through its SDK's session or profile configuration. In deployed environments, prefer runtime-provided role credentials:

EC2 applications should use an instance profile and IAM role.
ECS tasks should use a task role rather than host-wide access keys.
Lambda functions should use an execution role.

Do not embed access keys in source code, container images, application configuration, or checked-in deployment manifests. Do not use a secret manager merely to preserve a long-lived key when the platform can provide a role or federated identity directly.

Credential security practices

Never commit ~/.aws/credentials, access keys, session tokens, or copied configuration containing secrets to source control.
Use least privilege: grant only the permissions required for the task, account, resource, and duration.
Restrict local file permissions so other local users cannot read credential files. On systems with Unix permissions, a typical goal is owner read/write access only, such as chmod 600 ~/.aws/credentials.
Prefer IAM Identity Center, IAM roles, workload identity, or federation over persistent access keys where available.
Rotate keys that must exist, and deactivate or delete unused keys.
Monitor access-key use and investigate unexpected activity.
Redact credentials before sharing logs, support output, screenshots, or diagnostic bundles.

For a local account overview, see the related user account information lesson, but never use operating-system account files as an AWS credential store.

If an access key is exposed

Deactivate the exposed key immediately, or follow your incident process to disable it safely.
Review CloudTrail and other available logs for suspicious use.
Remove the secret from repositories, build artifacts, images, logs, and shared files. Removing it from the latest commit does not erase it from all repository history or copies.
Replace the workflow with a role or federation where possible.
If the key must remain, create a replacement with least privilege, update consumers securely, test it, and then delete the compromised key.

Inspection and troubleshooting

Always validate the effective identity with AWS STS:

aws sts get-caller-identity

The response identifies the AWS account and the caller ARN. Run it with the same profile, shell, container, or host context as the command that will make the change.

Symptom or error	Likely cause	How to verify	Resolution
Unable to locate credentials	No configured profile or environment credentials; missing file; wrong profile; or unavailable runtime role	Run `aws configure list`, `aws configure list-profiles`, and inspect `AWS_PROFILE`	Configure or select the intended profile, or attach and permit the appropriate runtime role
Wrong AWS account or identity	Environment variables override the profile, default profile is used, or an existing SSO or assumed-role session is active	Run `aws sts get-caller-identity` and `aws configure list`; inspect AWS credential variables	Remove unintended overrides, select the intended profile explicitly, and verify again
`ExpiredToken` or another token error	Temporary credentials or an environment session token expired	Check whether credentials are temporary and inspect `AWS_SESSION_TOKEN`	Renew the SSO, federation, or assumed-role session and remove stale environment values
`AccessDenied` after authentication succeeds	Missing permission, explicit deny, permissions boundary, SCP, session policy, or wrong role	Confirm caller identity and review the denied action, resource, and applicable policies	Use the correct identity or grant narrowly scoped permission consistent with least privilege
Assume-role profile fails	Incorrect role ARN or source profile; missing `sts:AssumeRole`; trust, MFA, or external ID problem	Validate the source identity and review source permissions and target trust policy	Correct the profile and satisfy both caller permission and target-role trust requirements
Credentials work on one machine but not another	Different files, environment variables, home directories, CLI or SDK versions, SSO state, or runtime roles	Compare `aws configure list`, active identity, file paths, and environment variables	Standardize authentication and avoid transferring long-lived secret files between machines
Request reaches the wrong Region	Incorrect profile Region, command override, or missing Region setting	Inspect `aws configure list` and the command's Region option	Set the intended Region in the selected profile or command; remember that Region does not select an account

Practical workflow: separate development and production access

Configure a development profile with aws configure --profile development, or use a federated login that creates the profile.
Configure a production role profile with role_arn and source_profile.
List profiles with aws configure list-profiles.
Verify development before use: aws sts get-caller-identity --profile development.
Use the production profile only for the individual command that requires it, for example:

aws s3 ls --profile production-readonly

Before a destructive operation, verify the caller identity and Region again. This habit catches both account-selection errors and Region mistakes before they affect resources.

Exam-relevant notes

The access key ID identifies a programmatic key; the secret access key authenticates it; temporary credentials also require a session token.
The shared credentials file and AWS config file are related but distinct. Credentials generally belong in the former; Region, output, and role settings generally belong in the latter.
The default profile is used only when no more specific profile or credential source wins.
AWS_PROFILE selects a profile, while AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN provide environment credentials that may override file-based values.
IAM roles and temporary credentials are preferred for workloads because they reduce dependence on persistent secrets.
An assume-role operation requires both permission for the source principal and trust from the target role; MFA or an external ID may also be required.
aws sts get-caller-identity is the practical way to confirm which account and principal are active.