Root

AWS Shared Credentials File: Configuration and Usage

Learn how to create, format, secure, and use the AWS shared credentials file with AWS CLI, SDKs, named profiles, and temporary credentials.

AWS command-line tools and applications must identify an AWS identity before they can make authenticated API requests. The AWS shared credentials file is one local credential source supported by the AWS CLI and many AWS SDKs.

Authentication answers “Who is making this request?” Authorization answers “What is that identity allowed to do?” The credentials file helps provide authentication material, while IAM policies, permissions boundaries, resource policies, organization controls, and explicit denies determine authorization.

Where the shared credentials file is located

The default path is based on the home directory of the operating-system user running the AWS tool. It is not automatically a system-wide file.

The file belongs to the operating-system user whose home directory contains it. A file in /home/alex/.aws/credentials is not necessarily available when the command runs as root, a service account, or another user.

export AWS_SHARED_CREDENTIALS_FILE=/secure/path/credentials

On Unix-like systems, that command changes the path for commands launched from the current shell. Set the equivalent environment variable using the conventions of your Windows shell when needed.

File format and profiles

The shared credentials file uses an INI-style format. A section header names a profile, and key-value lines underneath it contain credentials. The default profile is the section named [default]. A named profile is any other labeled section, such as [development] or [production].

Default profile with long-term keys

[default]
aws_access_key_id = EXAMPLEACCESSKEYID
aws_secret_access_key = exampleSecretAccessKey

The access key ID is the non-secret identifier. The secret access key is the secret value used to sign requests. The example values above are placeholders and are not usable credentials.

Named profile with temporary credentials

[development]
aws_access_key_id = EXAMPLEACCESSKEYID
aws_secret_access_key = exampleSecretAccessKey
aws_session_token = exampleSessionToken

Temporary credentials have three parts: an access key ID, a secret access key, and a session token. The token is required along with the two key values. Temporary credentials also have an expiration time, so they must be refreshed.

Default and named profiles

A profile can be selected by an AWS CLI flag, the AWS_PROFILE environment variable, SDK configuration, or application code. When no profile is specified, the default profile is normally considered.

aws sts get-caller-identity --profile development

AWS_PROFILE=development aws sts get-caller-identity

The credentials file and the AWS config file

The shared credentials file is intended primarily for credential values. The separate AWS config file commonly stores non-secret settings such as the region and output format, as well as role-assumption settings.

Profile section syntax differs between the two files. In the credentials file, use [profile-name], including [default] for the default profile. In the config file, non-default profiles normally use [profile profile-name], while the default section remains [default].

Role profile using a source profile

A role profile uses a source profile to obtain base credentials and then asks AWS STS to assume an IAM role. The base credentials remain in the credentials file, while the role settings belong in the config file.

[profile reporting-role]
role_arn = arn:aws:iam::123456789012:role/ReportingRole
source_profile = development
region = us-east-1

This example uses fictional account and role values. Role-based profiles are safer than embedding long-term keys in an application because the application can use temporary credentials produced by role assumption.

Other temporary mechanisms include external credential processes and IAM Identity Center profiles. These mechanisms obtain or refresh credentials through an approved identity workflow instead of requiring a permanent secret key in the file.

Creating and updating the file

Using the AWS CLI configuration wizard

Use aws configure to create or update the default profile interactively:

aws configure

For a named profile, include --profile:

aws configure --profile development

The wizard typically asks for an access key ID, secret access key, default region, and output format. Credential values are written to the shared credentials file, while region and output preferences are generally written to the config file.

Editing the file manually

Manual creation is also possible. Create the .aws directory if necessary, then preserve the INI section and key syntax exactly. Avoid extra quotation marks, incomplete values, malformed section headers, or accidentally copying spaces into a secret.

Manual editing is useful for carefully managed temporary credentials, automation setup, or reviewing a profile, but it increases the chance of exposing secrets in an editor, terminal transcript, or backup. Use a secure editor and remove temporary copies.

Obtaining credentials safely

• Prefer IAM roles for AWS compute, IAM Identity Center for workforce access, or another temporary credential mechanism.
• If access keys are necessary, create them only for an appropriate IAM identity and only for the required purpose.
• Apply least privilege: grant only the permissions needed for the task.
• Do not use the AWS account root user for routine command-line or application access.
• When a secret access key is created, save and protect it immediately. AWS displays the secret only at creation time.

Long-term user keys can remain valid until rotated, deactivated, or deleted. Temporary role credentials limit the useful lifetime of stolen values and can be governed by role-session controls, making them preferable for most workloads.

Credential provider chains

A credential provider chain is the ordered collection of sources an AWS tool or SDK checks for credentials. Possible sources include explicit application settings, environment variables, shared files, external processes, container credentials, and instance or workload roles.

The exact order can differ between AWS tools, SDKs, and versions. An environment variable, an application-provided credential, a container credential endpoint, or an instance role may therefore be used instead of the file you expected. Never assume that the presence of a credentials file proves it is active.

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

aws configure list helps show active values and their sources. Inspect relevant AWS_ environment variables and application configuration when the reported source is unexpected.

Security and secret handling

Treat ~/.aws/credentials as a secret-bearing file. On Linux and macOS, restrict it to the file owner:

chmod 600 ~/.aws/credentials

Also restrict the containing directory where appropriate, and do not share the file between operating-system users. On Windows, use file permissions and account controls that prevent other users from reading it.

• Keep credentials files out of source repositories, shell history, logs, screenshots, public file shares, and unprotected backups.
• Add credential paths and local secret files to .gitignore.
• Use secret scanning and repository protection rules.
• Remember that .gitignore does not remove a secret already committed; exposed history must be handled separately.
• Never put long-term secrets in application source code, AMIs, container images, or client-side web applications.

If a credential is exposed

1. Immediately deactivate or rotate the affected access key. Delete it when it is no longer needed.
2. Remove the secret from exposed locations and repository history where possible.
3. Review CloudTrail and other relevant activity for unauthorized use.
4. Investigate how the exposure happened and add controls such as secret scanning, protected branches, and workload roles.

Verification and maintenance

Verify the active identity with AWS STS. This operation is useful because it normally does not require broad service permissions:

aws sts get-caller-identity --profile development

Use the following commands during setup and troubleshooting:

• aws sts get-caller-identity verifies the identity selected by the current environment.
• aws configure list shows configuration values and likely sources.
• aws configure list-profiles lists available profile names.

Where long-term keys cannot be avoided, maintain an inventory, rotate them periodically, and remove obsolete profiles. Revoke credentials when a user, project, device, or automation process no longer requires access.

Environment-specific behavior

The current user, HOME variable, sudo behavior, service-account configuration, and container runtime can all change which file is read.

Running with sudo

A normal user may have credentials at /home/alex/.aws/credentials. Running an AWS command through sudo commonly changes the effective user to root, so the CLI may instead read /root/.aws/credentials. Environment variables may also be removed or changed by privilege escalation.

Check the effective user and home directory in the execution environment. Avoid copying personal credentials into root's directory merely to make a command work. Use an explicitly approved credential source or configure the service under its own identity.

Containers and AWS-hosted workloads

Do not copy a developer's credentials file into a container image or bake secrets into an AMI. Prefer workload roles: EC2 instance roles, ECS task roles, EKS pod identity or IAM roles for service accounts, and Lambda execution roles. These mechanisms let the workload obtain temporary credentials without storing a permanent secret in the artifact.

Troubleshooting

Unable to locate credentials

• Check whether the current user has a credentials file.
• Run aws configure list and aws configure list-profiles.
• Confirm that the intended profile was selected.
• Check HOME and AWS_SHARED_CREDENTIALS_FILE.
• Check whether the process runs as root or a service account.

The wrong account or identity is used

Run aws sts get-caller-identity, inspect the sources reported by aws configure list, and review AWS_PROFILE plus other credential-related environment variables. A role, container source, instance role, or environment credential may be overriding the file.

Authentication errors

Errors such as InvalidClientTokenId, signature errors, or access-key failures can result from a copied key, a deactivated or deleted key, a key from another account, a missing session token, or expired temporary credentials. Reconfigure with valid values and include all three temporary-credential fields.

AccessDenied

AccessDenied means authentication may have succeeded but authorization failed. Verify the identity first, then review IAM policies, organization service control policies, permissions boundaries, session policies, resource policies, and explicit denies. Fix the specific least-privilege permission requirement rather than switching to a more powerful credential.

Exam-relevant notes

• ~/.aws/credentials stores profile-based credential values; the config file commonly stores region, output, and role settings.
• Temporary credentials require an access key ID, secret access key, and session token, and they expire.
• --profile NAME applies to one CLI command, while AWS_PROFILE=NAME selects a profile through the environment.
• When no named profile is selected, the default profile is normally used, but another provider can win in the provider chain.
• Running as root can cause AWS tools to read /root/.aws/credentials.
• Authentication does not grant permissions; IAM authorization still applies.