This topic describes instance identities and how to use instance identities. This topic also provides examples on how to use instance identities with or without custom parameters.
Background information
Instance identities
Instance identities are part of instance metadata that can be used to identify and differentiate instances and provide a basis for managing permissions on applications and activating software. Instance identities are generated in real time and dynamically change with instance information. For more information, see Overview of ECS instance metadata.
Each instance identity consists of an instance identity document (document) and an instance identity signature (signature).
Instance identity document
The instance identity document includes instance information that is described in the following table.
Item
Description
account-id
The ID of the Alibaba Cloud account to which the instance belongs.
instance-id
The instance ID.
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
The instance identity signature is a secure, reliable digital signature that is encrypted by using the PKCS #7 standard.
You can specify the
audience
parameter in an instance identity signature to prevent the signature from being spoofed. The value ofaudience
can be a random string, a timestamp, regularly changing data, or data generated by a specific algorithm. After you specify theaudience
parameter in an instance identity signature, it is difficult for others to guess the value ofaudience
even if they obtain information about the instance identity document and instance identity signature. You can use theaudience
parameter for authentication. For more information, see Example 2: Use instance identities with the audience parameter specified.
Scenarios
In the following scenarios, you can use instance identities (instance-identity
) for authentication, authorization, or identification of runtime environments.
Traditionally, each piece of 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. For more information, see Use instance identities.
When you write sensitive data to an 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 where you want to confirm the source of the instance.
Configure instance identities
This section describes how to configure instance identities. In this example, an instance that runs CentOS 7.4 is used.
OpenSSL is required to validate and use instance identities to ensure security. If you have not configured OpenSSL, go to the OpenSSL official 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.
Run the following command to obtain the instance identity document:
curl http://100.100.100.200/latest/dynamic/instance-identity/document
Use one of the following methods to obtain the instance identity signature:
Run the following command without the
audience
parameter:curl http://100.100.100.200/latest/dynamic/instance-identity/pkcs7
Run the following command with the
audience
parameter:curl http://100.100.100.200/latest/dynamic/instance-identity/pkcs7?audience=XXXX
NoteIn the preceding command, replace
XXXX
with an actual value. Example:audience=test
.
Run the following command to validate the instance identity by using OpenSSL:
openssl smime -verify -in $signature -inform PEM -content $DOCUMENT -certfile AliyunPubkey -noverify > /dev/null
Take note of the following parameters in the preceding command:
$signature: Set this parameter to the instance identity signature that you obtained.
$DOCUMENT: Set this parameter to the instance identity document that you obtained.
NoteIf you specified the
audience
parameter in the previous step, add the parameter in the"audience":"<Value of audience>"
format to the end of the instance identity document. You can add multiple audience parameters and separate the parameters with commas (,).AliyunPubkey: Set this parameter to the Alibaba Cloud public certificate.
Use instance identities
Example 1: Use instance identities without specifying the audience parameter
This example demonstrates how to use the identity of an instance that uses an Alibaba Cloud Marketplace image as an application software seller.
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 check whether the image used by the instance is from Alibaba Cloud Marketplace.
You can check the
product-code
andcharge-type
items in the metadata of the instance. The product-code item indicates the product code of the Alibaba Cloud Marketplace image. The charge-type item indicates the billing method of the Alibaba Cloud Marketplace image. For more information, see Overview of ECS 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.
Example 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 have the permissions to manage application software.
Example 2: Use instance identities with the audience parameter specified
This example also demonstrates how to use the identity of an instance that uses an Alibaba Cloud Marketplace image as an application software seller. You can specify the audience
parameter to identify the instance and implement policy control at the application server to allow authenticated users to use software. This can protect the license codes against 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 check whether the image used by the instance is from Alibaba Cloud Marketplace.
You can check the
product-code
andcharge-type
items in the metadata of the instance. The product-code item indicates the product code of the Alibaba Cloud Marketplace image. The charge-type item indicates the billing method of the Alibaba Cloud Marketplace image. For more information, see Overview of ECS 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.
Example script:
#!/usr/bin/bash function verify_signature_with_specified_audience(){ audience='your audience' #Specify 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 have the permissions to manage application software.