API Gateway:Backend signature plugin

1. What is a backend signature

A Backend Signature (formerly known as a Signature Key) is a Key and Secret pair that you create. This pair functions as a credential that you issue to the gateway. When the gateway sends a request to your backend service, it calculates a signature and passes it with the request. Your backend service can then perform a symmetric calculation on the corresponding string to verify the gateway's identity. If your backend service is in a VPC and connects to the gateway over a private network, such as for APIs in a dedicated VPC environment, a backend signature is not required because the channel is secure.

The original signature key feature is now merged into the plugin system. The existing console interface and APIs are still available. The original signature key feature and the backend signature plugin are the same type of plugin and are subject to the same attachment restrictions.

Changes made using the API or console for the original signature key feature are synchronized with the plugin system. However, remote sync is not supported.

2. Plugin attachment

After you attach a key to an API, the gateway includes signature information in all requests for that API that are sent to the backend service. Your backend must perform a symmetric calculation to validate the signature and authenticate the gateway's identity.

To replace the key for an API, you can directly modify the key and secret in the plugin. The changes take effect immediately for all attached APIs.

3. Plugin configuration

You can configure the plugin using either JSON or YAML format. Both formats use the same schema, and you can use a YAML-to-JSON converter to switch between them. The following code block shows a template in YAML format:

---
type: APIGW_BACKEND
key: SampleKey
secret: SampleSecret
isGenerateContentSha256Header: false   # (Optional) Specifies whether to add "x-ca-signed-payload" from the client request to the signature header. Default: false.                   

4. Read the API Gateway signature

The signature calculated by the gateway is stored in the `X-Ca-Proxy-Signature` request header.

5. Backend signature rules

For a detailed Java demo of the signature calculation, see the sample code at https://github.com/aliyun/api-gateway-demo-sign-backend-java.

The signature calculation procedure is as follows:

1. API Gateway extracts specific data from the HTTP request sent to the backend and combines this data into a string to sign. The format of the string to sign is as follows:

   HTTPMethod
   Content-MD5
   Headers
   PathAndParameters

   These four fields make up the string to sign and are separated by line feeds (`\n`). You must include the line feed separator even for empty fields, with one exception: if the `Headers` field is empty, do not add a line feed after it. The signature is case-sensitive. The rules for extracting each field are described below:

   • `HTTPMethod`: The HTTP method in uppercase, such as `POST`.

   • `Content-MD5`: The gateway reads the value of the `Content-MD5` header from the client request. If the client does not send this header, the `Content-MD5` value in the string to sign is empty. The client must calculate and send the `Content-MD5` header only when the request has a body that is not form-encoded. The following Java code shows how to calculate the `Content-MD5` value:

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

   • `Headers`: This field contains all header keys and values that are part of the signature calculation. The keys of the headers to include in the signature are read from the `X-Ca-Proxy-Signature-Headers` request header, where multiple keys are separated by commas. To construct this part of the string, first sort all header keys included in the signature calculation alphabetically. Then, convert the header keys to lowercase and concatenate the keys and values as follows:

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

   • PathAndParameters

     This field includes the path and all parameters from the query and form. To construct this string, append a `?` to the path if there are any query or form parameters. Then, sort the keys of all query and form parameters alphabetically and concatenate them as shown below. If there are no query or form parameters, `PathAndParameters` is just the path.

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

     Note

     A query or form parameter can have multiple values. If a parameter has multiple values, only the first value is used in the signature calculation. If a parameter is present, the equals sign (`=`) must be included in the string to sign, even if the value is empty. For example, if the query string is `path?a=&b`, it must be written as `path?a=&b=` for the signature calculation.

2. Calculate the signature:

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

   The final signature is generated by encoding the string to be signed (StringToSign) into a byte array using UTF-8, encrypting the resulting byte array with an encryption algorithm, and then encoding the encrypted result using the Base64 algorithm.

6. Debug mode

To simplify backend signature integration and testing, you can enable debug mode by adding the `X-Ca-Request-Mode: debug` header to your request to API Gateway.

Your backend service can then read the `X-Ca-Proxy-Signature-String-To-Sign` header. In this header, line feed characters are replaced with `#` because line feeds are not allowed in HTTP headers.

7. Timestamp validation

If your backend needs to perform timestamp validation, you can select the `CaRequestHandleTime` system parameter in the API definition. This parameter provides the UTC time when the gateway received the request.