The STS service authenticates the sender identity of each access request. Therefore, each request must contain signature information, regardless of whether the request is sent over HTTP or HTTPS.

Background information

STS implements symmetric encryption with an AccessKey pair to verify the identity of the request sender. An AccessKey pair is an identity credential issued to Alibaba Cloud accounts and RAM users. An AccessKey pair consists of an AccessKey ID and an AccessKey secret. The AccessKey ID is used to verify the identity of the user, while the AccessKey secret is used to encrypt and verify the signature string. You must keep your AccessKey secret strictly confidential.

Procedure

  1. Compose and encode a string-to-sign.
    1. Create a canonicalized query string by arranging the request parameters (including all Common parameters and API-specific parameters except Signature) in alphabetical order.
      Note If you use the GET method to send a request, the request parameters are included as a part of the request URL. The first parameter follows the question mark (?) in the URL and the other parameters follow an ampersand (&).
    2. Encode the canonicalized query string in UTF-8. Follow these encoding rules to encode the name and value of each request parameter:
      • Uppercase letters, lowercase letters, digits, and some special characters such as ampersands (&), hyphens (-), underscores (_), periods (.), and tildes (~) do not need to be encoded.
      • Other characters must be percent encoded in %XY format. XY represents the ASCII code of the characters in hexadecimal notation. For example, double quotation marks (") are encoded as %22.
      • Spaces must be encoded as %20. Do not encode spaces as plus signs (+).
      Note Generally, libraries that support URL encoding, such as Java java.net.URLEncoder, encode characters according to the rules for the application/x-www-form-urlencoded MIME type. If this encoding method is used, replace the plus signs (+) in the encoded strings with %20, the asterisks (*) with %2A, and %7E with a tilde (~) to comply with the preceding encoding rules.
    3. Connect each encoded parameter name and value with an equal sign (=).
    4. Concatenate the encoded parameters with ampersands (&).
      Note For more information about the sequence of parameters, see Step 1.
  2. Create a string-to-sign from the encoded canonicalized query string. The steps to create a string-to-sign are as follows:
    StringToSign=
    HTTPMethod + "&" + //HTTPMethod: HTTP method used to make the request, such as GET.
    percentEncode("/") + "&" + //percentEncode("/"): Encode backslashes (/) as %2F.
    percentEncode(CanonicalizedQueryString) //Encode the canonicalized query string created in Step 1.
  3. Calculate the HMAC value of the string-to-sign according to RFC 2104.
    Note Use the SHA1 algorithm to calculate the HMAC value of the StringToSign. The AccessKey secret and an ampersand (&) are used as the key for the HMAC calculation. The ASCII code for the ampersand (&) is 38.
  4. Encode the HMAC value in Base64 to obtain the signature string.
  5. Add the signature string to the request as the Signature parameter.
    Note Before the signature string is added to the request as the Signature parameter, the string must be URL-encoded according to RFC 3986.

Result

The AssumeRole API operation is used as an example to introduce the signature method.

In this example, the request URL before the request is signed is as follows:

https://sts.aliyuncs.com/?SignatureVersion=1.0&Format=JSON&Timestamp=2015-09-01T05%3A57%3A34Z&RoleArn=acs%3Aram%3A%3A1234567890123%3Arole%2Ffirstrole&RoleSessionName=client&AccessKeyId=testid&SignatureMethod=HMAC-SHA1&Version=2015-04-01&Action=AssumeRole&SignatureNonce=571f8fb8-506e-11e5-8e12-b8e8563dc8d2

The corresponding StringToSign is as follows:

GET&%2F&AccessKeyId%3Dtestid%26Action%3DAssumeRole%26Format%3DJSON%26RoleArn%3Dacs%253Aram%253A%253A1234567890123%253Arole%252Ffirstrole%26RoleSessionName%3Dclient%26SignatureMethod%3DHMAC-SHA1%26SignatureNonce%3D571f8fb8-506e-11e5-8e12-b8e8563dc8d2%26SignatureVersion%3D1.0%26Timestamp%3D2015-09-01T05%253A57%253A34Z%26Version%3D2015-04-01

If the AccessKey ID is testid and the AccessKey secret is testsecret, testsecret& is the key used for calculating the HMAC value of the string-to-sign.

The result signature string is gNI7b0AyKZHxDgjBGPDgJ1Ce3L4=.

In this example, the request URL after the request is signed is as follows:

https://sts.aliyuncs.com/?SignatureVersion=1.0&Format=JSON&Timestamp=2015-09-01T05%3A57%3A34Z&RoleArn=acs%3Aram%3A%3A1234567890123%3Arole%2Ffirstrole&RoleSessionName=client&AccessKeyId=testid&SignatureMethod=HMAC-SHA1&Version=2015-04-01&Signature=gNI7b0AyKZHxDgjBGPDgJ1Ce3L4%3D&Action=AssumeRole&SignatureNonce=571f8fb8-506e-11e5-8e12-b8e8563dc8d2