Use instance identities to perform authentication or authorization or identify the runtime environment - Elastic Compute Service

An instance identity consists of an instance identity document and an instance identity signature. Instance identities are used to rapidly identify and distinguish among Elastic Compute Service (ECS) instances. The instance identities provide a trust basis for managing permissions on applications and activating software. This topic describes the definition and scenarios of instance identities and how to obtain and use instance identities.

Instance identities

An instance identity consists of an instance identity document (document) and an instance identity signature (signature).

Instance identity document

An instance identity document contains the identity information of an instance. The following table describes the items that are contained in the instance identity document.

Item	Description
account-id	The ID of the Alibaba Cloud account to which the instance belongs.
instance-id	The ID of the instance.
mac	The media access control (MAC) address of the primary elastic network interface (ENI) of the instance.
region-id	The region ID of the instance.
serial-number	The serial number of the instance.
zone-id	The zone ID of the instance.
instance-type	The instance type.
image-id	The ID of the image used by the instance.
private-ip	The private IP address of the instance.

Instance identity signature
An instance identity signature is used by third parties to validate the authenticity and content of the instance identity document. An instance identity signature is a secure and reliable digital signature that is encrypted by using the PKCS #7 standard.
You can configure the audience parameter in an instance identity signature to prevent the signature from being spoofed. The value of the audience parameter can be a random string, a timestamp, regularly changing information, or data generated by an algorithm. After you configure the audience parameter in an instance identity signature, spoofers cannot obtain the value of the audience parameter even if they obtained information about the instance identity document and the signature. You can use the audience parameter to perform authentication. For more information, see the Use instance identities section of this topic.

Scenarios

In the following scenarios, you can use instance identities for authentication, authorization, or runtime environment identification.

In most cases, software off the cloud is activated by using a single license code. This practice is not suitable for cloud-based software that is used at varying points in time and in different scenarios. You can use instance identities for user authorization when you publish application software in Alibaba Cloud Marketplace.
When you write sensitive data to an ECS instance, you can use the instance identity to ensure that you are writing the sensitive data to the exact instance that you want to use.
Scenarios in which you want to confirm the source of an instance.

Obtain the instance identity document or signature

(Recommended) Obtain the instance identity document or signature in security hardening mode

Linux instance

# Obtain server access credentials. Specify a validity period for the credentials and make sure that the request to create a token does not include the X-Forwarded-For header.
TOKEN='curl -X PUT "http://100.100.100.200/latest/api/token" -H "X-aliyun-ecs-metadata-token-ttl-seconds:<Validity period of the server access credentials>"'
# Obtain the instance identity.
curl -H "X-aliyun-ecs-metadata-token: $TOKEN" http://100.100.100.200/latest/<dynamic data>

Windows instance
```
# Obtain server access credentials. Specify a validity period for the credentials and make sure that the request to create a token does not include the X-Forwarded-For header.
$token = Invoke-RestMethod -Headers @{"X-aliyun-ecs-metadata-token-ttl-seconds" = "<Validity period of the server access credentials>"} -Method PUT -Uri http://100.100.100.200/latest/api/token
# Obtain the instance identity.
Invoke-RestMethod -Headers @{"X-aliyun-ecs-metadata-token" = $token} -Method GET -Uri http://100.100.100.200/latest/<dynamic data>
```
- <Validity period of the server access credentials>: specifies the validity period of the server access credentials. Valid values: 1 to 21600. Unit: seconds. The access credentials are used for authentication to enhance data security.
  - Within the validity period, you can repeatedly run the preceding command to obtain the instance identity. After the validity period ends, you must obtain new credentials before you request the instance identity.
  - The access credentials apply to only one instance. If you copy the credentials to obtain the identity of another instance, your request is denied.
- <dynamic data>: Replace this parameter with one of the following values:
  - dynamic/instance-identity/document: specifies an instance identification document.
  - dynamic/instance-identity/pkcs7?audience=XXXX: specifies an instance identity signature.
    Important
    The ?audience=XXXX parameter is optional. For more information, see the Instance identity signature section of this topic.

Obtain the instance identity document or signature in normal mode

Linux instance

curl http://100.100.100.200/latest/<dynamic data>

Windows instance (PowerShell)
```
Invoke-RestMethod http://100.100.100.200/latest/<dynamic data>
```
<dynamic data>: Replace this parameter with one of the following values:
- dynamic/instance-identity/document: specifies an instance identification document.
- dynamic/instance-identity/pkcs7?audience=XXXX: specifies an instance identity signature.
  Important
  The ?audience=XXXX parameter is optional. For more information, see the Instance identity signature section of this topic.

Use instance identities

Procedure

This section describes how to use an instance identity in security hardening mode. In this example, an instance that runs Alibaba Cloud Linux 3 is used.

Important

OpenSSL is required to validate and use instance identities to ensure security. If you did not configure OpenSSL, visit the official OpenSSL website to download and install OpenSSL.

Connect to a Linux instance.
For more information, see Connect to a Linux instance by using a password or key.

(Optional) Run the following commands to obtain the instance identity document and signature:

# Obtain server access credentials. Set the validity period of the credentials to 3,600 seconds.
TOKEN=`curl -X PUT "http://100.100.100.200/latest/api/token" -H "X-aliyun-ecs-metadata-token-ttl-seconds:3600"`
# Obtain the instance identity document.
curl -H "X-aliyun-ecs-metadata-token: $TOKEN" http://100.100.100.200/latest/dynamic/instance-identity/document
# Obtain the instance identity signature.
curl -H "X-aliyun-ecs-metadata-token: $TOKEN" http://100.100.100.200/latest/dynamic/instance-identity/pkcs7

Save the instance identity document, instance identity signature, and Alibaba Cloud public certificate to files.

Run the following command to save the instance identity document information to the document file:
```
curl 100.100.100.200/latest/dynamic/instance-identity/document > document
```

Run the following commands to save the instance identity signature to the signature file:

echo "-----BEGIN CERTIFICATE-----" > signature
curl 100.100.100.200/latest/dynamic/instance-identity/pkcs7 >> signature
echo "" >> signature
echo "-----END CERTIFICATE-----" >> signature

Run the following commands to save the Alibaba Cloud public certificate to the cert.cer file:

cat <<EOF > cert.cer
-----BEGIN CERTIFICATE-----
MIIDdzCCAl+gAwIBAgIEZmbRhzANBgkqhkiG9w0BAQsFADBsMRAwDgYDVQQGEwdV
bmtub3duMRAwDgYDVQQIEwdVbmtub3duMRAwDgYDVQQHEwdVbmtub3duMRAwDgYD
VQQKEwdVbmtub3duMRAwDgYDVQQLEwdVbmtub3duMRAwDgYDVQQDEwdVbmtub3du
MB4XDTE4MDIyMzAxMjkzOFoXDTM4MDIxODAxMjkzOFowbDEQMA4GA1UEBhMHVW5r
bm93bjEQMA4GA1UECBMHVW5rbm93bjEQMA4GA1UEBxMHVW5rbm93bjEQMA4GA1UE
ChMHVW5rbm93bjEQMA4GA1UECxMHVW5rbm93bjEQMA4GA1UEAxMHVW5rbm93bjCC
ASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAIJwy5sbZDiNyX4mvdP32pqM
YMK4k7+5lRnVR2Fky/5uwyGSPbddNXaXzwEm+u4wIsJiaAN3OZgJpYIoCGik+9lG
5gVAIr0+/3rZ61IbeVE+vDenDd8g/m/YIdYBfC2IbzgS9EVGAf/gJdtDODXrDfQj
Fk2rQsvpftVOUs3Vpl9O+jeCQLoRbZYm0c5v7jP/L2lK0MjhiywPF2kpDeisMtnD
/ArkSPIlg1qVYm3F19v3pa6ZioM2hnwXg5DibYlgVvsIBGhvYqdQ1KosNVcVGGQa
HCUuVGdS7vHJYp3byH0vQYYygzxUJT2TqvK7pD57eYMN5drc7e19oyRQvbPQ3kkC
AwEAAaMhMB8wHQYDVR0OBBYEFAwwrnHlRgFvPGo+UD5zS1xAkC91MA0GCSqGSIb3
DQEBCwUAA4IBAQBBLhDRgezd/OOppuYEVNB9+XiJ9dNmcuHUhjNTnjiKQWVk/YDA
v+T2V3t9yl8L8o61tRIVKQ++lDhjlVmur/mbBN25/UNRpJllfpUH6oOaqvQAze4a
nRgyTnBwVBZkdJ0d1sivL9NZ4pKelJF3Ylw6rp0YMqV+cwkt/vRtzRJ31ZEeBhs7
vKh7F6BiGCHL5ZAwEUYe8O3akQwjgrMUcfuiFs4/sAeDMnmgN6Uq8DFEBXDpAxVN
sV/6Hockdfinx85RV2AUwJGfClcVcu4hMhOvKROpcH27xu9bBIeMuY0vvzP2VyOm
DoJeqU7qZjyCaUBkPimsz/1eRod6d4P5qxTj
-----END CERTIFICATE-----
EOF

Run the following command to use OpenSSL to validate the instance identity:

openssl smime -verify -in signature -inform PEM -content document -certfile cert.cer -noverify > /dev/null

If Verification successful is returned, the instance identity is validated.

Take note of the following parameters in the preceding command:

document: Set this parameter to the file that contains the instance identity document you obtained.
signature: Set this parameter to the file that contains the instance identity signature you obtained.
Note
If you configured the audience parameter in the instance identity signature, append the parameter in the "audience":"<Values of audience>" format to the end of the instance identity document. You can specify multiple values for the audience parameter. Separate the values with commas (,).

cert.cer: Set this parameter to the file that contains the Alibaba Cloud public certificate.

Code for the Alibaba Cloud public certificate:

Example 1: Use instance identities without configuring the audience parameter

This example shows how to use the identity of an instance that uses an Alibaba Cloud Marketplace image as an application software vendor.

Connect to a Linux instance.
For more information, see Connect to a Linux instance by using a password or key.
Run the following commands to use the metadata service to obtain the product code (product-code) and billing method (charge-type) of the image used by the Linux instance and check whether the image is from Alibaba Cloud Marketplace.
For more information, see Obtain instance metadata.
```
curl http://100.100.100.200/latest/meta-data/image/market-place/product-code
curl http://100.100.100.200/latest/meta-data/image/market-place/charge-type
```
Create a temporary file named cert.cer in the current directory and save the Alibaba Cloud public certificate to the file.

Validate the instance identity.

Sample script:

#!/usr/bin/bash
function verify_signature_without_audience(){
curl 100.100.100.200/latest/dynamic/instance-identity/document > document
echo "-----BEGIN CERTIFICATE-----" > signature
curl 100.100.100.200/latest/dynamic/instance-identity/pkcs7 >> signature
echo "" >> signature
echo "-----END CERTIFICATE-----" >> signature
openssl smime -verify -in signature -inform PEM -content document -certfile cert.cer -noverify > /dev/null
}
verify_signature_without_audience

If Verification successful is returned, the instance identity is validated and you are granted the permissions to manage application software.

Example 2: Use instance identities for which the audience parameter is configured

This example shows how to use the identity of an instance that uses an Alibaba Cloud Marketplace image as an application software vendor. You can configure the audience parameter to identify the instance and implement policy control on the application servers. This allows authenticated users to use software and protects the license codes from unauthorized use.

Connect to a Linux instance.
For more information, see Connect to a Linux instance by using a password or key.
Run the following commands to use the metadata service to obtain the product code (product-code) and billing method (charge-type) of the image used by the Linux instance and check whether the image is from Alibaba Cloud Marketplace.
For more information, see Obtain instance metadata.
```
curl http://100.100.100.200/latest/meta-data/image/market-place/product-code
curl http://100.100.100.200/latest/meta-data/image/market-place/charge-type
```
Create a temporary file named cert.cer in the current directory and save the Alibaba Cloud public certificate to the file.

Validate the instance identity.

Sample script:

#!/usr/bin/bash
function verify_signature_with_specified_audience(){
audience='your audience' #Configure the audience parameter.
document=$(curl 100.100.100.200/latest/dynamic/instance-identity/document)
audience_json=',"audience":''"'${audience}'"}'
echo -n ${document%?}${audience_json} > document
echo "-----BEGIN CERTIFICATE-----" > signature
curl 100.100.100.200/latest/dynamic/instance-identity/pkcs7?audience=${audience} >> signature
echo "" >> signature
echo "-----END CERTIFICATE-----" >> signature
openssl smime -verify -in signature -inform PEM -content document -certfile cert.cer -noverify > /dev/null
}
verify_signature_with_specified_audience

If Verification successful is returned, the instance identity is validated and you are granted the permissions to manage application software.

References

For information about how to obtain instance information from instance metadata, see Obtain instance metadata.
For information about how to use instance user data to automatically run commands or scripts on instance startup, see Instance user data.