AWS Credentials File: Profiles, Configuration, and Secure Usage

Learn how to use the AWS shared credentials file, configure profiles, select credentials, verify identities, use temporary roles, and troubleshoot AWS authentication securely.

AWS credentials are authentication material used to establish the identity of a person, application, or workload making an AWS request. The identity might be an IAM user, an assumed IAM role, or a federated session.

Authentication answers “Who is making this request?” Authorization answers “What is that identity allowed to do?” Credentials establish identity; IAM policies, resource policies, permission boundaries, and organizational controls determine permitted actions.

Common AWS credential types

Long-term access keys: an access key ID paired with a secret access key. These are persistent until rotated or deactivated.
Temporary role credentials: an access key ID, secret access key, and session token with an expiration time.
Web identity credentials: temporary credentials obtained by exchanging a web identity token for an IAM role, commonly in containerized workloads or CI systems.
External credential processes: credentials supplied by an approved command or authentication tool rather than stored directly in the profile file.

For local development, federated sign-in, IAM Identity Center, or an assumed role is generally preferable to maintaining a personal long-term access key. For deployed workloads, use a workload role or a CI/CD identity mechanism instead of copying a developer's credentials file.

What is the AWS shared credentials file?

The AWS shared credentials file is a local, INI-style text file that stores credential profiles. The AWS CLI and many AWS SDK credential providers can read it automatically.

The conventional Unix-like location is ~/.aws/credentials. The ~ symbol means the current user's home directory. For example, if the current user's home directory is /home/alex, the expanded path is /home/alex/.aws/credentials.

Operating system	Credentials file location	Config file location	Notes
Unix-like systems	`~/.aws/credentials`	`~/.aws/config`	The path is relative to the current user's home directory.
Windows	User-profile AWS directory, commonly `%USERPROFILE%\.aws\credentials`	User-profile AWS directory, commonly `%USERPROFILE%\.aws\config`	Use the current Windows user's profile directory.

The file might not exist on a new machine. It is commonly created by aws configure, a sign-in tool, an SDK setup process, or a person manually provisioning a profile.

For this lesson, the public reference path is AWS credentials. A real user's file is normally under that user's own home directory, not necessarily this path.

Credential file format

The shared credentials file contains profile sections. A section heading is followed by key-value pairs. Do not place real secrets in examples, documentation, or source control.

[default]
aws_access_key_id = EXAMPLEACCESSKEYID
aws_secret_access_key = EXAMPLESECRETKEY

The default profile is selected when no other profile is explicitly requested and no higher-priority credential source supplies credentials.

A named profile separates credentials for another account, environment, role, or responsibility:

[development]
aws_access_key_id = EXAMPLETEMPACCESSKEY
aws_secret_access_key = EXAMPLETEMPSECRET
aws_session_token = EXAMPLESESSIONTOKEN

Key	Required for	Sensitivity	Purpose
`aws_access_key_id`	Long-term or temporary access-key credentials	Identifier; still sensitive in context	Identifies the access-key credential.
`aws_secret_access_key`	Long-term or temporary access-key credentials	Secret	Proves possession of the credential paired with the access key ID.
`aws_session_token`	Temporary credentials	Secret	Completes a temporary credential set. It is required when the issuing system provides one.

Credentials file versus AWS config file

AWS tooling commonly combines two files:

~/.aws/credentials normally contains secret-bearing access material such as access keys and session tokens.
~/.aws/config normally contains non-secret settings such as region, output format, retry behavior, and role-assumption settings.

Both files can contain profile-related information, but their section-heading syntax differs.

File	Default profile section form	Named profile section form	Example use
Credentials	`[default]`	`[development]`	Access keys or session credentials.
Config	`[default]`	`[profile development]`	Region, output format, and role settings.

For example, a role-based profile is normally placed in the config file:

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

role_arn identifies the role to assume. source_profile identifies the profile containing credentials that can perform the role assumption. The resulting role credentials are temporary. An optional role session name can help identify the session in audit records.

Profiles and profile selection

A profile is a labeled set of AWS authentication and configuration settings. Named profiles are useful when one machine accesses multiple accounts, environments, roles, or responsibilities.

Create a default profile interactively

aws configure

The command prompts for an access key ID, secret access key, default region, and output format. Secret values should be entered only into a trusted terminal and should not be pasted into tickets, logs, or shell scripts.

Create a named profile interactively

aws configure --profile development

The same command can create or update a separate profile without changing the default profile.

Select a profile for one command

aws sts get-caller-identity --profile development

Select a profile for a shell session

export AWS_PROFILE=development

On Windows PowerShell, the equivalent is commonly $env:AWS_PROFILE = "development". The profile remains selected for commands launched from that shell until the variable is changed or the shell closes.

When no profile is selected, tooling commonly starts with the default profile after checking higher-priority providers. SDKs often use the same shared profile mechanism, although exact provider-chain details vary by language and SDK version.

Credential provider precedence

A credential provider chain is the ordered set of sources an AWS CLI or SDK checks for credentials. The exact order can vary, but practical sources include explicitly supplied command options, environment variables, selected profiles, shared credentials and config files, external processes, container credentials, instance or workload roles, and other runtime providers.

Credential source	Typical use case	Can override local file expectations	Security guidance
Environment variables	Short-lived shell sessions, CI jobs, or secret injection	Yes; they can cause a command to ignore the expected profile.	Do not expose them in process listings, logs, debugging output, or build artifacts.
Explicit profile option	One CLI command	Yes, relative to the default profile selection.	Use it to make an important command unambiguous.
Shared credentials file	Local development profiles	Usually, if no higher-priority source is present.	Protect the file and never commit it.
AWS config file	Regions, output settings, and role profiles	It can change which source profile or role is used.	Review role and source-profile relationships.
Container credentials	Container task or pod workloads	Yes, in a hosted runtime.	Use the narrowest workload role.
Instance or workload role	Compute services running inside AWS	Yes, when attached to the runtime.	Avoid distributing user keys to instances.
External credential process or federated provider	SSO, identity tools, and temporary sessions	Yes, depending on provider order.	Use approved identity tooling and short-lived credentials.

Environment-provided credentials are a frequent source of surprises. A shell startup file, container definition, CI variable, or IDE may inject credentials that override the profile you expected to use. When troubleshooting, verify both the active identity and the active credential source.

Verify AWS CLI setup safely

Use AWS Security Token Service (STS) to inspect the principal currently making requests:

aws sts get-caller-identity

The response includes the AWS account and an ARN identifying the caller, such as an IAM user or assumed role. Test a named profile explicitly:

aws sts get-caller-identity --profile development

To inspect effective CLI configuration without printing secret values:

aws configure list

This command helps show whether values came from a profile, environment variable, or another provider. Treat all diagnostic output carefully: do not paste secret values or sensitive environment data into public logs.

Temporary credentials and IAM roles

Temporary credentials expire after a limited period and normally include an access key ID, secret access key, and session token. Their shorter lifetime reduces the impact of accidental exposure and supports centralized role and session control.

Role assumption uses source credentials to request a session for an IAM role. The caller must be authorized to assume the role, and the role's trust policy must allow that caller. The resulting session is limited by the role's policies and its expiration.

A role profile can keep role settings separate from secret material:

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

Where available, prefer IAM Identity Center or another federated sign-in approach over personal long-term keys. These approaches can centralize access control, use organizational identity, and issue temporary sessions.

Characteristic	Long-term access keys	Temporary credentials
Lifetime	Remain valid until rotated or deactivated.	Expire automatically.
File values	Access key ID and secret access key.	Access key ID, secret access key, and session token.
Risk if exposed	Potentially persistent access until response action is taken.	Usually bounded by expiration, but must still be revoked or investigated when exposed.
Typical source	Local profile or secret injection.	Assumed role, federated login, web identity, container role, or instance role.
Preferred use	Use only when an approved alternative is unavailable.	Preferred for people and workloads where supported.

Security practices

Treat the credentials file as a secret-bearing file, even if it also contains identifiers or non-secret-looking text.
Never commit access key IDs, secret keys, session tokens, or the entire AWS directory to source control.
Use least privilege: grant only the actions and resources required for the task.
Use separate identities for people, applications, environments, and workloads.
Prefer IAM roles, federated access, IAM Identity Center, and short-lived credentials.
Restrict local file permissions and protect backups, disk images, snapshots, and home-directory synchronization.
Avoid placing credentials in scripts, command history, container images, logs, issue reports, or shared configuration.
Use a secret-management system or CI/CD credential mechanism for automation instead of distributing personal credential files.
If a long-term access key is compromised, deactivate or rotate it promptly and audit its use.

Protect a Unix-like credentials file

chmod 600 ~/.aws/credentials

This grants read and write access to the file's owner while restricting other users. Also check ownership and permissions on the containing ~/.aws directory. On other platforms, apply equivalent user-only protections through the operating system's file permissions or user-profile security controls.

Automation and noninteractive environments

A deployed application should not depend on a developer's local credentials file. Local files disappear when the application moves to another host, create backup and distribution risks, and often grant more access than the workload needs.

AWS compute: attach an appropriate instance profile, task role, pod identity, or other workload role.
CI/CD: use protected secret injection when necessary, or prefer OpenID Connect role assumption so the pipeline receives short-lived credentials without storing a permanent key.
Local controlled testing: mounting a profile file can be acceptable in a tightly controlled, short-lived environment, but the mount remains a secret exposure and should be read-only, narrowly scoped, and excluded from images and artifacts.

Troubleshooting AWS credential errors

Symptom or error	Likely cause	How to verify	Recommended fix
Cannot locate credentials	No usable provider is available, the file is missing, or the command runs as another operating-system user.	Run `aws configure list`; check the home directory, `AWS_PROFILE`, and runtime role availability.	Configure the required profile, provide an approved runtime source, or attach a workload role.
Profile not found	Spelling, case, section syntax, or home directory is wrong.	Inspect credentials and config section names and confirm the current user's AWS directory.	Create or correct the profile and select it consistently.
Wrong AWS account or identity	An environment variable, explicit option, startup file, IDE, or CI setting overrides the expected profile.	Run STS identity inspection and check `AWS_PROFILE` plus credential-related environment variables.	Remove the unintended source and explicitly choose the intended profile or role.
Session-token or expiration error	Temporary credentials expired or the session token is missing.	Check for `aws_session_token` and confirm expiration with the issuing sign-in or role system.	Refresh or re-assume the role through the approved authentication process.
Invalid or inactive access key	The key is mistyped, deleted, deactivated, rotated, or belongs to an unexpected account.	Verify the active identity and review the key status in the approved AWS identity-management process.	Correct the profile or deactivate and replace the compromised or invalid key.
AccessDenied	Authentication succeeded, but IAM or resource authorization denies the requested action.	Verify caller identity, target account, action, resource, identity policies, role policies, resource policies, boundaries, and organizational controls.	Adjust authorization according to least privilege; do not distribute broader credentials as a shortcut.
Permission denied reading the file	Incorrect ownership or permissions on the AWS directory or credentials file.	Inspect filesystem ownership and permissions and confirm the file is valid INI-style text.	Restore user access, correct the format, and retain restrictive permissions.
A secret was committed	The credential is exposed even if the repository later becomes private or the line is deleted.	Identify the affected key or token and audit its use.	Deactivate or rotate immediately, remove it from code and history according to organizational procedure, and replace it with an approved role or secret mechanism.

A practical diagnostic sequence

Confirm which operating-system user and home directory are running the command.
Check whether AWS_PROFILE or an explicit --profile option selects the intended profile.
Inspect effective configuration with aws configure list without disclosing secrets.
Run aws sts get-caller-identity and compare the account and ARN with the intended principal.
Check for environment variables or runtime providers that take precedence over local files.
Determine whether credentials are temporary and still valid, including whether a session token is present.
If identity is correct but the request is denied, troubleshoot IAM authorization rather than rewriting credential syntax.

Exam-relevant notes

Credentials authenticate; IAM policies authorize.
The conventional shared credentials path is ~/.aws/credentials, while general profile settings commonly use ~/.aws/config.
The credentials file uses [profile-name], but a named profile in the config file normally uses [profile profile-name].
aws_session_token is required for temporary credential sets that include a session token.
--profile name selects one CLI command; AWS_PROFILE=name selects a profile for a shell environment.
Environment credentials can override the local profile you expected to use.
STS get-caller-identity is a practical way to confirm the active account and principal.
Access denied usually indicates an authorization problem, not necessarily a malformed credential file.
Roles and short-lived federated credentials are generally safer than distributing long-term personal access keys.