VMware ESXi and vSphere Cluster Management

AWS Credentials File: Configuration, Profiles, and Secure Usage

Learn how to configure ~/.aws/credentials, use AWS profiles, understand the credential provider chain, assume roles, use IAM Identity Center, and troubleshoot AWS authentication securely.

The AWS shared credentials file lets the AWS CLI and many AWS SDKs find credentials for local API requests. Its default location is ~/.aws/credentials. This guide explains how the file works, how it relates to ~/.aws/config, how profiles and temporary credentials are selected, and how to avoid exposing secrets.

What AWS credentials do

AWS credentials are values or tokens used to authenticate requests to AWS. Authentication answers, “Who is making this request?” Authorization answers, “What is that identity allowed to do?” AWS evaluates both before allowing an API operation.

An access key ID is the public identifier portion of an access key. A secret access key is the confidential signing secret paired with it. Together, they can authenticate an IAM user or another credential source. Temporary credentials also include a session token, which must be sent with the access key ID and secret access key.

• Access keys: Long-lived IAM user keys or temporary keys issued by AWS STS.
• IAM roles: AWS identities that provide temporary credentials to trusted users, services, or workloads.
• IAM Identity Center: Interactive workforce sign-in that lets users select an AWS account and role without creating long-lived IAM user keys.
• Workload identity: Credentials supplied to EC2, ECS, EKS, or other AWS-hosted workloads through roles and metadata or identity endpoints.

The shared AWS credentials file

The shared credentials file is normally stored at ~/.aws/credentials, where ~ means the current user’s home directory. On Windows, AWS tools use the equivalent AWS configuration directory for the current user.

The file uses an INI-style format: a section header in square brackets followed by key-value pairs.

[default]
aws_access_key_id = EXAMPLEACCESSKEY
aws_secret_access_key = EXAMPLESECRETKEY

[development]
aws_access_key_id = EXAMPLEDEVACCESSKEY
aws_secret_access_key = EXAMPLEDEVSECRETKEY

[default] is the default profile. It is selected when no other profile is specified. A named profile such as development separates credentials for another account, environment, or identity.

Creating a default profile

Run the interactive configuration command and answer its prompts:

aws configure

This normally writes access-key values to ~/.aws/credentials and general settings such as the default region and output format to ~/.aws/config.

A redacted credentials file might look like this:

[default]
aws_access_key_id = EXAMPLEACCESSKEY
aws_secret_access_key = EXAMPLESECRETKEY

Never use example values as real credentials. Do not paste real secret values into documentation, shell history, tickets, or chat.

Creating a named profile

Use a named profile when you work with separate accounts, environments, or roles:

aws configure --profile development

The resulting credentials section is named [development]. Keeping development and production identities separate reduces the chance of running a destructive command in the wrong account.

Credentials file versus AWS config file

AWS tools commonly combine information from two local files. Credentials are normally kept in ~/.aws/credentials, while behavior and profile settings commonly belong in ~/.aws/config.

For example, a config file can contain:

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

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

The CLI and SDKs resolve the selected profile by combining the matching sections from both files. A profile named development in the credentials file corresponds to [profile development] in the config file.

Credential fields and file permissions

• aws_access_key_id identifies the credential.
• aws_secret_access_key signs requests and must remain confidential.
• aws_session_token is required when the access key and secret are temporary.

Temporary credentials expire. If the session token is missing, expired, or paired with the wrong access key and secret, requests fail even when the other fields appear correct.

On Unix-like systems, restrict the AWS directory and credentials file:

chmod 700 ~/.aws && chmod 600 ~/.aws/credentials

Use equivalent access controls on other operating systems. Also protect backups, terminal logs, environment dumps, container layers, and editor swap files.

Never commit the credentials file to source control. Add sensitive local files to appropriate ignore rules, enable secret scanning, and treat any exposed key as compromised until it has been deactivated or rotated.

Selecting profiles

Use a profile for one command

aws sts get-caller-identity --profile development

This is useful for high-risk commands because the intended identity is visible in the command itself.

Set a profile for the current shell

export AWS_PROFILE=development

On Windows PowerShell, the equivalent is:

$env:AWS_PROFILE = "development"

After setting the variable, commands that support profile selection use that profile unless a more explicit setting overrides it.

Profile precedence

Exact provider behavior can vary by AWS CLI or SDK, but the practical ordering is:

1. Explicit application settings or command options, such as a command-level profile option.
2. Credential-related environment variables such as AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN.
3. The profile selected by AWS_PROFILE or an application’s profile setting.
4. Shared credentials and config files.
5. Other providers such as credential processes, web identity, container credentials, or instance roles.

For region and output settings, command options commonly override environment variables, which commonly override profile configuration. When values conflict, inspect the effective configuration rather than guessing.

The credential provider chain

The credential provider chain is the ordered process an AWS tool uses to locate credentials. A local profile may exist but not be used if an earlier provider supplies credentials.

The chain and its exact order differ between SDKs and versions. For an application that behaves unexpectedly, inspect its SDK documentation and runtime environment. Check whether environment variables, a container endpoint, an instance role, or an application-supplied credential object is taking precedence over the local file.

Temporary credentials and role assumption

A role profile lets a tool use one configured identity to assume another IAM role. The resulting credentials are temporary and include an access key ID, secret access key, session token, and expiration time.

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

Here, the development profile supplies the source credentials. The CLI or SDK requests the DeploymentRole credentials through AWS STS and uses them for the operation. The source identity must be allowed to assume the role, and the role trust policy must trust that source.

Supported tools can refresh role credentials as needed. Manually copying temporary values is fragile because the values expire and all three credential components must remain synchronized. It can also encourage the creation of unnecessarily powerful permanent keys.

IAM Identity Center for modern local authentication

IAM Identity Center is generally preferred for human developer access when an organization uses centralized workforce identity, federated sign-in, or multi-factor authentication. It avoids creating long-lived IAM user access keys for each developer.

An Identity Center setup typically has three related parts:

• An SSO session configuration that describes the sign-in session and Identity Center start information.
• A named profile that identifies an AWS account, permission set, and region.
• Cached short-lived tokens created after interactive sign-in and reused until they expire.

These settings generally belong in ~/.aws/config, not as static secrets in ~/.aws/credentials. The CLI can prompt for sign-in through the supported SSO flow, then obtain temporary role credentials for the selected account and permission set. Renew the session through that flow rather than replacing it with a permanent administrator key.

Security practices

• Grant only the permissions required for the task: this is the principle of least privilege.
• Do not create or use root-user access keys.
• Do not share keys in chat, tickets, screenshots, repositories, container images, browser code, or client-side applications.
• Use workload IAM roles for deployed applications, such as EC2 instance profiles, ECS task roles, or an appropriate Kubernetes workload identity.
• Store application secrets in a managed secret service such as AWS Secrets Manager or Systems Manager Parameter Store when a workload genuinely needs a secret.
• Use MFA and short-lived sessions for human access where appropriate.
• Deactivate or rotate exposed keys promptly, then investigate logs and remove the secret from every copied location.
• Keep production profiles and development profiles distinct, and verify the account before destructive operations.

Verification and diagnostics

Verify the active identity

AWS STS can report the account and principal associated with the current credentials:

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

Run this before account-sensitive work. The result includes an account identifier and an ARN, not the secret key.

Inspect resolved configuration safely

aws configure list --profile development

This helps show whether values came from a profile, environment variable, or another source. Review the output without copying or displaying secret values.

Common failures

Practical workflow

1. Choose the safest credential source: IAM Identity Center or a workload role where possible.
2. If static local credentials are unavoidable, create a least-privilege profile with aws configure --profile name.
3. Keep secrets in ~/.aws/credentials and region or output settings in ~/.aws/config.
4. Select the profile explicitly with --profile name for important commands, or set AWS_PROFILE for a controlled shell session.
5. Run aws sts get-caller-identity and confirm the account and principal before changing resources.
6. When a command fails, inspect the effective source and identity before changing permissions or credentials.

For related material, see AWS credentials file reference and the AWS development topics.