APIs: Concepts, Design, Requests, Responses, and Integration

AWS Credentials: Authentication, Profiles, Roles, and Secure Configuration

Learn how AWS credentials authenticate API requests, how the credential provider chain works, how to configure profiles, and how to use temporary workload credentials securely.

AWS credentials are the identity material used by the AWS CLI, SDKs, and other clients to authenticate API requests. They identify a principal, such as an IAM user, assumed role, or federated session, and enable the client to sign requests sent to AWS services.

Authentication and authorization are separate steps. Authentication answers “Who is making this request?” Credentials establish that identity. Authorization answers “What may that identity do?” IAM policies, resource policies, permissions boundaries, and organization controls determine which actions are allowed.

What AWS credentials contain

The minimum long-term programmatic credential normally contains an access key ID and a secret access key. The access key ID is a non-secret identifier. The secret access key is the secret value used with it to create a signed request.

Temporary credentials contain a third value: a session token. A temporary access key ID and secret access key are not sufficient by themselves; the session token must also be sent. Temporary credentials are issued for a limited period and normally represent an IAM role or federated session.

AWS credential types and identity sources

Long-term IAM user access keys

An IAM user access key is intended for programmatic access associated with an IAM user. It can be used by the CLI or an SDK, but it remains valid until an administrator disables, deletes, or rotates it. This persistence increases the impact of accidental exposure.

If long-term keys are unavoidable, create narrowly scoped permissions, separate keys by purpose, protect them locally, monitor their use, rotate them, and remove unused keys. Do not use an administrator key simply because it is convenient.

Temporary credentials and STS

AWS Security Token Service, commonly called STS, issues temporary credentials. They consist of an access key ID, secret access key, and session token, along with an expiration time. The client must include all three values while the session is valid.

Temporary credentials reduce the useful lifetime of a leaked secret and make it easier to represent a specific session, workload, or role. They are commonly created by assuming an IAM role, signing in through an SSO system, or receiving credentials from an AWS compute environment.

IAM roles

An IAM role is an assumable identity rather than a permanently stored user key. A role has a trust policy describing who or what may assume it and permissions policies describing what the role may do after it is assumed.

For example, a developer may authenticate as a source identity and assume a read-only role in another account. STS then returns a temporary session. The source identity is involved in obtaining the session, but AWS evaluates the assumed role's permissions for actions made through that session.

Federation and single sign-on

Federated access lets an external identity provider authenticate a person or workload and exchange that authentication for an AWS role session. Single sign-on systems can provide named profiles or cached temporary sessions to the CLI and SDKs. This avoids issuing a permanent IAM user key to every developer.

Workload identity

AWS compute services can provide credentials to applications through an attached or associated IAM role. EC2 uses instance metadata, ECS can provide task credentials, Lambda uses its execution role, and EKS commonly uses pod identity or web identity with an OIDC provider. The application uses an SDK provider rather than storing keys in its deployment package.

The credential provider chain

A credential provider chain is the ordered list of sources an AWS CLI or SDK checks when it needs credentials. The client normally selects the first usable source. This lets the same application run locally, in CI, and on AWS without changing its source code.

Common provider sources include:

1. Explicit application configuration: credentials or a credential provider supplied directly to the application. This is powerful but easy to misuse.
2. Environment variables: values such as AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and, for temporary credentials, AWS_SESSION_TOKEN.
3. Shared credentials file: normally ~/.aws/credentials.
4. Shared configuration file: normally ~/.aws/config, which can also participate in role, SSO, and credential configuration.
5. Web identity token files: an OIDC token file used to obtain role credentials.
6. Container credentials: credentials exposed to an ECS or compatible container workload.
7. EC2 instance metadata: credentials obtained from the role attached to an EC2 instance.

The exact order and supported providers vary by AWS SDK, CLI release, language, and configuration. Consult the documentation for the specific implementation. Do not assume that a profile always overrides an environment variable, or that every SDK supports every provider identically.

Shared credentials and configuration files

The default shared credentials file is ~/.aws/credentials. It commonly contains access key values grouped into profiles. The default shared configuration file is ~/.aws/config. It commonly contains region, output format, role settings, SSO settings, and other non-secret configuration.

Credentials files use INI-style sections. In the credentials file, a named profile is normally written as [development]. In the configuration file, the default section is [default], while a named profile is normally written as [profile development].

A credentials file can look like this:

[default]
aws_access_key_id = EXAMPLEACCESSKEY
aws_secret_access_key = EXAMPLESECRETKEY

[development]
aws_access_key_id = EXAMPLEDEVACCESSKEY
aws_secret_access_key = EXAMPLEDEVSECRETKEY

These are placeholders, not usable credentials. A temporary profile would also need an aws_session_token value. Keep the files outside source repositories and restrict their operating-system permissions. On a Unix-like system, a common starting point is:

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

The configuration file can contain settings and role relationships:

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

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

source_profile identifies the profile used to authenticate before assuming the role. Another option, credential_source, tells the SDK or CLI to obtain source credentials from a supported environment such as an attached EC2 role. Use the option supported by the selected SDK or CLI configuration format.

Profiles

A profile is a named set of credential and configuration settings. Profiles are useful for separating accounts, environments, roles, or human identities. The default profile is used when no other profile is selected and no higher-priority provider supplies credentials.

Configure a default local profile interactively:

aws configure

Configure a named development profile:

aws configure --profile development

Select a profile for one CLI command with --profile:

aws sts get-caller-identity --profile development

Select a profile for commands in the current shell with AWS_PROFILE:

export AWS_PROFILE=development
aws sts get-caller-identity

SDKs usually support profile selection through a language-specific configuration option or the AWS_PROFILE environment variable. Prefer the SDK's documented profile configuration rather than embedding secret values in application settings.

Separate development and production profiles

Use clearly named profiles to reduce accidental account changes:

[development]
region = us-east-1

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

A command explicitly selecting production is easier to review than a command that silently depends on whichever profile happens to be default. For destructive operations, verify the caller identity and account before running the command.

Role assumption and temporary sessions

At a conceptual level, role assumption works as follows:

1. A source principal authenticates to AWS. This may be a user, an existing role session, an SSO identity, or a workload identity.
2. The source principal requests AssumeRole from STS.
3. The role trust policy determines whether that source principal may assume the role.
4. STS creates a temporary session with an access key ID, secret access key, session token, and expiration time.
5. The client signs AWS API requests using the temporary session. The role's permissions policies determine the actions allowed by that session.

Both sides matter: a permissive role permissions policy does not help if the trust policy does not allow the source principal, and a successful trust relationship does not grant actions absent from the role's permissions.

A role-assumption profile illustrates the relationship:

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

The development profile is the source identity. The active API session after assumption represents the production-readonly role. This distinction is important when interpreting audit logs and diagnosing permissions.

Automatic credentials on AWS compute

Applications deployed to AWS should normally receive credentials through their workload identity:

• EC2: attach an IAM role to the instance profile. The SDK retrieves temporary credentials through the instance metadata service.
• ECS: assign an appropriate task role. The container credential provider supplies temporary task credentials.
• EKS: use a supported pod identity or OIDC web-identity arrangement so a pod receives role credentials without copied keys.
• Lambda: assign an execution role. The Lambda environment exposes temporary credentials to the SDK.

The application should use the default SDK credential provider rather than manually calling a metadata endpoint or baking keys into an image. The SDK handles retrieval and, when supported, refresh.

Web identity and OIDC

Web identity uses an OIDC token to obtain AWS role credentials. A workload receives a token file and identifies a role to assume. STS validates the federated relationship and returns temporary credentials. This pattern is common for Kubernetes workloads and other systems that integrate with an OIDC identity provider.

Environment variables for short-lived automation

Environment variables can be useful for CI/CD jobs or other short-lived processes when a protected secret mechanism injects them at runtime:

export AWS_ACCESS_KEY_ID=EXAMPLEACCESSKEY
export AWS_SECRET_ACCESS_KEY=EXAMPLESECRETKEY
export AWS_SESSION_TOKEN=EXAMPLESESSIONTOKEN

Include AWS_SESSION_TOKEN whenever the credentials are temporary. Do not hard-code these commands in scripts committed to a repository. A CI/CD platform should store secrets in its protected secret store, limit which jobs can read them, mask them in output, and preferably obtain short-lived role credentials through federation.

AWS_PROFILE selects a profile, while the access-key environment variables provide credential values. Because provider precedence varies, clear or unset variables that could unexpectedly override the profile you want:

unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN
export AWS_PROFILE=development
aws sts get-caller-identity

Credential security practices

• Prefer temporary role credentials, federation, and workload identity over long-lived IAM user keys.
• Apply least privilege: grant only the actions and resources required for the task.
• Use separate identities for development, testing, production, and unrelated workloads.
• Use MFA where appropriate, especially for privileged human access and sensitive role assumption.
• Rotate long-term keys that must exist, and disable or delete unused keys.
• Never put secrets in source code, client-side applications, container images, logs, screenshots, tickets, documentation, or committed configuration files.
• Protect local credential files with operating-system permissions and avoid sharing home directories or build artifacts containing them.
• Use secret-management systems for application secrets, while recognizing that an AWS access key copied into a secret store is still a long-lived key. Prefer a federated or role-based design when possible.
• If a key is exposed, revoke or disable it immediately, investigate its use, replace dependent credentials safely, and remove the secret from the exposure source.

Verification and debugging

The safest first verification request is an STS identity lookup. It shows the AWS account and principal represented by the active credentials:

aws sts get-caller-identity

Verify a named profile explicitly:

aws sts get-caller-identity --profile development

Run this check before account-sensitive operations. It helps distinguish a credential problem from a permissions problem and exposes accidental use of a default or production profile.

For CLI troubleshooting, debug output can show provider and request-resolution details:

aws sts get-caller-identity --debug

Review debug output locally and redact it before sharing. Request diagnostics can reveal account identifiers, role names, file paths, headers, or other sensitive context. Never publish secret access keys, session tokens, authorization headers, or complete signed requests.

Common credential errors

Authentication versus authorization failures

A missing-credentials or invalid-token error usually means the client could not prove a valid identity. An AccessDenied response usually means AWS accepted the identity but the relevant policy evaluation denied the requested action. Confirm the caller first, then investigate permissions.

Practical workflow

1. Choose the identity model. For deployed workloads, start with an attached role, task role, execution role, or web-identity role. For people, prefer SSO or federation.
2. For local development, create a named profile rather than placing secrets in application code.
3. Set the region and other non-secret settings in the shared configuration file or through documented application configuration.
4. Select the profile explicitly with --profile, AWS_PROFILE, or the SDK's profile option.
5. Run aws sts get-caller-identity and confirm the account and principal.
6. Test the smallest required API operation.
7. If the request fails, determine whether the failure is credential resolution, token validity, request signing, region selection, or authorization.

Exam-relevant notes

• An access key ID is an identifier; the secret access key is secret signing material.
• Temporary credentials require the session token in addition to the access key ID and secret access key.
• Credentials authenticate a principal; IAM policies authorize actions.
• An IAM role commonly produces temporary credentials through STS.
• ~/.aws/credentials normally stores profile credentials, while ~/.aws/config normally stores region, output, role, and SSO configuration.
• AWS_PROFILE and --profile select profiles, but exact provider precedence depends on the CLI or SDK implementation.
• EC2, ECS, EKS, and Lambda can obtain temporary credentials through workload identity mechanisms, avoiding stored access keys.
• The best diagnostic for the active identity is aws sts get-caller-identity.

For related API credential material, see AWS credential details and the AWS credentials endpoint. Use these paths only as part of an authorized application or service integration.