@Fs

AWS CLI Credentials: Configuration, Profiles, and Secure Access

Learn how AWS CLI and SDK credentials work, where profiles are stored, how precedence is resolved, how to verify identities, and how to use secure temporary access.

AWS credentials let the AWS CLI and AWS SDKs make authenticated requests to AWS services. This guide explains how credentials are stored, how profiles are selected, how temporary role credentials work, and how to verify and secure the identity used by a command or workload.

What AWS credentials do

Credentials identify a principal, such as an IAM user, an assumed IAM role, or an IAM Identity Center session. AWS uses that identity to evaluate whether a request is authorized to perform an action on a resource.

Authentication answers “Who is making this request?” Authorization answers “What is that identity allowed to do?” Valid credentials authenticate a request, but they do not automatically grant permission. IAM policies, resource policies, permissions boundaries, session policies, and organization controls determine authorization.

• Access key ID: The public identifier portion of an AWS access-key pair.
• Secret access key: The confidential portion used to sign requests. Treat it as a password.
• Session token: An additional value required with temporary credentials.
• Region: The default AWS geographic Region used by commands that do not specify one.
• Output format: The default CLI response format, such as json, text, table, or yaml.

The AWS CLI is Amazon Web Services' command-line interface. An AWS SDK is a language-specific library that makes authenticated AWS API calls from application code.

Shared AWS files

On a typical Linux or macOS workstation, AWS tools use two shared INI-style files:

The AWS CLI normally creates the ~/.aws directory the first time you configure it. The credentials file commonly stores access-key pairs. The config file commonly stores Regions, output settings, role configuration, and profile-specific options.

Do not assume every setting must exist in only one file. AWS tools can resolve settings from both files, and some profile features require the config file. Keep static credentials in the credentials file when using shared files, and place general profile configuration in the config file.

Profile section naming

A profile is a named set of AWS settings and credential-resolution instructions. The default profile is used when no profile is explicitly selected.

The default profile is written as [default] in both files. A named profile uses different section syntax:

# ~/.aws/credentials
[development]
aws_access_key_id = YOUR_ACCESS_KEY_ID
aws_secret_access_key = YOUR_SECRET_ACCESS_KEY

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

The profile prefix is used for non-default profiles in the config file. It is omitted in the credentials file. This difference is a common source of “profile not found” errors.

Creating credentials with the AWS CLI

For an initial local setup, run:

aws configure

The CLI prompts for an access key ID, secret access key, default Region, and default output format. The values are saved under the default profile unless another credential mechanism is already being used.

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

Create or update a named profile with:

aws configure --profile development

Use named profiles to separate personal, development, testing, production, or organization accounts. A profile is a selection mechanism, not a permission boundary: the permissions still come from the identity behind that profile.

Direct file editing

Direct editing can be useful for role profiles, reviewing configuration, or automation that generates a controlled file. A static profile has this general structure:

[development]
aws_access_key_id = YOUR_ACCESS_KEY_ID
aws_secret_access_key = YOUR_SECRET_ACCESS_KEY

Never copy real secret values into documentation, tickets, screenshots, shell transcripts, or source control. Be especially careful with shell commands that place secrets directly in command arguments, because command history and process inspection may expose them.

Using profiles

Run a command with an explicit named profile:

aws s3 ls --profile development

You can select a profile for the current shell session with the AWS_PROFILE environment variable:

export AWS_PROFILE=development
aws s3 ls

An explicit --profile option is clear and useful for one command. AWS_PROFILE affects commands in the shell until it is changed or unset:

unset AWS_PROFILE

Before a production operation, prefer an explicit profile and verify its identity. This reduces the chance that a shell's inherited settings silently select another account.

Credential provider precedence

A credential provider chain is the ordered set of sources checked by an AWS tool. The exact order can vary by AWS CLI version, SDK, language, and configuration, but common sources include the following:

An unexpected exported variable, explicit profile option, or role setting can cause a command to use the wrong identity. Diagnose identity before diagnosing permissions.

aws configure list
aws sts get-caller-identity

Inspect relevant variables carefully:

echo "$AWS_PROFILE"
echo "$AWS_ACCESS_KEY_ID"
echo "$AWS_SESSION_TOKEN"

Avoid printing secret access keys. In shared environments, inspect environment configuration through approved tools rather than exposing all process variables.

Temporary credentials and IAM roles

Temporary credentials contain an access key ID, secret access key, and session token. They also have an expiration time. After expiration, the CLI or SDK must obtain a fresh session through the original sign-in, role-assumption, or workload-identity mechanism.

An IAM role is an AWS identity with permissions that can be assumed. Role assumption is often safer than maintaining long-lived user access keys because the resulting credentials are short-lived and can be limited to a particular task or account.

Role profiles

A role profile can use a source profile containing base credentials to assume a role in another account:

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

Here, development supplies the initial authentication, while audit describes the target role. The active permissions come from AuditRole, subject to trust policies and other applicable controls.

IAM Identity Center, formerly known as AWS SSO, provides workforce sign-in and SSO-based profiles as an alternative to static access keys. The CLI obtains or refreshes cached short-lived credentials after the user signs in. When those credentials expire, sign in again or use the supported refresh flow.

Verifying the active identity

AWS STS, the Security Token Service, can report the principal making the request:

aws sts get-caller-identity

Verify a named profile directly:

aws sts get-caller-identity --profile production

A sanitized response resembles:

{
    "UserId": "AIDAEXAMPLE",
    "Account": "123456789012",
    "Arn": "arn:aws:iam::123456789012:role/ExampleRole"
}

The account ID confirms the AWS account. The ARN identifies the user, role, or federated principal. Run this check before deleting resources, changing networking, modifying IAM, or executing production scripts.

Security practices

• Apply least privilege: grant only the actions and resources required for the task.
• Do not use the AWS account root user for routine CLI access. Protect it for exceptional account-level tasks.
• Prefer IAM roles, IAM Identity Center, workload identity, and other short-lived mechanisms over long-lived access keys.
• Never commit ~/.aws/credentials, access keys, or secret-bearing environment files to source control.
• On Linux or macOS, restrict the local credentials file:

chmod 600 ~/.aws/credentials

• Do not share credential files between users. Each user or workload should have its own identity.
• Do not place secrets in screenshots, shell history, documentation, tickets, or logs.
• Rotate access keys when they must exist, remove unused keys, and immediately deactivate exposed keys before investigating further.
• Use separate identities and explicit profiles for development and production.

Local workstations versus AWS workloads

On a local computer, a developer may use an IAM Identity Center profile, an assumed role, or—where unavoidable—a protected shared credentials file. On AWS infrastructure, applications should normally receive credentials from the platform rather than from a manually copied local file.

• EC2: Attach an instance profile whose IAM role supplies temporary credentials.
• ECS: Assign an ECS task role so the container receives task-scoped credentials.
• EKS: Use pod identity or web identity federation so a workload receives credentials for its Kubernetes service account.
• CI/CD: Use the provider's federated identity or workload identity mechanism when available, rather than storing permanent AWS keys in pipeline variables.

Manual copying of a local credentials file into a production server creates a long-lived secret outside the workload's intended identity controls.

Troubleshooting credential problems

Unable to locate credentials

• Run aws configure list to see the selected sources.
• Confirm the expected home directory and the paths ~/.aws/credentials and ~/.aws/config.
• Check that the requested profile section exists and is spelled correctly.
• For a workload, confirm that its instance role, task role, pod identity, web identity, or CI identity is actually available.
• Select the intended profile explicitly or attach the appropriate role-based identity.

The CLI uses the wrong AWS account

• Run aws sts get-caller-identity.
• Check AWS_PROFILE, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN.
• Look for an explicit --profile option in scripts or aliases.
• Review role_arn and source_profile in role profiles.
• Remove unintended environment variables, select the intended profile, and verify the caller again.

InvalidClientTokenId or SignatureDoesNotMatch

• Confirm that the access key ID and secret access key belong together and are active.
• For temporary credentials, confirm that the session token is present and not expired.
• Check that the system clock is synchronized; substantially incorrect time can invalidate signed requests.
• Test with aws sts get-caller-identity --profile PROFILE_NAME.

AccessDenied after authentication succeeds

Successful authentication does not prove authorization. First confirm the account ID and caller ARN. Then identify the API action and target resource, and review identity policies, resource policies, permissions boundaries, session policies, and organization service control policies. Grant the minimum missing permission or use the intended authorized role; do not respond by broadly granting administrator access.

Profile not found or malformed profile behavior

• Use [development] in the credentials file and [profile development] in the config file for a named profile.
• Check INI formatting, spelling, and duplicate sections.
• Confirm that every source_profile refers to an existing profile.
• Test with an explicit option such as aws sts get-caller-identity --profile development.

Exam-relevant notes

• Authentication establishes identity; authorization evaluates permissions.
• Temporary credentials require a session token and expire.
• The default profile is used when no profile is selected.
• Non-default profiles use the profile prefix in ~/.aws/config, but not in ~/.aws/credentials.
• Always verify the caller identity before destructive or production operations.
• For production workloads, prefer attached or federated identities over manually copied local credential files.