.Aws

Retrieve IAM Role Security Credentials from Amazon EC2 Instance Metadata

Learn how EC2 applications use instance profile roles and IMDSv2 to obtain temporary AWS credentials, configure metadata security, and troubleshoot credential access.

Overview

Amazon EC2 workloads can obtain temporary AWS credentials from the Amazon EC2 Instance Metadata Service (IMDS). IMDS is a local service available from an EC2 instance, including metadata about the instance and its attached IAM role.

The normal metadata endpoint is http://169.254.169.254/latest/. The IAM security-credentials hierarchy is /latest/meta-data/iam/security-credentials/, so the complete role-discovery URL is http://169.254.169.254/latest/meta-data/iam/security-credentials/.

This service is not a general-purpose public AWS API endpoint. It is intended to be reached from the instance, subject to the instance's metadata configuration and network design.

How EC2 Role Credentials Work

Role, instance profile, and credentials

An IAM role is an AWS identity with permission policies. A role can be associated with an EC2 instance through an instance profile. The instance profile is the EC2 attachment container; it is not the same thing as the role.

After a suitable role is attached, IMDS makes a temporary credential set available to software running on the instance. The set contains an access key ID, a secret access key, and a session token. These are temporary security credentials, not permanent user access keys.

• IAM role: Defines the identity and permissions.
• Instance profile: Associates the role with the EC2 instance.
• Temporary credentials: The time-limited values used by applications to sign AWS requests.

This arrangement avoids embedding long-term access keys in source code, images, configuration files, or deployment scripts. Applications can use the role to call AWS APIs, read or write Amazon S3 data, publish metrics or logs, read secrets, and use supported AWS SDKs or the AWS CLI.

The IAM Metadata Credential Path

The credential hierarchy is under /latest/meta-data/iam/security-credentials/. Retrieval uses two logical requests:

1. Request the directory path to obtain the name of the role attached through the instance profile.
2. Append that role name to the path and request the role-specific credential document.

Use the /latest path for normal requests. The IPv4 link-local address is 169.254.169.254. An IPv6 metadata endpoint is available only where the EC2 networking configuration supports it; its availability should not be assumed for every instance.

IMDSv2 Authentication Flow

IMDSv2 is the token-based version of IMDS. A client first obtains a metadata token with an HTTP PUT, then includes that token in later metadata requests. This extra step helps reduce the chance that an unintended server-side request, such as an SSRF request, can directly retrieve metadata.

A metadata token authorizes IMDS requests. It is different from the AWS session token returned in the credential document.

TOKEN=$(curl -sS -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")

The TTL header requests the token lifetime in seconds, subject to the service's limits. A token is scoped to the instance. It can be reused for requests from that instance until it expires, and a client can request a replacement token when needed.

curl -sS -H "X-aws-ec2-metadata-token: $TOKEN" "http://169.254.169.254/latest/meta-data/iam/security-credentials/"

The response to the first GET is the role name. Use it in the second request:

ROLE_NAME=$(curl -sS -H "X-aws-ec2-metadata-token: $TOKEN" "http://169.254.169.254/latest/meta-data/iam/security-credentials/") && curl -sS -H "X-aws-ec2-metadata-token: $TOKEN" "http://169.254.169.254/latest/meta-data/iam/security-credentials/$ROLE_NAME"

If IMDSv2 is required, a missing, expired, or invalid metadata token causes the metadata request to fail. Scripts that make tokenless requests must be updated.

Temporary Credential Document

The role-specific response is JSON. It should be treated as secret material. Do not log it, paste it into tickets or chat, place it in shell history, or commit it to source control.

AccessKeyId, SecretAccessKey, and Token are one temporary session credential set. Supplying only the first two values is incomplete and can cause AWS authentication failures.

Automatic Use by the AWS CLI and SDKs

Supported AWS SDKs and the AWS CLI normally use a credential provider chain. This is an ordered collection of credential sources. One provider in the chain can query EC2 instance metadata and refresh instance-profile credentials automatically.

In normal application code, prefer the SDK's default credential resolution instead of manually parsing metadata JSON. The same principle applies to the AWS CLI when it runs on an EC2 instance with an attached role.

aws sts get-caller-identity

This command shows the AWS principal selected by the CLI. A supported SDK client should usually be created without hard-coded credentials so its standard provider can retrieve and refresh the role credentials.

Container credential settings and explicitly selected profiles can also affect provider selection. Always confirm the active identity when credentials appear unexpected.

Rotation, Expiration, and Refresh

EC2 role credentials are temporary. AWS rotates them before expiration and makes the new values available through the credential provider. Applications should use a provider that refreshes credentials rather than storing one credential document forever.

Manually exporting the values as environment variables is not a durable configuration method. Those exported values can become stale even while the instance role continues to work normally.

If an API call returns an expired-token or invalid-token error, allow the SDK or provider to refresh and retry according to its documented behavior. Code that accesses IMDS directly must check expiration, obtain fresh credentials before they expire, and avoid exposing the values during diagnostics.

Metadata Security Controls

Require IMDSv2

Requiring IMDSv2 is the recommended deployment setting for instances that use metadata. It rejects tokenless IMDSv1 requests and makes accidental or malicious metadata access more difficult.

aws ec2 modify-instance-metadata-options --instance-id i-0123456789abcdef0 --http-tokens required --http-endpoint enabled

aws ec2 describe-instances --instance-ids i-0123456789abcdef0 --query "Reservations[].Instances[].MetadataOptions" --output table

IMDSv1 does not require a session token and uses direct metadata requests. IMDSv2 requires the token request followed by token-bearing metadata requests.

Endpoint, hop limit, and network boundaries

Disabling the metadata endpoint prevents workloads from obtaining role credentials through IMDS. If an application does not need metadata, disabling it can reduce attack surface. If it is enabled, restrict which workloads can reach it.

The metadata hop limit controls how far metadata responses can travel through the network. A low value can prevent responses from reaching containers or forwarded network paths; a higher value may be required for an intentional container design. Increasing it also increases the importance of isolating untrusted workloads.

Do not expose metadata requests through a reverse proxy, application proxy, or URL-fetching feature. Never forward metadata responses to untrusted callers. Defend application endpoints against SSRF, or server-side request forgery, by validating destination URLs, restricting outbound network access, blocking link-local and other internal destinations where appropriate, and separating privileged workloads from untrusted input.

Role Attachment and Authorization

Credentials appear at the IAM security-credentials path only when an appropriate IAM role is attached through an instance profile and the metadata endpoint is available. The role's policies determine which AWS API operations the instance can perform.

These are separate failure categories:

• Unable to retrieve credentials: The role may be missing, the endpoint may be disabled, the path may be wrong, or IMDSv2 authentication may be incomplete.
• Credentials retrieved but action denied: The role identity is valid, but IAM or a related policy does not authorize the requested operation or resource.

An explicit deny, permissions boundary, resource policy, or organization policy can also block an operation. Change permissions according to least privilege rather than installing long-term user keys. IAM policy changes are generally effective quickly, but propagation is not guaranteed to be instantaneous; allow a short interval before concluding that a valid policy update failed.

Troubleshooting

No role name or a not-found response

• Check that an IAM role is associated with the instance through an instance profile.
• Inspect the instance metadata options and confirm that the endpoint is enabled when the workload requires it.
• Use /latest/meta-data/iam/security-credentials/, not an unrelated path.

Unauthorized metadata request

• Create a fresh token with the PUT request.
• Send X-aws-ec2-metadata-token: $TOKEN on every follow-up request.
• Check whether the token expired or a proxy removed the header.

Unexpected AWS identity

• Run aws sts get-caller-identity.
• Inspect environment variables such as configured access key values.
• Check shared AWS configuration, credentials files, selected profiles, container credential settings, and explicit SDK credential initialization.
• Remove unintended overrides and rely on the default provider chain where suitable.

Expired-token API errors

• Check whether the application cached credential values indefinitely.
• Replace manual credential parsing with the SDK's refreshing provider.
• If direct metadata access is unavoidable, refresh before Expiration and do not persist the values as static configuration.

Credentials exist but an operation is denied

• Confirm the active role with an identity query.
• Evaluate identity policies, resource policies, permissions boundaries, explicit denies, and organization controls.
• Grant only the required actions and resources.

Host access works but a container or proxy fails

• Review the metadata hop limit and the actual network path.
• Check whether container or proxy networking blocks link-local access or removes required headers.
• Do not broadly expose host metadata to untrusted containers; use a workload-appropriate credential delivery mechanism when direct access is unsuitable.

Exam-Relevant Notes

• An instance profile is the EC2 mechanism that attaches an IAM role; it is not the temporary credential set itself.
• IMDSv2 uses a metadata token, while AWS API signing uses an AWS session token. They are different values with different purposes.
• The role-name request precedes the role-specific credential request.
• Temporary credentials require the access key ID, secret access key, and session token together.
• Use SDK and CLI default credential resolution so rotation and refresh are handled automatically.
• Requiring IMDSv2, using least privilege, controlling hop limits, and preventing SSRF are complementary controls.

Related Reference

See the Security Credentials reference path for the IAM metadata credential hierarchy.