Home

AWS Credentials File and Credential Management

Learn how AWS credentials, profiles, config files, provider chains, temporary credentials, IAM roles, and secure credential practices work with the AWS CLI and SDKs.

AWS credentials let the AWS CLI and SDKs make authenticated requests to AWS services. Good credential management helps you select the intended AWS account and permissions while reducing the risk of leaked or over-privileged secrets.

This lesson covers the shared credentials file at ~/.aws/credentials, the AWS config file, profiles, the credential provider chain, temporary credentials, IAM roles, IAM Identity Center, and practical diagnosis.

Authentication, authorization, and AWS identities

Authentication answers “Who is making this request?” Authorization answers “What is that identity allowed to do?” AWS credentials primarily support authentication, while IAM policies and related controls determine authorization.

An AWS account is an isolated security and billing boundary. An IAM identity is a principal that can make requests in an account. Common principals include an IAM user and an IAM role.

  • IAM user: A long-lived identity that can have programmatic access keys. Static IAM user keys should be avoided when a temporary alternative is available.
  • IAM role: An assumable identity that normally provides temporary credentials. Roles are commonly used by applications, EC2 instances, containers, CI systems, and users accessing another account.
  • AWS access key ID: The identifier portion of a programmatic credential.
  • AWS secret access key: The secret portion used to sign AWS API requests. Never publish it.
  • Session token: An additional value required with temporary credentials.
  • AWS STS: AWS Security Token Service, which issues temporary credentials and provides identity information.

A request made with valid credentials can still fail authorization. For example, aws sts get-caller-identity may succeed while an S3 operation returns AccessDenied because the principal lacks the required permission.

The AWS shared credentials file

The AWS shared credentials file is an INI-style text file containing credential values organized into profiles. Its usual locations are:

  • Unix-like systems: ~/.aws/credentials
  • Windows: %UserProfile%\.aws\credentials

A profile is a named set of AWS settings and, optionally, credentials. The default profile is selected when no other profile is specified. Any other profile is a named profile.

[default]
aws_access_key_id = EXAMPLEACCESSKEY
aws_secret_access_key = EXAMPLESECRETKEY

[development]
aws_access_key_id = DEVACCESSKEY
aws_secret_access_key = DEVSECRETKEY

The example uses placeholders rather than usable secrets. A credentials file may contain long-term access keys or all three values for temporary credentials:

[temporary]
aws_access_key_id = ASIAEXAMPLE
aws_secret_access_key = EXAMPLESECRETKEY
aws_session_token = EXAMPLESESSIONTOKEN

Temporary values must be used as a set. The access key ID, secret access key, and session token must come from the same session.

For a relevant path-specific reference, see the AWS credentials file path.

The AWS config file

The AWS config file normally stores non-secret profile settings. Its usual Unix-like location is ~/.aws/config; on Windows it is under %UserProfile%\.aws\config.

  • The credentials file commonly stores access keys and temporary session credentials.
  • The config file commonly stores the default Region, output format, role-assumption settings, IAM Identity Center settings, and other profile behavior.

Profile names use a different syntax in the two files. The default profile is written as [default] in both files. A named profile is written as [name] in the credentials file, but as [profile name] in the config file.

# ~/.aws/credentials
[default]
aws_access_key_id = EXAMPLEACCESSKEY
aws_secret_access_key = EXAMPLESECRETKEY

[development]
aws_access_key_id = DEVACCESSKEY
aws_secret_access_key = DEVSECRETKEY
# ~/.aws/config
[default]
region = us-east-1
output = json

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

The CLI and SDK can combine the selected profile's settings from both files. For example, credentials can come from ~/.aws/credentials while the Region and output format come from ~/.aws/config. Do not assume that moving a secret into the config file makes it safe; both files should be protected.

Shared credentials file versus config file

Aspect — Credentials file — Config file

Typical path — ~/.aws/credentials — ~/.aws/config

Named profile syntax — [development] — [profile development]

Typical contents — Access key ID, secret access key, session token — Region, output, role settings, SSO settings, and profile behavior

Secret handling — Contains sensitive values when static or temporary credentials are stored — Usually non-secret settings, although some authentication-related configuration still requires protection

Relationship — Supplies credentials for a selected profile — Supplies additional settings for that same profile

The credential provider chain

The credential provider chain is an ordered list of credential sources that an AWS CLI or SDK checks. The first usable source, according to that tool's rules, is generally selected. Exact providers and precedence vary by AWS SDK, SDK version, CLI version, language, and runtime.

Common sources include:

  1. Credentials explicitly supplied in application or SDK configuration. Hard-coding secrets is unsafe.
  2. Environment variables such as AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN.
  3. The shared credentials file and config file, including a selected profile.
  4. IAM Identity Center credentials obtained after human sign-in.
  5. Web identity credentials, often used by Kubernetes or CI workloads through OIDC.
  6. Process-based providers that invoke a configured helper program.
  7. ECS task credentials supplied to a container task.
  8. EC2 instance metadata credentials supplied by an attached instance role.
  9. Other runtime role providers supplied by the deployment environment.

An unexpected source may win because environment variables override a profile, AWS_PROFILE selects another profile, an IDE or container inherited credentials, or a runtime role is available. Always verify the active identity instead of inferring it from a file alone.

Credential sources and typical use cases

Credential source — Typical environment — Credential lifetime — Recommended use — Security considerations

IAM user access keys — Legacy local tools or applications — Long-lived until rotated or disabled — Only when no suitable temporary method exists — High exposure risk; apply least privilege and rotate promptly

IAM role — EC2, ECS, CI, serverless, and other workloads — Temporary and automatically refreshed when supported — Preferred for AWS workloads — Protect the trust policy and limit permissions

IAM Identity Center — Human developers and administrators — Temporary sessions — Preferred for interactive users — Protect the sign-in session and use MFA

AssumeRole — Cross-account or elevated access — Temporary STS session — Preferred for controlled access transitions — Restrict the trust relationship and session permissions

Web identity or OIDC — Kubernetes and CI/CD — Temporary — Preferred for federated workloads — Restrict token subjects and role trust conditions

ECS or EC2 runtime role — AWS compute services — Temporary and commonly refreshed — Preferred over storing keys on hosts — Protect the workload and metadata access path

Recommended credential choices

Prefer short-lived credentials and role-based access. Human users should generally sign in through AWS IAM Identity Center and assume roles for required access. Workloads should use an attached IAM role, web identity, or another federated mechanism rather than static keys in files or source code.

AssumeRole is an AWS STS operation that exchanges an authorized source identity for temporary credentials representing a target role. It is useful for cross-account access and for separating ordinary development access from elevated operations.

Use long-term IAM user access keys only for narrowly justified cases. Apply least privilege, protect the keys, monitor their use, and rotate or remove them when they are no longer needed.

Creating and configuring profiles

Default profile

Run the interactive command and answer its prompts:

aws configure

This commonly writes access key values to the shared credentials file and the default Region and output format to the config file.

Named profile

aws configure --profile development

Use named profiles to separate environments and reduce accidental production changes:

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

Profile selection methods

Method — Example — Scope — When to use

Command-line option — aws s3 ls --profile development — One CLI command — Safest for an explicit, easily reviewed choice

Environment profile — export AWS_PROFILE=development — Current shell and processes that inherit it — A session containing several commands

SDK configuration — Select a profile through the SDK's supported configuration — One application or client — Applications that intentionally choose a profile

Default profile — Omit profile selection — Current user and environment — Simple local use when only one profile is appropriate

AWS_DEFAULT_REGION sets a default Region for the current process environment. The selected profile can also define region in the config file. Make the environment and profile choice explicit in scripts that could affect production.

Role-assumption profile

A role profile can use a source profile to obtain temporary credentials for a target role:

# ~/.aws/credentials
[development]
aws_access_key_id = DEVACCESSKEY
aws_secret_access_key = DEVACCESSSECRET

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

When production-readonly is selected, the CLI or SDK uses the source profile, calls STS to assume the role, and uses the resulting temporary credentials. The source principal must be allowed to assume the target role, and the target role's trust policy must allow that principal.

Temporary credentials and refresh

Temporary credentials have an expiration time. The AWS_SESSION_TOKEN value proves that the access key and secret key belong to the temporary session. Without the token, requests made with temporary credentials commonly fail.

export AWS_ACCESS_KEY_ID='TEMPORARY_ACCESS_KEY'
export AWS_SECRET_ACCESS_KEY='TEMPORARY_SECRET_KEY'
export AWS_SESSION_TOKEN='TEMPORARY_SESSION_TOKEN'
export AWS_DEFAULT_REGION='us-east-1'

Keep all three credential values together and remove them from the environment when the session ends. Do not put real values in scripts committed to a repository.

  • Role profiles refresh credentials by obtaining a new role session when supported by the CLI or SDK.
  • IAM Identity Center profiles refresh after the user signs in again or while a valid cached sign-in remains available.
  • ECS, EC2, and other metadata-based providers generally obtain replacement credentials from the runtime.
  • Manually exported temporary variables do not automatically refresh; replace them before expiration.

Security and operational hygiene

  • Treat credential files, access keys, session tokens, environment variables, and diagnostic output as sensitive material.
  • On Unix-like systems, restrict the credentials file to the owning user: chmod 600 ~/.aws/credentials.
  • Keep credential files out of source repositories, shared directories, screenshots, tickets, shell history, and logs.
  • Do not print environment variables or entire configuration files in CI logs or bug reports.
  • Remember that environment variables can leak through process inspection, CI diagnostics, crash reports, and inherited child processes.
  • Grant only the permissions required for the task. This is the principle of least privilege.
  • Use MFA and role assumption where appropriate, especially for administrative or cross-account access.
  • If a key is exposed, immediately investigate its use and then deactivate or delete it. Replace it only through a controlled process.

Validate the active identity

AWS STS can report the account and principal associated with the credentials currently selected by the CLI:

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

Run the explicit-profile command before making changes in a sensitive account. The response identifies the active AWS account and caller ARN, which helps detect profile and environment-variable conflicts.

CLI debug output can help diagnose provider selection, signing, endpoints, and request details, but use it cautiously. Debug output may expose sensitive information in terminals, logs, or support bundles. Redact secrets before sharing any diagnostics.

Common authentication and authorization errors

Message or symptom — Likely cause — How to verify — Resolution

Unable to locate credentials — No usable provider, missing profile, wrong user, or unavailable runtime credentials — Confirm the selected profile, inspect profile names without values, and run STS identity lookup — Configure a valid profile, sign in through IAM Identity Center, or attach the appropriate workload role

The security token included in the request is invalid — Mismatched keys, missing session token, revoked key, or conflicting environment variable — Check all three credential variables and verify the active identity — Use one complete valid credential set and remove stale overrides

ExpiredToken — Temporary STS, role, or SSO credentials expired — Check the profile's session state and expiration — Sign in again, re-assume the role, or restore the workload provider

AccessDenied — Authentication succeeded but an IAM, resource, boundary, session, or organization policy denies the action — Identify the caller with STS and review action, resource, and applicable policies — Grant only the narrowly required permission or use the intended role

Wrong account or role — Unintended AWS_PROFILE, environment credentials, IDE settings, container inheritance, or runtime role — Run STS identity lookup and inspect profile-related environment variables — Unset overrides, select the intended profile, or isolate the runtime

SignatureDoesNotMatch — Incorrect secret, incomplete temporary set, inaccurate clock, wrong Region, or wrong endpoint — Check time synchronization, credential completeness, Region, and endpoint; use diagnostics carefully — Correct the credentials, clock, Region, or endpoint

A practical troubleshooting sequence

  1. Confirm which operating-system user and runtime are executing the command.
  2. Check whether AWS_PROFILE, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, or AWS_SESSION_TOKEN is set. Do not paste their values into a report.
  3. Run aws sts get-caller-identity and compare the account and ARN with the intended principal.
  4. Repeat the test with an explicit profile, such as aws sts get-caller-identity --profile development.
  5. Determine whether the selected source uses temporary credentials and whether its sign-in or refresh session has expired.
  6. For AccessDenied, inspect authorization policies after confirming authentication.
  7. For signing errors, verify the system clock, credential set, Region, and endpoint.

Replacing exposed static credentials

If static credentials are exposed, stop treating them as trustworthy. Identify the IAM user and key, review activity, deactivate or delete the exposed key, and investigate any resulting access. Then migrate the workflow to IAM Identity Center for human access, an IAM role for AWS workloads, or OIDC and web identity for supported CI systems.

This migration reduces the amount of secret material stored on disk and changes credentials from long-lived values to short-lived sessions that can be refreshed and constrained by role policies.

Exam-relevant notes

  • Authentication and authorization are different: valid credentials do not guarantee permission to perform an action.
  • The credentials file and config file are separate, but a selected profile commonly combines settings from both.
  • Named profile syntax is [name] in the credentials file and [profile name] in the config file.
  • Temporary credentials require the access key ID, secret access key, and session token together.
  • Environment variables can cause a profile to appear ignored because they may take precedence in the provider chain.
  • Roles, IAM Identity Center, web identity, and runtime credentials are generally preferable to long-lived static access keys.
  • aws sts get-caller-identity is a safe first check for determining which principal is active, though its output still identifies account information.