Public

AWS Credentials: Configuring and Managing Authentication for the AWS CLI and SDKs

Learn how AWS credentials, profiles, shared files, temporary roles, IAM Identity Center, and provider chains authenticate the AWS CLI and SDKs securely.

AWS credentials are authentication material or session information used to make signed requests to AWS APIs. They identify an IAM principal—such as a user, role, federated identity, or service—and allow AWS to evaluate what that principal is authorized to do.

Authentication answers “Who is making this request?” Authorization answers “What may that identity do?” Valid credentials prove an identity, but they do not automatically grant permission to every AWS service or resource.

Credential components

A long-term access key normally contains an access key ID and a secret access key. The access key ID is an identifier; the secret access key is confidential and must be protected like a password.

Temporary credentials issued by AWS STS commonly contain those two values plus a session token. The session token must accompany the access key ID and secret access key. Temporary credentials also have an expiration time. Expiration is provider metadata and is not normally stored as a standard field in the shared credentials file.

Credential mechanisms and recommended choices

Prefer short-lived, role-based credentials whenever possible. Long-lived IAM user keys are difficult to protect, can be copied, and remain usable until rotated or deactivated.

Do not create or use root-account access keys for routine work. Protect the root account with strong authentication and reserve it for tasks that specifically require root access.

Local credential and configuration files

The shared credentials file normally stores access-key fields at ~/.aws/credentials. The config file normally stores regions, output preferences, and advanced profile settings at ~/.aws/config. The tilde represents the current user’s home directory. On Windows, the home directory is resolved from the user profile, commonly resulting in a path under %USERPROFILE%\.aws\.

The AWS CLI uses these conventions, and many SDKs support them, but file support and provider precedence can vary by SDK and version. Check the documentation for the exact tool in use.

You can select alternate locations with AWS_SHARED_CREDENTIALS_FILE and AWS_CONFIG_FILE:

export AWS_SHARED_CREDENTIALS_FILE="$HOME/.config/aws/credentials"
export AWS_CONFIG_FILE="$HOME/.config/aws/config"

Credentials file format

Both files use INI-style sections. The default profile is named default; other sections are named profiles.

[default]
aws_access_key_id = EXAMPLEACCESSKEY
aws_secret_access_key = EXAMPLESECRETKEY

[development]
aws_access_key_id = EXAMPLEDEVACCESSKEY
aws_secret_access_key = EXAMPLEDEVSECRETKEY

[temporary-session]
aws_access_key_id = EXAMPLETEMPACCESSKEY
aws_secret_access_key = EXAMPLETEMPSECRETKEY
aws_session_token = EXAMPLESESSIONTOKEN

The final profile illustrates temporary credentials. Its session token must match the access key and secret key issued for the same session. Do not add real secrets to examples, tickets, screenshots, logs, or shared locations. Avoid placing comments or unrelated data beside secrets where the file could be copied or exposed.

Configuration file and profile settings

A profile can combine credentials from the credentials file with settings from the config file. The config file uses [default] for the default profile and [profile NAME] for named profiles.

[default]
region = us-east-1
output = json

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

[profile audit]
role_arn = arn:aws:iam::123456789012:role/AuditReadOnly
source_profile = development
role_session_name = local-audit

region supplies a default AWS Region and output controls common CLI formats such as json, text, or table. A role profile uses role_arn to identify the target role and source_profile to identify credentials used to call AWS STS. credential_source can instead tell a tool to use credentials supplied by an environment such as EC2 instance metadata or a container. role_session_name gives the temporary session a recognizable name.

Web identity profiles exchange a web identity token for temporary role credentials. IAM Identity Center profiles describe an organization’s start URL, Region, account, role or permission-set selection, and cached sign-in session. These mechanisms avoid embedding long-lived keys in application code.

Credential provider chain

A credential provider chain is the ordered set of sources a CLI or SDK checks for usable credentials. Common inputs include explicit application settings, command options, environment credential variables, shared files, IAM Identity Center sessions, role assumption, container credentials, and EC2 instance metadata. Exact precedence differs between tools and SDK versions, so verify it for your environment.

Configure the AWS CLI

When long-term keys are genuinely necessary, configure a least-privilege, non-production identity interactively:

aws configure

The CLI prompts for an access key ID, secret access key, default Region, and output format. For a named profile, use:

aws configure --profile development

For organization-managed human access, prefer IAM Identity Center:

aws configure sso --profile workforce
aws sso login --profile workforce

The CLI stores or uses a cached short-lived session and can request a renewed sign-in when the session is no longer valid. Do not put credentials directly in source code merely to set a Region; configure the Region in a profile or through an environment variable.

Select profiles and Regions

Without an explicit selection, tools generally use the default profile. Select a profile for one CLI invocation with:

aws sts get-caller-identity --profile development

Select a profile for a shell session with:

export AWS_PROFILE=development
export AWS_DEFAULT_REGION=us-west-2

A command-specific Region can take precedence over profile defaults:

aws ec2 describe-instances --profile development --region us-west-2

Separate profiles help prevent accidental work in the wrong account. Useful names distinguish personal, development, test, production, audit, and cross-account access.

Assume a role across accounts

Role assumption connects four elements: a source identity, permission to call sts:AssumeRole, a target role trust policy that permits that source, and the target role’s permissions policy. AWS STS then issues a temporary session.

[profile audit]
role_arn = arn:aws:iam::123456789012:role/AuditReadOnly
source_profile = development
role_session_name = local-audit

The source profile supplies the initial credentials. The target role’s trust policy must trust that source principal, and the source identity must be allowed to call AssumeRole. The resulting permissions are those granted to the target role, subject to applicable boundaries, session policies, resource policies, and organization controls.

aws sts get-caller-identity --profile audit

Temporary credentials expire by design. Role-capable providers can refresh them when supported. For local sessions, renew the source login or rerun the approved authentication workflow. Long-running processes may need restarting if they retained stale credentials.

Use IAM Identity Center locally

1. Run aws configure sso --profile workforce and provide the organization’s requested sign-in details.
2. Run aws sso login --profile workforce and complete browser authentication.
3. Use the named profile for commands and SDK processes.

aws sts get-caller-identity --profile workforce

The selected account and permission set determine the resulting principal and permissions. A renewed sign-in may be required after the cached session expires.

Use credentials in applications without hardcoding

SDKs commonly provide a default credential provider chain. The following Python example uses Boto3’s standard session behavior; it does not assign key values in application code.

import boto3

session = boto3.Session()
sts = session.client("sts")
identity = sts.get_caller_identity()
print(identity["Account"], identity["Arn"])

During local development, choose the intended profile without changing the program:

export AWS_PROFILE=development
python verify_identity.py

After deployment, attach an IAM role to the workload—such as an EC2 instance profile or container task role—and let the SDK obtain temporary credentials from its environment. Use a secret-management mechanism for application secrets that are not identity credentials; do not embed access keys in source, client-side applications, or packaged binaries.

Validate the active identity

Always confirm the account and principal before destructive or production operations:

$ aws sts get-caller-identity --profile audit
{
    "UserId": "AROAEXAMPLE:local-audit",
    "Account": "123456789012",
    "Arn": "arn:aws:sts::123456789012:assumed-role/AuditReadOnly/local-audit"
}

$ aws configure list --profile audit
      Name                    Value             Type    Location
      ----                    -----             ----    --------
   profile                    audit              manual  --profile
access_key     ****************EXAMPLE shared-credentials-file
    region                us-west-2              config-file

Account identifies the AWS account. An ARN containing assumed-role identifies a temporary role session; a user ARN identifies an IAM user. Expiration details may be available from the relevant provider or SDK, but are not normally a standard field in the shared credentials file. Configuration inspection should reveal sources and masked values, never secret key contents.

Security practices

• Never commit credential files, access keys, session tokens, or generated secret-containing configuration to version control.
• Use least privilege: grant only the permissions required for a defined task.
• Separate identities for development, testing, production, auditing, and automation.
• Rotate, deactivate, and remove unused long-term access keys through the approved access process.
• Protect local files with operating-system permissions and keep backups from exposing secrets.
• Do not place secrets in shell history, screenshots, support tickets, logs, or chat messages.
• Use workload identity and secret-management services for deployed applications.
• If a key may have leaked, stop using it, deactivate or revoke it, investigate use, and replace it through your organization’s incident process.

Troubleshooting workflow

Use this order: identify the selected profile, inspect effective configuration and source locations, check credential-related environment variables, verify the caller identity, then review permissions, role trust, and Region settings. Never print or share secret values.

Authentication versus authorization errors

A missing-credentials, invalid-token, or expired-token error usually means AWS cannot authenticate the request. An AccessDenied response usually means authentication succeeded, but the principal is not authorized for the requested action or resource. Confirm the exact principal first; otherwise, it is easy to grant permissions to the wrong identity.

Exam-relevant notes

• Access key IDs identify keys; secret access keys sign requests and must remain confidential.
• Temporary credentials require a session token and expire.
• IAM roles provide temporary credentials and are preferred over long-lived keys for workloads and delegated access.
• An instance profile supplies a role to EC2; a task role supplies credentials to supported containers.
• source_profile identifies credentials used to assume a role; role_arn identifies the target role.
• Authentication proves identity; authorization evaluates permissions.
• The exact provider-chain order depends on the CLI or SDK and its version.

For continued study, see AWS credentials and profiles.