Updated on 2022-12-05 GMT+08:00

Creating a Frontend Custom Authorizer

Overview

If you need to use your own authentication system for API calling authentication, you can create a custom authorizer.

Custom authorizers are classified into the following types:

  • Frontend custom authorizer: ROMA Connect uses a custom authentication function to authenticating received API requests.
  • Backend custom authorizer: The backend service of an API uses a custom authentication function to authenticating backend service requests forwarded by ROMA Connect.

This section describes how to create a frontend custom authorizer. You need to create a function backend as the authentication function, and use the function backend as the authentication backend in custom authentication.

Creating a Function Backend for Frontend Authentication

  1. Log in to the ROMA Connect console. On the Instances page, click View Console next to a specific instance.
  2. In the navigation pane on the left, choose API Connect > Custom Backend. On the Backends tab page, click Create.
  3. On the Create Backend page, set backend parameters and click Create.
    • Backend Request Method must be set to POST.
    • You do not need to set input parameters. The function backend used for custom authentication will obtain the values of Header and Query parameters from API requests.
    • For details about the settings of other parameters, see Creating a Function API.

    After the backend is created, the online IDE page is automatically displayed.

  4. Develop a function backend.

    In the upper left corner of the online IDE, choose File > Create Function Backend > Blank Template. In the dialog box displayed, click Yes. Compile a function script for security authentication and click Save.

    The function script used for frontend custom authentication must meet the following conditions:

    • For the request parameters obtained using the function script:
      • Header parameter: indicates the identity source parameter in Header defined in custom authentication. The parameter value is transferred from the API request that uses the frontend custom authentication. The format of the invoked parameter in the function script is as follows: body["headers"]["Parameter name"].
      • Query parameter: indicates the identity source parameter in Query defined in custom authentication. The parameter value is transferred from the API request that uses the frontend custom authentication. The format of the invoked parameter in the function script is as follows: body["queryStringParameters"]["Parameter name"].
      • Body parameter: indicates the user data defined in custom authentication. The parameter value is set when the custom authentication is created. The format of the invoked parameter in the function script is as follows: body["user_data"].
    • For the response message defined by the function script:

      The response body cannot be greater than 1 MB. The response content must meet the following format:

      {
        "status": "allow/deny",
        "context": {
          "user": "abc"
        }
      }
      • status: identifies the authentication result. This field is mandatory. Only allow or deny is supported. allow indicates that the authentication is successful, and deny indicates that the authentication fails.
      • context: indicates the authentication response result. This field is mandatory. Only key-value pairs of the string type are supported. The key value does not support JSON objects or arrays.

        The data in the context is user-defined. After the authentication is successful, the data can be used as a system parameter (frontend authentication parameter) and mapped to the backend request parameter of the API. The system parameter name set in the API backend service must be the same as the parameter name in the context. The parameter name is case sensitive. The parameter name in context must start with a letter and contain 1 to 32 characters, including uppercase letters, lowercase letters, digits, underscores (_), and hyphens (-).

    The following is an example of the header parameter definition script:
    function execute(data){
      data=JSON.parse(data)
      body=data.body
      if(body["headers"]["test"]=='abc'){
        return{
          "status": "allow",
          "context": {
            "user": "abcd"
          }
        }
      }else{
        return{
          "status": "deny"
        }
      }
    }

    The following is an example of the query parameter definition script:

    function execute(data){
      data=JSON.parse(data)
      body=data.body
      if(body["queryStringParameters"]["test"]=='abc'){
        return{
          "status": "allow",
          "context": {
            "user": "abcd"
          }
        }
      }else{
        return{
          "status": "deny"
        }
      }
    }

    The following is an example of the user data definition script:

    function execute(data){
      data=JSON.parse(data)
      body=data.body
      if(body["user_data"]=='abc'){
        return{
          "status": "allow",
          "context": {
            "user": "abcd"
          }
        }
      }else{
        return{
          "status": "deny"
        }
      }
    }
  5. Test the function backend.

    In the upper right corner of the page, click Test. In the Test Parameters area, add request parameters required for authentication based on the definition of the function backend and click Test to send the request.

    The user data definition script example in the preceding step is used as an example. You need to enter the request content {"user_data": "abc"} in the Body parameter as the authentication parameter of the backend request.

    If the value of status in the test result is allow, the test is successful.

  6. Deploy the function backend.

    After the backend test is complete, click Deploy in the upper right corner of the page. In the dialog box displayed, click Yes to deploy the function backend.

Creating a Frontend Custom Authorizer

Before creating a frontend custom authorizer, ensure that the function backend used for frontend custom authentication has been created. Otherwise, create a function backend first. For details, see Creating a Function Backend for Frontend Authentication.

  1. Log in to the ROMA Connect console. On the Instances page, click View Console next to a specific instance.
  2. In the navigation pane on the left, choose API Connect > API Management. On the Custom Authorizers tab page, click Create.
  3. In the Create Custom Authorizer dialog box, configure custom authorizer information and click Create.
    Table 1 Parameters for creating a frontend custom authorizer

    Parameter

    Description

    Name

    Enter a custom authorizer name. It is recommended that you enter a name based on naming rules to facilitate search.

    Type

    Select Frontend.

    Integration Application

    Select the integration application to which the custom authorizer belongs.

    Function URN

    Select the function backend used for frontend custom authentication. Only function backends in the Deployed state can be selected.

    Identity Sources

    Add request parameters used for authentication. The Header and Query parameters can be added.

    If the value of Cache Duration is not 0, a request parameter must be added. When the authentication result is cached, this parameter is used as the cache index of the authentication result.

    Cache Duration (s)

    Enter the cache time of the authentication result. If it is set to 0, the authentication result is not cached. The maximum cache duration can be set to 3600 seconds.

    Send Request Body

    Determine whether to send the API request body to the authentication function.

    User Data

    Enter the user-defined authentication request parameter, which is used together with Identity Sources as the authentication request parameter.