A backend signature (formerly known as a signature key) is a key-secret pair that you create and issue to API Gateway. It works in a way similar to an account and password pair. After a backend signature plug-in is bound with an API, API Gateway uses the key-secret pair to sign requests designated for your backend service. Your backend service also performs symmetric encryption on the received requests. API Gateway passes authentication if the signature on API Gateway is consistent with that on the backend service.

1. What is a backend signature?

A backend signature (formerly known as a signature key) is a key-secret pair that you create and issue to API Gateway. It works in a way similar to an account and password pair. When API Gateway sends a request to your backend service, API Gateway uses the backend signature to calculate a signature string and pass it to your backend service. Your backend service obtains the signature string and authenticates API Gateway by using symmetric calculation. If your backend service accesses API Gateway over a VPC, you do not need to use backend signatures because the transmission channel is secure.

The original signature key feature has been integrated into the plug-in system. The original signature key interface and console are still in use. The original signature key feature and the backend signature plug-in are of the same plug-in type and are subject to the binding limits of that type.

When you create or modify keys in the original signature key interface or console, the data modifications are synchronized to the plug-in system. However, the modifications you make in the plug-in system cannot be synchronized to the original signature key interface or console.

2. Plug-in binding

After you bind a key to an API, API Gateway contains signature information in all the requests sent to your backend service. The backend service performs symmetric calculation to parse the signature information and authenticate API Gateway.

If you want to replace the key bound to an API, modify the key and secret in the backend signature plug-in that is bound to the API. The new key takes effect immediately after it is bound to the API.

3. Plug-in configurations

You can configure backend signature plug-ins in JSON or YAML format because these two formats use the same schema. You can use the yaml to json tool to convert the configuration format of a backend signature plug-in. The following example describes a plug-in configuration template in YAML format:

---
type: APIGW_BACKEND
key: SampleKey
secret: SampleSecret
			

4. Storage of the backend signatures of API Gateway

Save the signature information calculated by API Gateway into the X-Ca-Proxy-Signature header of a request.

5. Backend signature rules

For more information about the JAVA demo for signature calculation, visit https://github.com/aliyun/api-gateway-demo-sign-backend-java.

Follow these steps to perform signature calculation:

  1. API Gateway extracts key data from the HTTP requests that are sent to your backend service and combines the data into a signature string. The generated signature string is in the following format:

    HTTPMethod
    Content-MD5
    Headers
    PathAndParameters

    The preceding four fields constitute an entire signature string and are separated with \n. If the Headers field is left empty, \n is not required. If the other fields are left empty, \n must be retained. The name of the signature string is case-sensitive. The following content describes the data extraction rules for each field:

    • HTTPMethod: the HTTP method used to send a request, such as POST. The field value is in uppercase.
    • Content-MD5: the value of the Content-MD5 header in a request. This field can be left empty. The value is calculated only when a request contains a body of a non-Form type. The following example is used to calculate the value of the Content-MD5 header in Java format:

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

    • Headers: specifies the keys and values of all headers involved in signature calculation. You can read the keys named X-Ca-Proxy-Signature-Headers from the headers of requests. The keys are separated with commas (,). The keys involved in signature calculation are sorted in alphabetical order, converted into lowercase letters, and then combined based on the following rules:

    String headers = HeaderKey1.toLowerCase() + ":" + HeaderValue1 +"\n"+
     HeaderKey2.toLowerCase() + ":" + HeaderValue2 +"\n"+
     ... +
    HeaderKeyN.toLowerCase() + ":" + HeaderValueN + "\n"

    • PathAndParameters

    This field contains all the path, query, and form parameters. To form a signature string with query and form parameters, add a question mark (?), sort the keys of the query and form parameters in alphabetical order, and combine the keys based on the following rules. If the signature is not formed with query or form parameters, set PathAndParameters to Path.

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

    Note: A query or form parameter may have multiple values. Only the first value is used for signature calculation. The equal sign (=) in the signature calculation process must be retained for the parameters that have been transferred. For example, "path?a=&b" must be written as "path?a=&b=" in the request signature process.

  2. Calculate a signature.

Mac hmacSha256 = Mac.getInstance("HmacSHA256");
byte[] keyBytes = secret.getBytes("UTF-8");  //The secret value is the secret of the signature key bound to the API.
hmacSha256.init(new SecretKeySpec(keyBytes, 0, keyBytes.length, "HmacSHA256"));
String sign = new String(Base64.encodeBase64(Sha256.doFinal(stringToSign.getBytes("UTF-8")),"UTF-8"));

Decode stringToSign by using UTF-8 to obtain a Byte array. Then use an encryption algorithm to encrypt the Byte array, and Base64 encode the encrypted Byte array to form a final signature.

6. Debug mode

To access and debug a backend signature efficiently, you can enable the Debug mode. The debugging procedure is to add X-Ca-Request-Mode = debug to the header of a request that is sent to API Gateway.

The backend service reads X-Ca-Proxy-Signature-String-To-Sign from the header of a request. Line breaks are not allowed in the value of an HTTP request header and are replaced with vertical bars (|).

Note: X-Ca-Proxy-Signature-String-To-Sign is not involved in backend signature calculation.

7. Timestamp verification

If your backend service needs to verify the timestamp of a request, set CaRequestHandleTime to the Greenwich Mean Time (GMT) when API Gateway receives the request.