@Fs

AWS Credentials File and Profile Configuration

Learn how to create, locate, secure, and use AWS shared credentials files, named profiles, temporary credentials, role profiles, and IAM Identity Center.

What AWS credentials do

AWS credentials authenticate the principal making a request to an AWS service. A principal can be an IAM user, an assumed IAM role, an IAM Identity Center session, or a workload identity such as an EC2 instance role.

Authentication answers who is making the request. Authorization answers what that identity may do. IAM policies, resource policies, permissions boundaries, session policies, and organization controls determine authorization after AWS identifies the caller.

• Access key ID: The public identifier portion of an access-key pair.
• Secret access key: The private value used to sign AWS API requests. Treat it as a password.
• Session token: An additional value required with temporary credentials.

Long-term access keys normally consist of an access key ID and secret access key and remain valid until rotated, deactivated, or deleted. Temporary credentials contain all three values: an access key ID, secret access key, and session token. They also have an expiration time and must be refreshed.

The shared AWS credentials file

The shared credentials file is a local INI-style text file containing one or more credential profiles. Its usual location on Linux and macOS is ~/.aws/credentials. On Windows, the equivalent location is %USERPROFILE%\.aws\credentials.

The .aws directory and the file can be created by aws configure or created manually. The file linked here is the credentials-file location for this lesson: shared credentials file.

Default and named profiles

A profile is a named set of AWS credentials and settings. The default profile is selected when no other profile is requested. A named profile has a label such as development or production-readonly.

In the credentials file, the profile heading is the name in brackets. Do not add the word profile to the heading.

[default]
aws_access_key_id = EXAMPLEACCESSKEYID
aws_secret_access_key = EXAMPLESECRETACCESSKEY

[development]
aws_access_key_id = EXAMPLEDEVACCESSKEYID
aws_secret_access_key = EXAMPLEDEVSECRETACCESSKEY

Credentials file versus config file

AWS commonly uses two local files. The shared config file usually contains non-secret settings such as the default region, output format, role assumption, and IAM Identity Center configuration. The shared credentials file commonly contains access keys and session tokens.

A single profile can combine information from both files. For example, the development section in credentials can provide keys while [profile development] in config provides region = us-east-1. The files are joined by the profile name.

The profile-heading syntax is an important distinction:

# ~/.aws/credentials
[development]
aws_access_key_id = EXAMPLEACCESSKEYID
aws_secret_access_key = EXAMPLESECRETACCESSKEY

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

Do not put secret access keys in source code, and avoid placing them in the config file unless a specific authentication mechanism requires it. Configuration files can contain sensitive settings even when they do not contain raw keys.

Creating and selecting profiles

Create the default profile

Run the following command to create or update the default profile:

aws configure

The CLI prompts for an access key ID, secret access key, default region, and output format:

AWS Access Key ID [None]: EXAMPLEACCESSKEYID
AWS Secret Access Key [None]: EXAMPLESECRETACCESSKEY
Default region name [None]: us-east-1
Default output format [None]: json

Use only fake values such as these in examples or tests. The command writes credentials to the shared credentials file and general settings to the shared config file.

Create a named profile

Supply --profile when creating or updating a named profile:

aws configure --profile development

The resulting credentials section has this form:

[development]
aws_access_key_id = EXAMPLEDEVACCESSKEYID
aws_secret_access_key = EXAMPLEDEVSECRETACCESSKEY

Use that profile for one command:

aws s3 ls --profile development

Or select it for commands in the current shell:

export AWS_PROFILE=development

On Windows PowerShell, the equivalent is:

$env:AWS_PROFILE = "development"

SDKs usually support profile selection through their own configuration APIs or constructors. Check the SDK's documented profile option rather than assuming that a CLI flag is available in application code.

Inspect profiles and verify identity

List profile names known to the AWS CLI:

aws configure list-profiles

Inspect resolved settings and their sources without displaying secret values:

aws configure list --profile development

Confirm the account, user, or role associated with the credentials actually being used:

aws sts get-caller-identity --profile development

The response includes an account ID and an ARN. An ARN containing assumed-role indicates that the request is using an assumed role rather than directly using an IAM user.

Temporary credentials

Temporary credentials are issued by services such as AWS STS, by an assumed role, or through an IAM Identity Center session. All three values are required:

1. aws_access_key_id
2. aws_secret_access_key
3. aws_session_token

[temporary]
aws_access_key_id = EXAMPLETEMPACCESSKEYID
aws_secret_access_key = EXAMPLETEMPSECRETACCESSKEY
aws_session_token = EXAMPLE_SESSION_TOKEN

If the session token is omitted, AWS may reject the request even when the access key ID and secret access key are correct. Temporary credentials expire, so renew them through the system that issued them instead of editing an old token indefinitely.

Equivalent environment variables are AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN.

Role assumption with a source profile

A role profile tells the CLI to use one profile as the source identity and request temporary credentials for an IAM role. Put the source credentials in ~/.aws/credentials:

[development]
aws_access_key_id = EXAMPLEDEVACCESSKEYID
aws_secret_access_key = EXAMPLEDEVSECRETACCESSKEY

Put the role settings in ~/.aws/config:

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

Select the role profile:

aws sts get-caller-identity --profile audit-role

The CLI uses the source profile to request temporary credentials for AuditRole. Role-based access limits the exposure and lifetime of credentials and is generally preferable to handing out separate long-term keys for every account or task. The source principal must be allowed to call sts:AssumeRole, and the target role's trust policy must allow that principal.

IAM Identity Center and modern sign-in

IAM Identity Center, formerly commonly called AWS SSO, provides workforce sign-in and usually supplies temporary role credentials. Its profiles are typically configured in ~/.aws/config, not by manually copying access keys into ~/.aws/credentials.

[profile development]
sso_session = company
sso_account_id = 123456789012
sso_role_name = Developer
region = us-east-1

[sso-session company]
sso_start_url = https://example.invalid/start
sso_region = us-east-1

Start or refresh the login session with:

aws sso login --profile development

SSO login sessions differ from static access-key profiles: the user authenticates interactively, cached session information is used by the CLI, and the resulting role credentials expire. Other preferred alternatives include EC2 instance roles, ECS task roles, EKS workload identity, and other workload identity systems.

The credential provider chain

AWS tools search multiple credential sources. This ordered search is called the credential provider chain. A simplified view of common sources is:

Exact precedence differs between AWS CLI versions and SDKs. Consult the documentation for the specific tool when debugging. In practice, an environment variable can take precedence over a profile in the file, while an active container or instance role can be selected instead of the local file.

AWS_PROFILE selects a profile, but explicit access-key environment variables can still cause an unexpected identity depending on the tool's provider ordering. Check both the selected profile and all relevant AWS_* variables.

Comparing common authentication methods

Protecting local credentials

• Treat access key IDs, secret access keys, and session tokens as secrets. Although an access key ID is an identifier, disclose the complete credential set only through approved channels.
• Apply least privilege: grant only the actions and resources required for the task.
• Rotate long-term keys, deactivate unused keys, and revoke exposed or unnecessary keys.
• Never create access keys for the AWS root user unless an exceptional, documented task requires it; prefer IAM users, roles, or federation.
• Do not commit credentials to Git, embed them in source code, place them in container images, or include them in logs, tickets, screenshots, or shell history.
• Use secret-scanning tools in repositories and CI pipelines.

On Linux or macOS, create the directory and restrict the credentials file to its owner:

mkdir -p ~/.aws
touch ~/.aws/credentials
chmod 600 ~/.aws/credentials

The security goal on Windows is equivalent: the file should be readable and writable only by the intended user and approved system administrators. Use the file's security properties or an appropriate access-control command to remove access for unnecessary users and groups.

Verification and troubleshooting

Unexpected AWS account or identity

Start with configuration resolution and caller identity:

aws configure list
aws sts get-caller-identity
printf '%s\n' "$AWS_PROFILE"
printf '%s\n' "$AWS_ACCESS_KEY_ID"
printf '%s\n' "$AWS_SESSION_TOKEN"

On Windows PowerShell, inspect variables with Get-ChildItem Env:AWS_*. Do not print secret values into shared terminals or logs. If the result is unexpected, unset unintended variables, select the intended profile explicitly, and review whether a role, container source, or instance role is active.

Common errors

Debugging provider selection

CLI debug output can reveal which credential provider was selected and which endpoint or region was used:

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

Debug output can contain request details and environment or file information. Never share it without reviewing and redacting sensitive data. When comparing profiles, use aws configure list --profile NAME and aws sts get-caller-identity --profile NAME before enabling verbose diagnostics.

Practical workflow

1. Choose the safest authentication method available: IAM Identity Center for human users, a role or workload identity for applications, and static keys only when necessary.
2. Configure the intended profile with aws configure --profile NAME, or configure SSO and run aws sso login --profile NAME.
3. Confirm the profile appears in aws configure list-profiles.
4. Inspect sources with aws configure list --profile NAME.
5. Verify the account and ARN with aws sts get-caller-identity --profile NAME.
6. Use --profile NAME for important commands until the shell's default selection is unambiguous.
7. If the identity changes unexpectedly, inspect AWS_PROFILE, access-key environment variables, role settings, and runtime credential sources.

The shared credentials file is one part of AWS authentication, not the entire provider system. Understanding profiles, the config file, temporary sessions, and provider precedence prevents both accidental access to the wrong account and unsafe reliance on long-lived secrets.