S3

AWS Credentials for Amazon S3 Access

Learn how AWS credentials authenticate S3 requests, configure AWS CLI profiles, use IAM roles and temporary credentials, apply least privilege, and troubleshoot access failures.

AWS credentials are information used to authenticate a request to AWS. When you use the AWS CLI, an SDK, or an application to access Amazon S3, AWS must identify the principal: the user, role, or federated session making the request.

Authentication answers “Who is making this request?” Authorization answers “Is that principal allowed to perform this action on this resource?” Valid credentials solve only the authentication part. IAM policies, bucket policies, access point policies, permission boundaries, service control policies, and explicit denies affect authorization.

How credentials control S3 access

An AWS CLI or SDK obtains credentials, creates a request, and signs it using AWS Signature Version 4. The signed request contains information that allows AWS to verify the caller and detect changes to the request.

  1. The CLI, SDK, or workload searches its credential provider chain.
  2. The selected credentials sign the S3 request.
  3. AWS authenticates the request and identifies the principal.
  4. IAM and S3 resource policies evaluate whether the principal may perform the requested action.
  5. S3 returns the result or an error such as AccessDenied.

A request can therefore fail even when credentials are present. For example, a principal may be authenticated but lack s3:PutObject permission for the destination object, or a bucket policy may contain an explicit deny.

AWS identity and credential types

An AWS credential method determines how an identity obtains permission to call AWS APIs. Long-lived access keys are convenient for some local cases but increase the risk of exposure. Temporary credentials are preferred because they expire.

Root user credentials — Account-wide identity; long-lived and highly privileged; create the account, protect with MFA, and avoid for everyday S3 work; never use root access keys for routine operations.

IAM user access keys — Long-lived identity credentials; useful only where an approved legacy or external integration requires them; restrict permissions, protect the secret, rotate, and deactivate when no longer needed.

IAM role credentials — Temporary credentials obtained by assuming a role; recommended for applications, AWS workloads, and cross-account access; configure trust policies and least-privilege permissions.

AWS IAM Identity Center (SSO) — Workforce sign-in using permission sets; temporary CLI and SDK sessions; suitable for human access and avoids distributing IAM user keys.

EC2 instance profile — An IAM role attached to an EC2 instance; temporary credentials are provided through instance metadata; do not store access keys on the instance.

ECS task role — An IAM role assigned to an ECS task; the application receives task-scoped temporary credentials.

Lambda execution role — An IAM role assumed by the Lambda service while a function runs; the function receives temporary credentials automatically.

Web identity credentials — Temporary role credentials obtained using a web identity token; commonly used by Kubernetes workloads such as EKS pods.

Credential components

  • Access key ID: A public identifier associated with an access key. It is not sufficient by itself to authenticate a request.
  • Secret access key: A private value used to sign requests. Treat it like a password; AWS generally cannot show the original secret again after creation.
  • Session token: An additional value required with temporary credentials. The access key ID, secret access key, and session token must come from the same session.
  • Region: The AWS geographic region used by the client. It is configuration rather than a credential, but an incorrect region can cause endpoint or signature errors.
  • Expiration: Temporary credentials work only until their session expiration time. Supported SSO, role, and workload providers can refresh them automatically.

Creating least-privilege S3 access

Least privilege means granting only the permissions needed for a defined task. Avoid solving an S3 error by granting broad administrator permissions.

S3 permissions apply to different resource types. Bucket-level actions commonly use a bucket ARN, while object-level actions use object ARNs that include a key or prefix.

List bucket contents — s3:ListBucket — bucket — arn:aws:s3:::example-bucket

Read an object — s3:GetObject — object — arn:aws:s3:::example-bucket/uploads/report.csv

Upload an object — s3:PutObject — object — arn:aws:s3:::example-bucket/uploads/*

Delete an object — s3:DeleteObject — object — arn:aws:s3:::example-bucket/uploads/*

Read bucket location — s3:GetBucketLocation — bucket — arn:aws:s3:::example-bucket

This policy grants only upload permission to one prefix:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "s3:PutObject",
      "Resource": "arn:aws:s3:::example-bucket/uploads/*"
    }
  ]
}

The policy does not grant listing, reading, or deletion. Actual requirements can also depend on encryption, KMS permissions, bucket ownership settings, access points, and organizational controls.

Installing and configuring the AWS CLI

Install the AWS CLI using your organization's approved installation method, then verify that it is available:

aws --version

Configure a default access-key-based profile with:

aws configure

The prompts normally request an access key ID, secret access key, default region, and output format. For example, the region might be us-east-1 and the output format might be json. Do not paste real secrets into scripts or examples.

For a separate environment, create a named profile:

aws configure --profile development

Select it explicitly for a command:

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

You can select a profile for the current shell:

export AWS_PROFILE=development

On Windows PowerShell, use $env:AWS_PROFILE = "development". Check the selected profile carefully because an environment variable can cause commands to use a different identity than expected.

Shared credentials and configuration files

The shared credentials file stores access-key-based profiles. The AWS config file stores settings such as regions, output formats, role profiles, and SSO configuration.

  • Linux and macOS normally use ~/.aws/credentials and ~/.aws/config.
  • Windows normally uses %USERPROFILE%\.aws\credentials and %USERPROFILE%\.aws\config.
  • AWS_SHARED_CREDENTIALS_FILE and AWS_CONFIG_FILE can point to alternate locations.
  • The default profile is written as [default] in the credentials file and commonly as [default] in the config file.
  • Named profiles use a name such as [development] in the credentials file and [profile development] in the config file.

Protect these files with operating-system permissions. On a Unix-like system, a local access-key file should normally be readable only by its owner:

chmod 600 ~/.aws/credentials
chmod 600 ~/.aws/config

Do not commit either file to version control. Add credential files to .gitignore and use secret scanning in repositories and CI systems.

Role profiles

A role profile uses one profile as the source identity and obtains temporary credentials for another role:

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

The source identity must be allowed by the role's trust policy to call sts:AssumeRole. The role's permissions policy then controls what it can do in the target account.

SSO profiles

Create an AWS IAM Identity Center profile with:

aws configure sso --profile workforce
aws sso login --profile workforce
aws sts get-caller-identity --profile workforce

The prompts and organization-specific sign-in settings depend on the Identity Center configuration. The resulting profile uses a temporary session rather than a permanent IAM user secret.

Credential provider precedence

The credential provider chain is the ordered set of locations that the CLI or SDK checks for credentials. Exact details vary by SDK and operation, but explicit settings and environment configuration commonly take precedence over local files and workload metadata.

CLI command options — An explicit profile or command setting; selected for that invocation; a typo or unexpected option can select the wrong settings.

Environment variables — For example, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN; useful for short-lived sessions and automation; stale variables can override the intended profile.

AWS_PROFILE — Selects a named profile; applies to the shell or process; may make commands use another account.

Shared credentials file — Access-key profiles such as [development]; used when higher-priority sources do not supply credentials; file permissions or wrong profile names cause failures.

Shared config file and role profile — Uses role settings and a source profile; obtains temporary credentials; the trust policy or source credentials may be incorrect.

Web identity token file — Exchanges a token for role credentials; common for EKS and federated workloads; missing or expired tokens prevent credential retrieval.

Container credentials — ECS task-role provider; supplies credentials to the task; incorrect task-role configuration or network restrictions can interfere.

EC2 instance metadata — Supplies credentials for an attached instance profile; metadata access or role attachment may be unavailable.

SDKs use a similar provider-chain concept. Avoid ambiguity by using one deliberate method per execution environment, checking the active identity, and removing obsolete environment variables.

Using credentials with S3 operations

These commands use a fictional bucket and a named profile:

aws sts get-caller-identity --profile development
aws s3 ls --profile development
aws s3 ls s3://example-bucket/ --profile development
aws s3 cp ./report.csv s3://example-bucket/uploads/report.csv --profile development
aws s3 cp s3://example-bucket/uploads/report.csv ./report.csv --profile development
aws s3 cp s3://example-bucket/uploads/report.csv s3://example-bucket/archive/report.csv --profile development

aws s3 ls may require permission to list buckets or may fail even though access to a particular bucket is allowed. Object upload requires permission for the destination object, commonly s3:PutObject. The signed request identifies the caller; S3 does not infer permission from the local filename or profile name.

Temporary credentials and role assumption

STS, the AWS Security Token Service, issues temporary credentials. AssumeRole is an STS operation that lets a trusted principal obtain credentials for an IAM role.

Temporary credentials reduce the impact of exposure because they expire. A role requires both:

  • A trust policy stating which principals may assume it.
  • A permissions policy stating which AWS actions the role may perform.

Role sessions have a configured duration and expiration. SSO tools, role profiles, EC2 instance profiles, ECS task roles, Lambda execution roles, and supported SDK providers can refresh credentials automatically. A cross-account workflow typically signs in to an identity in one account, assumes a role trusted by the target account, and uses the resulting session to access the target S3 resource. The target bucket policy may also need to allow the role or its account.

Workload identity

Applications running on AWS should normally use workload identity rather than embedded access keys:

  • Attach an IAM role to an EC2 instance through an instance profile.
  • Assign an IAM task role to an ECS task.
  • Assign an execution role to a Lambda function.
  • Use web identity federation for supported Kubernetes or other federated workloads.

The AWS SDK obtains temporary credentials from the environment's provider and refreshes them when supported. The application should not read or write permanent credentials on disk.

Credential security practices

  • Use IAM roles, Identity Center, or an approved external secret-management system instead of static keys where possible.
  • Never embed credentials in source code, browser code, images, documentation, container images, or committed configuration.
  • Use .gitignore, pre-commit checks, repository secret scanning, and CI secret detection.
  • Rotate long-lived access keys and deactivate or delete keys that are no longer needed.
  • If a secret may have been exposed, stop using it, deactivate or replace it immediately, investigate usage, and remove it from repositories and logs.
  • Require MFA for appropriate human access and use organizational controls for sensitive operations.
  • Review IAM credential reports and monitor API activity with CloudTrail.

Troubleshooting S3 credential failures

First separate credential discovery problems from authorization problems. Run:

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

Unable to locate credentials — No usable provider supplied credentials — inspect aws configure list, AWS_PROFILE, file locations, SSO login, and workload role attachment — configure the intended profile, sign in, attach a role, or remove unintended overrides.

InvalidClientTokenId — Invalid, deleted, or deactivated key, or mixed credential values — inspect the selected profile and environment variables — use active credentials from one approved source.

ExpiredToken — Temporary session has expired or an old token remains exported — identify whether the source was STS, SSO, a role, or environment variables — refresh the session and replace stale variables.

AccessDenied — Authentication succeeded but authorization failed — verify the caller and review IAM, bucket, access point, permission boundary, SCP, VPC endpoint policy, and explicit denies — grant only the missing scoped permission or correct the deny.

SignatureDoesNotMatch — Wrong secret, mismatched session token, altered request, or incorrect clock — verify credential pairs and system time — refresh credentials, synchronize the clock, and use current CLI or SDK signing.

AuthorizationHeaderMalformed — Region or signing information does not match the S3 endpoint — check the configured region and bucket location — use the correct region and allow the CLI or SDK to construct the request.

Wrong account or role — Another profile or environment variable is active — run aws sts get-caller-identity and inspect AWS_PROFILE — specify the intended profile explicitly.

Resolving AccessDenied on upload

  1. Run aws sts get-caller-identity with the same profile used for the upload.
  2. Confirm that the role or user has s3:PutObject on the exact destination ARN, including the prefix.
  3. Check whether encryption requires additional KMS permissions.
  4. Review the bucket policy and access point policy for conditions or explicit denies.
  5. Check permission boundaries, organization service control policies, VPC endpoint policies, and identity or network conditions.
  6. Do not grant administrator access merely to make the error disappear.

Exam-relevant notes

  • Authentication identifies the principal; authorization evaluates permissions.
  • An access key ID is not secret, but the secret access key is private.
  • Temporary credentials require a session token.
  • IAM roles normally provide temporary credentials and are preferred for AWS workloads.
  • s3:ListBucket applies to a bucket resource; s3:GetObject, s3:PutObject, and s3:DeleteObject apply to object resources.
  • An explicit deny overrides an allow.
  • Always verify the active principal with aws sts get-caller-identity before diagnosing an S3 permission problem.
  • Credential provider precedence can cause a valid but unintended identity to be used.

For a shorter reference, see AWS credentials quick reference.