@Fs

AWS Credentials File: Configuration, Profiles, and Secure Usage

Learn how the AWS shared credentials file works, configure CLI and SDK profiles, understand credential resolution, use temporary credentials, and troubleshoot AWS authentication securely.

What AWS credentials do

AWS credentials are authentication data used to sign requests to AWS APIs. They identify the AWS principal making a request, such as an IAM user, an assumed role, or an IAM Identity Center session.

Authentication answers who is calling. Authorization answers what that caller may do. AWS credentials authenticate the caller, while IAM policies determine whether the caller can perform an action on a resource.

Common credential values

Long-term access keys usually contain an access key ID and secret access key. Temporary credentials contain all three values: access key ID, secret access key, and session token. A valid key pair can still fail if its temporary session has expired.

The AWS shared credentials file

The shared credentials file is a local INI-style file that stores AWS credential values under named profiles. The AWS CLI and many AWS SDKs can read it as one source in their credential provider chain.

The conventional locations are:

The home marker is user-specific; it is not a literal server path. For example, the file for one Linux user may be different from the file for another user on the same computer. A process running under a service account, container user, or administrator account may therefore read a different file.

You can inspect the credentials file conceptually at the AWS credentials file path. Never assume that a file displayed by a browser or diagnostic tool contains safe-to-share data.

Profiles and INI file format

An INI file is organized into sections containing key-value pairs. In AWS terminology, each section is a profile: a named set of credentials and settings.

The default profile is selected when no other profile is specified. Named profiles let you keep separate access for accounts, environments, teams, or roles.

Default static profile

[default]
aws_access_key_id = AKIAEXAMPLE
aws_secret_access_key = EXAMPLE_SECRET_VALUE

The values above are placeholders only. Never publish a real secret access key in documentation, source control, tickets, screenshots, or logs.

Two named profiles

[development]
aws_access_key_id = AKIADEVELOPMENTEXAMPLE
aws_secret_access_key = DEVELOPMENT_SECRET_PLACEHOLDER

[production]
aws_access_key_id = AKIAPRODUCTIONEXAMPLE
aws_secret_access_key = PRODUCTION_SECRET_PLACEHOLDER

Profile names in the shared credentials file are written without a profile prefix. Use separate credentials for separate environments; do not copy development credentials into a production profile.

Temporary credential profile

[temporary-admin]
aws_access_key_id = ASIAEXAMPLE
aws_secret_access_key = TEMPORARY_SECRET_PLACEHOLDER
aws_session_token = TEMPORARY_SESSION_TOKEN_PLACEHOLDER

Temporary credentials require the session token in addition to the two key values. They also expire. Refresh them through the login, role-assumption, or identity-provider workflow that issued them rather than manually extending their lifetime.

Credentials file versus AWS config file

The shared credentials file normally holds secret credential material. The separate AWS config file commonly holds non-secret settings such as region, output format, and role-related configuration. Tools may merge values from both files while resolving one profile.

For a named profile, the same logical profile can be split between the files:

# ~/.aws/credentials
[development]
aws_access_key_id = AKIAEXAMPLE
aws_secret_access_key = SECRET_PLACEHOLDER

# ~/.aws/config
[profile development]
region = us-west-2
output = json

The credentials section is [development], while the non-default config section is [profile development]. A mismatch between these conventions is a common cause of ignored settings.

Keep secret values in the credentials file or another approved secure provider. The config file can be viewed at the AWS config file path for comparison of the two file conventions.

Creating and selecting profiles

The AWS CLI can create or update the default profile interactively:

aws configure

For a named profile, use:

aws configure --profile development

The prompts commonly collect an access key ID, secret access key, default region, and output format. A region such as us-west-2 determines the default regional endpoint for commands that support regional services. Output formats such as json, yaml, yaml-stream, text, and table affect display, not permissions.

Select a profile for one command with --profile:

aws sts get-caller-identity --profile development

Select a profile for a shell session or process with AWS_PROFILE:

AWS_PROFILE=development
aws sts get-caller-identity

On Windows PowerShell, the equivalent environment-variable assignment is:

$env:AWS_PROFILE = "development"
aws sts get-caller-identity

Organize profiles by account, environment, team, or role. Names such as development, production-readonly, or billing-audit communicate intent, but always verify the actual identity before changing resources.

The credential provider chain

The credential provider chain is the ordered set of sources an AWS CLI or SDK checks to obtain credentials. The exact order and supported providers vary by tool and version, but common sources include:

Precedence matters. Environment variables or explicitly supplied values can cause a tool to use credentials different from those in ~/.aws/credentials. Selecting a profile controls which profile-based settings are considered, but it does not necessarily defeat higher-precedence sources. Check the documentation for the specific CLI or SDK version.

Useful overrides include:

AWS_SHARED_CREDENTIALS_FILE=/secure/path/credentials
AWS_CONFIG_FILE=/secure/path/config

These variables change the files used by supported tools. They do not move or encrypt existing credentials.

Temporary credentials, roles, and sign-in access

An IAM role is an AWS identity intended to provide temporary credentials when it is assumed by a trusted principal or supplied to an AWS runtime. Role-based access is generally safer than distributing long-lived user keys.

A role profile commonly contains role settings in the config file and refers to a source profile that supplies the initial identity:

# ~/.aws/credentials
[base]
aws_access_key_id = AKIAEXAMPLE
aws_secret_access_key = BASE_SECRET_PLACEHOLDER

# ~/.aws/config
[profile audit-role]
role_arn = arn:aws:iam::123456789012:role/AuditRole
source_profile = base
region = us-east-1

This example is conceptual and uses placeholders. The CLI or SDK first obtains credentials from the source profile, then requests temporary credentials for the role. Role sessions expire and must be renewed.

AWS IAM Identity Center provides sign-in-based workforce access to AWS accounts and applications. It is preferable to distributing long-lived access keys when it is available. EC2 instance roles, ECS task roles, and web identity roles are similarly preferred for workloads.

Security practices

• Treat secret access keys as passwords. Never commit them to source control, paste them into tickets, or include them in logs.
• Use least privilege: grant only the permissions required for the task.
• Avoid root-user access keys. Use an appropriate IAM identity or role instead.
• Prefer short-lived credentials, IAM roles, and IAM Identity Center over long-lived user keys.
• Rotate access keys on a planned schedule and revoke them immediately if exposure is suspected.
• Restrict local file permissions. On a single-user Unix workstation, a typical protective command is chmod 600 ~/.aws/credentials. Confirm that this matches your organization's requirements.
• On multi-user systems, ensure other users and untrusted processes cannot read the home directory or credential files.
• Protect backups, disk images, editor swap files, shell history, terminal recordings, and editor plugins.
• Ensure CI systems mask secrets and prevent credentials from appearing in command output or build logs.
• Use a managed secret or identity provider rather than putting permanent keys into application source code.

If a key is exposed, do not merely delete the file or commit. Identify the key, revoke or deactivate it, investigate usage, replace it through the approved process, and inspect related systems for copies.

Validate the active identity and configuration

AWS STS, the AWS Security Token Service, can report the principal associated with the currently resolved credentials:

aws sts get-caller-identity

To test a named profile explicitly:

aws sts get-caller-identity --profile development

The response normally includes an account identifier, an ARN, and a user or role identity field. An ARN containing an assumed-role session indicates that the request is using temporary role credentials rather than directly identifying an IAM user.

Inspect resolved settings and their sources without displaying the secret access-key material:

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

Use these commands to confirm the selected profile, region, and credential source. The source may indicate environment variables, a shared file, a role, or another provider. Do not treat a profile name alone as proof of the active AWS account; confirm with STS.

Troubleshooting AWS credentials

Missing credentials and incorrect location

First determine which operating-system user runs the CLI or application. A credentials file under one user's home directory is not automatically available to another user. Then check whether AWS_SHARED_CREDENTIALS_FILE or AWS_CONFIG_FILE points somewhere unexpected.

Missing session token

If credentials came from STS, role assumption, IAM Identity Center, web identity, or another temporary source, the access key ID and secret access key are not sufficient by themselves. Ensure the matching session token is supplied and refresh all values together.

Stale credential caches

Role and sign-in tools may cache temporary sessions. If an identity check reports an expired token, renew the supported login or role-assumption session rather than copying old values into a new profile. Clear a cache only through the provider's documented workflow and avoid deleting unrelated configuration.

SDK usage without hard-coded secrets

SDKs commonly use their default credential provider mechanism, which can read environment variables, shared profiles, role providers, and runtime credentials. A local development program can explicitly select a profile without embedding secret values. For example, Python with Boto3 can use a named profile:

import boto3

session = boto3.Session(profile_name="development")
sts = session.client("sts")
print(sts.get_caller_identity())

In deployed applications, prefer the SDK's default provider mechanism so the application can use an ECS task role, EC2 instance role, web identity, or another runtime provider. Avoid placing access keys directly in source code or configuration committed to a repository.

Quick operating checklist

1. Identify the operating-system user and the effective credentials and config file paths.
2. Choose a profile deliberately; use --profile for important commands.
3. Run aws configure list to inspect the resolved source and region.
4. Run aws sts get-caller-identity before modifying AWS resources.
5. Confirm whether credentials are long-lived or temporary and check expiration.
6. Use least privilege and prefer roles or IAM Identity Center.
7. Protect files, backups, shell history, editor data, CI logs, and any copied credential material.
8. Revoke and rotate credentials immediately after suspected exposure.