The metadata of ECS instances can be accessed in normal or security-enhanced mode. In security-enhanced mode, ECS instances access instance metadata by using token-based authentication. The security-enhanced mode provides better protection against Server-Side Request Forgery (SSRF) attacks than the normal mode does.

Overview

An SSRF is an attack in which an attacker takes advantage of vulnerabilities in a server to send crafted resource requests to the server and access resources located within the same internal network. When a request for instance metadata is received, the instance metadata server shares the requested metadata in the format of URLs. These URLs are vulnerable to tampering and may be used to attack internal systems that are not accessible to external networks. To prevent SSRF attacks, we recommend that you access instance metadata in security-enhanced mode.

The following table compares the normal and security-enhanced modes.
Comparison item Normal mode Security-enhanced mode
Interaction mode Requests and responses. Sessions.
Security verification Verification of source IP addresses in the same VPC. Token-based authentication.
Access method Use cURL commands to access the endpoint. Use cURL commands to access the endpoint. Requests must include token headers.

In normal mode, a new connection is established with each request to access instance metadata, and the connection is released immediately after the request has been completed. This mode uses a simple verification method. If the instance metadata server is attacked and sensitive data such as RAM roles is leaked, your data and assets are under threats.

In security-enhanced mode, you can establish a session between an ECS instance and the instance metadata server. When you access instance metadata through the ECS instance, the instance metadata server authenticates your identity based on a token. When the token expires, the instance metadata server closes the session and deletes the token. For more information about the access process, see Procedure to access instance metadata in security-enhanced mode. The following limits apply to tokens:
  • Each token can only be used for a single ECS instance. If you copy the token file of one ECS instance to another ECS instance, the instance metadata server will deny access from the ECS instance using the copied token file.
  • Each token must have a defined validity period ranging from 1 to 21,600 seconds (six hours). Tokens can be repeatedly used until they expire. This helps achieve a good balance between security and user experience.
  • Proxy access is not supported. If a token creation request contains the X-Forwarded-For header, the instance metadata server will refuse to issue the token.
  • An unlimited number of tokens can be issued to each ECS instance.

Scenarios of the security-enhanced mode

In the following scenarios, we recommend that you access instance metadata in security-enhanced mode to prevent SSRF attacks and improve the security of applications:
  • Access self-built network firewall applications.
  • Access self-built reverse proxy applications.
  • Access self-built web applications that provide transcoding and download services.

Procedure to access instance metadata in security-enhanced mode

This section describes how to run a cURL command to create and use a token to access instance metadata in security-enhanced mode.
  1. Use the PUT method to initiate a request to create a token.

    You must specify the token validity period in the header in the following format: X-aliyun-ecs-metadata-token-ttl-seconds:<token validity period>.

  2. The instance metadata server issues the token.
  3. When you access instance metadata, enter the endpoint of the instance metadata server and the token header.

    Token header format: x-aliyun-ecs-metadata-token: $TOKEN.

  4. When authentication succeeds, the instance metadata server returns the requested instance metadata.
The following command is a sample command to create and use a token:
TOKEN=`curl -X PUT "http://100.100.100.200/latest/api/token" -H "X-aliyun-ecs-metadata-token-ttl-seconds: 21600"` \
&& curl -H "X-aliyun-ecs-metadata-token: $TOKEN"  http://100.100.100.200/latest/meta-data/instance-id
The preceding sample command involves the following steps:
  • Use the PUT method to create a token with a validity period of 21,600 seconds (6 hours).
  • Use the TOKEN variable to store the token.
  • Access the instance ID in instance metadata and include the $TOKEN variable in the request.
Tokens can be repeatedly used until they expire. The following command is a sample command to use an existing token:
curl -H "X-aliyun-ecs-metadata-token: $TOKEN"  http://100.100.100.200/latest/meta-data/instance-id
Error examples:
  • The validity period exceeds the allowed maximum length.
    curl -X PUT "http://100.100.100.200/latest/api/token" -H "X-aliyun-ecs-metadata-token-ttl-seconds: 21700"
  • The token creation request contains the X-Forwarded-For header.
    curl -X PUT "http://100.100.100.200/latest/api/token" -H "X-Forwarded-For: www.ba****.com"
  • The token specified for access to instance metadata is invalid.
    curl -H "X-aliyun-ecs-metadata-token: aaa" -v http://100.100.100.200/latest/meta-data/