tencent cloud

Overview

If the verification and authentication method provided by API Gateway cannot meet your requirements, you can use the custom authentication plugin with custom code.

The custom verification plugin applies during the request process. API Gateway will forward the request to the verification function after receiving it from the client. You can deploy the verification function in SCF, on the public network, or in a VPC. Then, the request will be forwarded to the service backend only if it passes the verification; otherwise, the request will be denied.

Prerequisites

For verification services deployed in SCF, you need to enable the SCF service.

Directions

Step 1. Create a verification function

For verification functions deployed on the public network or in a VPC, you can skip this step.

1. Log in to the SCF console.
2. Click Functions on the left sidebar to enter the function list page.
3. Click Create at the upper-left corner of the page to create a verification SCF.

Step 2. Create a custom verification plugin

1. Log in to the API Gateway console.

2. On the left sidebar, click Plugin > Custom Plugin to enter the custom plugin list page.

3. Click Create in the top-left corner of the page to create a custom verification plugin.

   • For verification services deployed in SCF, you need to enter the following data when creating the custom verification plugin:

     Parameter	Required	Description
     Function	Yes	Select the namespace, name, and version of the verification function.
     Backend timeout	Yes	Set the backend timeout that API Gateway forwards the request to the verification function. The maximum time limit is 30 minutes. When no response is returned before the timeout after API Gateway calls the function, API Gateway will end the call and return an error message.
     Whether to send the Body	Yes	When the value is `Yes`, the Header, Body, and Query requested by the client will be sent to the function. When the value is `No`, the requested Body will not be sent.
     Verification Parameters	No	Set the request parameters for verification. When **Cache Period** is not `0`, this parameter must be set. When caching is enabled, the verification result will be queried with this parameter as the search criterion.
     Cache Period	Yes	Set the cache validity period for the verification result. `0` indicates that caching is not enabled. The cache validity period can be up to 3,600 seconds.

   • For verification services deployed on the public network, you need to enter the following data when creating the custom verification plugin:

     Parameter	Required	Description
     Request method	Yes	Request method of the custom verification function, which can be GET, POST, PUT, DELETE, HEAD, and ANY.
     Public network service	Yes	Access address of the custom verification service, which can be an HTTP or HTTPS address.
     Path match mode	Yes	It can be backend path or full path match. Backend path match: The configured path is used to request the service. Full path match: The overlapping part is used to request the service. For example, if the configured API path is `/a/` and the request path is `/a/b`, then the path transferred to the service will be `/b` after full path match is enabled.

   • For verification services deployed in a VPC, you need to enter the following data when creating the custom verification plugin:

     Parameter	Required	Description
     VPC	Yes	Select the VPC of the verification service.
     Request method	Yes	Request method of the custom verification function, which can be GET, POST, PUT, DELETE, HEAD, and ANY.
     Backend address	Yes	Access address of the custom verification service, which can be an HTTP or HTTPS address.

Step 3. Bind the API

1. Select the just created plugin in the list and click Bind API in the Operation column.
2. In the Bind API pop-up window, select the service, environment, and the target API.
3. Click OK to bind the plugin to the API. At this time, the configuration of the plugin has taken effect for the API.

pluginData

{
  "cache_time":10,   // Verification result caching duration in seconds. Value range: 0–3600
  "endpoint_timeout":15, // Backend timeout period in seconds. Value range: 0–60
  "func_name":"test_name", // Custom SCF name
  "func_namespace":"test_namespace", // Custom SCF namespace
  "func_qualifier":"$LATEST", // Custom SCF version
  "is_send_body":true, // Whether to send the request Body to the SCF
  "header_auth_parameters":[ // Verification parameter in Header location. The plugin caches the verification result based on the parameter value
      "Header1"
  ],
  "query_auth_parameters":[ // Verification parameter in Query location. The plugin caches the verification result based on the parameter value
      "Query1"
  ],
  "user_id":1253970226, // appid
  "version":"2021-12-26 17:17:49" // Plugin version in the format of `yyyy-MM-dd HH:mm:ss`. When you edit the plugin, the new value passed in will invalidate the result cached in the plugin
}

Notes

• When you enable caching and configure the verification parameter, the API Gateway will conduct parameter verification. If the request does not transfer the verification parameter, the API Gateway will report an error message "xxx parameter is missing". The values are case insensitive for parameter verification and cache hitting conducted by the API Gateway.
• Binding a custom plugin to the API means creating a trigger for the SCF to trigger the API. Deleting the trigger on the SCF side means unbinding the plugin from the API.
• For now, the custom verification plugin only supports event-triggered function and does not support HTTP-triggered function.
• The custom verification plugin can coexist with the verification method provided by the API Gateway. The latter takes priority. We recommend that you set the API where the custom verification plugin bound to "free from verification".