EC2 Instance Metadata Service (IMDS) is a crucial component for applications running on EC2 instances. It provides access to instance-specific data, such as instance IDs, security group memberships, and importantly, temporary security credentials for accessing other AWS services. Historically, IMDSv1 was the default, but it’s vulnerable to Server-Side Request Forgery (SSRF) attacks, where an attacker could trick an application into making requests to the IMDS endpoint, potentially exfiltrating sensitive information. IMDSv2 addresses this by introducing a session-oriented, token-based authentication mechanism.
The most surprising true thing about IMDSv2 is that it doesn’t just add a security layer; it fundamentally changes how you retrieve metadata, requiring a two-step process for every request.
Let’s see IMDSv2 in action with a practical example. Imagine you want to retrieve the instance identity document, which contains information about your EC2 instance.
First, you need to obtain a session token. This is done using a PUT request to the IMDS endpoint. The http-put-response-hop-limit parameter is crucial here; setting it to 1 ensures that the token can only be used from within the instance itself, preventing hop-across instances.
TOKEN=$(curl -X PUT "http://169.254.169.254/latest/api/token" -H "x-aws-ec2-metadata-token-ttl-seconds: 21600")
Here, 21600 is the Time-To-Live (TTL) for the token, set to 6 hours. You can adjust this based on your security requirements.
Once you have the token, you can use it to make GET requests to retrieve the metadata. For the instance identity document, the endpoint looks like this:
curl -H "x-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/dynamic/instance-identity/document
This curl command uses the obtained token in the x-aws-ec2-metadata-token header to authenticate the request. The response will be a JSON document containing details like the instance’s region, instance ID, account ID, and public/private IP addresses.
The core problem IMDSv2 solves is mitigating SSRF vulnerabilities in metadata access. By requiring a token obtained via a hop-limited PUT request, it ensures that only code running on the instance can generate valid tokens, and each metadata retrieval requires an explicit, authenticated request. This prevents external attackers from simply curling 169.254.169.254 and getting sensitive information.
Internally, IMDSv2 works by establishing a session. The initial PUT request to /latest/api/token initiates this session and returns a unique token. This token is then used as a bearer token in subsequent GET requests to any other metadata endpoint. The IMDS service validates this token, including its TTL and hop limit, before returning the requested metadata. If the token is invalid, expired, or has been used from a different hop count, the request will be denied.
The primary lever you control when using IMDSv2 is the x-aws-ec2-metadata-token-ttl-seconds parameter. A shorter TTL increases the frequency of token refreshes, which adds a small overhead but enhances security by limiting the window of opportunity if a token were somehow compromised. A longer TTL reduces this overhead but increases the potential exposure. The default TTL is 1 hour (3600 seconds), but you can set it up to 21600 seconds (6 hours).
Many systems are configured to allow IMDSv1 access for backward compatibility or due to oversight. While IMDSv2 is enabled, if the HttpTokens configuration is set to optional or allow, an attacker could still potentially exploit IMDSv1. To enforce IMDSv2, you must configure the instance metadata service to require tokens by setting HttpTokens to required. This is typically done at the EC2 instance’s launch configuration or its runtime settings.
The next concept you’ll likely encounter is how to manage these IMDSv2 tokens programmatically within your applications, especially in distributed systems or when dealing with long-running processes that need to refresh their credentials.