API Gateway:Use digest authentication to call an API

Overview

API Gateway generates and verifies request signatures to:

• Validate that requests contain a correct signature based on the authorized AppKey.

• Prevent request tampering during transmission.

API providers create applications on the Apps page of the API Gateway console. Each application has a signature key pair (AppKey and AppSecret). After the provider authorizes an application to call an API, callers use the key pair to sign requests. The application can belong to either the provider or the caller.

When a client calls an API, it signs the request with the authorized key pair and adds the AppKey and signature to the request header. API Gateway reads the AppKey, retrieves the corresponding AppSecret, and recalculates the signature. If the calculated signature matches the client signature, the request is forwarded to the backend service. Otherwise, API Gateway returns an error.

API Gateway verifies signatures only for APIs with Security Authentication set to Alibaba Cloud App.

Call APIs with SDKs

API Gateway provides SDKs with built-in signature logic and source code for Java, Android, and Objective-C. Download them from the API Gateway console:

• Open API > SDKs

• Call API > Authorized API SDK

For more information, see Use SDKs to call APIs.

Digest authentication principles

3.1. Signature generation and verification

3.1.1. Prerequisites

The API caller has obtained the signature key pair for the target API.

• APP Key

• APP Secret

The Security Authentication of the target API is set to Alibaba Cloud App.

3.1.2. Signature generation on clients

To generate a signature:

1. Extract key data from the request to obtain a signature string.

2. Encrypt the signature string with AppSecret to produce a signature.

3. Add all signature-related headers to the HTTP request.

3.1.3. Signature verification on servers

To verify a client signature:

1. Extract key data from the request to build a signature string.

2. Read the AppKey from the request and retrieve the corresponding AppSecret.

3. Encrypt the signature string with the AppSecret to produce a signature.

4. Compare the server-side signature with the client-side signature from the request.

3.2. Signature generation and transfer

3.2.1. Extraction of a signature string

Extract key data from the HTTP request and combine it into a signature string in the following format:

HTTPMethod
Accept
Content-MD5
Content-Type
Date
Headers
PathAndParameters

These fields are separated by \n. If Headers is empty, omit its \n. For other empty fields, retain the \n. The signature is case-sensitive. Each field is extracted as follows:

• HTTPMethod: the HTTP method used to send the request (for example, POST). Must be uppercase.

• Accept: the value of the Accept header. Can be left empty, but we recommend that you set it explicitly. Some HTTP clients default to */*, which causes signature verification to fail.

• Content-MD5: the value of the Content-MD5 header. Optional.

  • Calculated only for requests with a non-Form body. If the client omits Content-MD5, API Gateway skips validation.

  • Java example for calculating Content-MD5:

String content-MD5 = Base64.encodeBase64(MD5(bodyStream.getbytes("UTF-8")));

• Content-Type: the value of the Content-Type header. Optional.

• Date: the value of the Date header. Optional.

• Headers: custom headers to include in the signature. Concatenation rules:

  • Sort header keys alphabetically and concatenate them as follows:

  HeaderKey1 + ":" + HeaderValue1 + "\n" +
  HeaderKey2 + ":" + HeaderValue2 + "\n" +
  ...
  HeaderKeyN + ":" + HeaderValueN + "\n"

  • If a header value is empty, use HeaderKey + ":" + "\n" and retain the key and colon (:).

  • Place the header keys used for signing in the X-Ca-Signature-Headers header, separated by commas (,).

  • The following headers cannot be used for signature calculation: X-Ca-Signature, X-Ca-Signature-Headers, Accept, Content-MD5, Content-Type, and Date.

• PathAndParameters: includes all Path, Query, and Form parameters.

  Path + "?" + Key1 + "=" + Value1 + "&" + Key2 + "=" + Value2 + ... "&" + KeyN + "=" + ValueN

  • Sort Query and Form parameter keys alphabetically, then concatenate them as shown above.

  • If Query and Form parameters are empty, use only the Path without appending a question mark (?).

  • If a parameter value is empty, use only the key for signing.

  • For array parameters with the same key but different values, only the first value is used for signing.

Example HTTP request:

POST /http2test/test?param1=test HTTP/1.1
host:api.aliyun.com
accept:application/json; charset=utf-8
ca_version:1
content-type:application/x-www-form-urlencoded; charset=utf-8
x-ca-timestamp:1525872629832
date:Wed, 09 May 2018 13:30:29 GMT+00:00
user-agent:ALIYUN-ANDROID-DEMO
x-ca-nonce:c9f15cbf-f4ac-4a6c-b54d-f51abf4b5b44
content-length:33
username=xiaoming&password=123456789

Generated signature string for this request:

POST
application/json; charset=utf-8
application/x-www-form-urlencoded; charset=utf-8
Wed, 09 May 2018 13:30:29 GMT+00:00
x-ca-key:203753385
x-ca-nonce:c9f15cbf-f4ac-4a6c-b54d-f51abf4b5b44
x-ca-signature-method:HmacSHA256
x-ca-timestamp:1525872629832
/http2test/test?param1=test&password=123456789&username=xiaoming

3.2.2. Signature calculation

After combining the key data into a signature string, encrypt and encode it to produce the final signature. Supported algorithms:

• HmacSHA256

• HmacSHA1

Encryption examples, where stringToSign is the signature string and appSecret is the AppSecret:

Mac hmacSha256 = Mac.getInstance("HmacSHA256");
byte[] appSecretBytes = appSecret.getBytes(Charset.forName("UTF-8"));
hmacSha256.init(new SecretKeySpec(appSecretBytes, 0, appSecretBytes.length, "HmacSHA256"));
byte[] md5Result = hmacSha256.doFinal(stringToSign.getBytes(Charset.forName("UTF-8")));
String signature = Base64.encodeBase64String(md5Result);

Mac hmacSha1 = Mac.getInstance("HmacSHA1");
byte[] appSecretBytes = appSecret.getBytes(Charset.forName("UTF-8"));
hmacSha1.init(new SecretKeySpec(appSecretBytes, 0, appSecretBytes.length, "HmacSHA1"));
byte[] md5Result = hmacSha1.doFinal(stringToSign.getBytes(Charset.forName("UTF-8")));
String signature = Base64.encodeBase64String(md5Result);

The StringToSign is decoded as a UTF-8 byte array, encrypted, and then Base64-encoded to produce the final signature.

3.2.3. Signature transfer

Include the following headers in requests sent to API Gateway:

• x-ca-key: the AppKey. This parameter is required.

• x-ca-signature-method: the signature method. This parameter is optional. Valid values: HmacSHA256 and HmacSHA1. Default value: HmacSHA256.

• X-Ca-Signature-Headers: the keys of all signature headers. This parameter is optional. Separate multiple keys with commas (,).

• X-Ca-Signature: the signature. This parameter is required.

Example signed HTTP request:

POST /http2test/test?param1=test HTTP/1.1
host:api.aliyun.com
accept:application/json; charset=utf-8
ca_version:1
content-type:application/x-www-form-urlencoded; charset=utf-8
x-ca-timestamp:1525872629832
date:Wed, 09 May 2018 13:30:29 GMT+00:00
user-agent:ALIYUN-ANDROID-DEMO
x-ca-nonce:c9f15cbf-f4ac-4a6c-b54d-f51abf4b5b44
x-ca-key:203753385
x-ca-signature-method:HmacSHA256
x-ca-signature-headers:x-ca-timestamp,x-ca-key,x-ca-nonce,x-ca-signature-method
x-ca-signature:xfX+bZxY2yl7EB/qdoDy9v/uscw3Nnj1pgoU+Bm6xdM=
content-length:33
username=xiaoming&password=123456789

3.3. Troubleshooting

If signature verification fails, API Gateway returns the server-side StringToSign in the X-Ca-Error-Message response header. Compare it with the client-side StringToSign to identify discrepancies.

If both strings match, verify the AppSecret used for signing.

HTTP headers do not support line breaks. Line breaks in the StringToSign are replaced with number signs (#).

errorMessage:  Invalid Signature, Server StringToSign:`GET#application/json##application/json##X-Ca-Key:200000#X-Ca-Timestamp:1589458000000#/app/v1/config/keys?keys=TEST`

Example server-side signature string:

GET
application/json
application/json
X-Ca-Key:200000
X-Ca-Timestamp:1589458000000
/app/v1/config/keys?keys=TEST