更新时间:2023-03-01 GMT+08:00

创建前端自定义认证

概述

如果您需要把自己的认证系统用于API调用的认证鉴权,可以使用自定义认证来实现。

自定义认证包括前端和后端两种类型:

  • 前端自定义认证:指ROMA Connect使用自定义的认证函数,对收到的API请求进行安全认证。
  • 后端自定义认证:指API的后端服务使用自定义的认证函数,对来自ROMA Connect转发的后端服务请求进行安全认证。

本章节主要介绍如何创建一个前端自定义认证。您需要先创建一个函数后端作为认证函数,并在自定义认证中使用该函数后端作为认证后端。

创建用于前端认证的函数后端

  1. 登录ROMA Connect控制台,在“实例”页面单击实例上的“查看控制台”,进入实例控制台。
  2. 在左侧的导航栏选择“服务集成 APIC > 自定义后端”,在“后端列表”页签中单击“创建后端”。
  3. 在创建后端页面配置后端信息,完成后单击“立即创建”。
    • “后端请求方法”必须为“POST”。
    • 入参无需设置,用于自定义认证的函数后端会获取API请求中的Header和Query参数。
    • 其他参数请参考创建函数API进行设置。

    后端创建完成后,页面自动跳转到该后端的编辑器页面。

  4. 开发函数后端的功能实现。

    在编辑器的左上角单击“文件 > 新建函数后端 > 空白模板”,在弹窗中单击“确定”,然后编写用于安全认证的函数脚本,完成后单击“保存”。

    用于前端自定义认证的函数脚本应满足如下条件:

    • 函数脚本支持获取的请求参数:
      • Header参数:自定义认证中定义的Header位置的身份来源参数,参数值从使用该前端自定义认证的API请求中传入。函数脚本中调用参数的格式为:body["headers"]["参数名"]。
      • Query参数:自定义认证中定义的Query位置的身份来源参数,参数值从使用该前端自定义认证的API请求中传入。函数脚本中调用参数的格式为:body["queryStringParameters"]["参数名"]。
      • Body参数:自定义认证中定义的用户数据,参数值在创建自定义认证时设置。函数脚本中调用参数的格式为:body["user_data"]。

      在前端自定义认证过程中,API请求的Header和Query参数会被放到后端请求Body体的headers和queryStringParameters参数中,并传递给认证函数。因此函数脚本中需要调用Header和Query参数时,需要从后端请求的Body体中获取。headers和queryStringParameters参数在后端请求Body体中的示例请参见测试步骤的示例

    • 函数脚本定义的响应消息:

      响应消息体不能大于1M,响应内容必须满足如下格式:

      {
        "status": "allow/deny",
        "context": {
          "user": "abc"
        }
      }
      • status:必选字段,用于标识认证结果。只支持“allow”或“deny”,“allow”表示认证成功,“deny”表示认证失败。
      • context:必选字段,为认证的响应结果。只支持字符串类型键值对,键值不支持JSON对象或数组。

        context中的数据为您自定义的字段,认证通过后可作为系统参数(前端认证参数)映射到API的后端服务请求参数中。其中API后端服务中填写的“系统参数名称”与context中的参数名称必须完全一致,且区分大小写。context中的参数名称必须以英文字母开头,支持英文大小写字母、数字、下划线和中划线,且长度为1-32个字符。

    Header参数定义脚本示例
    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"
        }
      }
    }

    Query参数定义脚本示例

    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"
        }
      }
    }

    Body参数定义脚本示例

    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. 测试函数后端的功能。

    在页面右上角单击“测试”,在下方的“测试参数”处,根据函数后端中的脚本定义,增加认证所需的请求参数,然后单击“立即测试”,发送请求。当测试结果返回的status值为“allow”时,表示测试成功。

    “测试参数”处填写的是后端请求参数,Header、Query和Body认证参数均需要填写在后端请求的Body参数中,以上一步的脚本示例为例,各认证参数的填写示例如下:

    • Header参数
      {
        "headers":{
          "test":"abc"
        }
      }
    • Query参数
      {
        "queryStringParameters":{
          "test":"abc"
        }
      }
    • Body参数
      {
        "user_data": "abc"
      }
  6. 部署函数后端。

    后端测试完成后,在页面右上角单击“部署”,在确认弹窗中单击“立即部署”,部署函数后端。

创建前端自定义认证

在创建前端自定义认证前,请确保已有用于前端自定义认证的函数后端,否则请提前创建用于前端认证的函数后端

  1. 登录ROMA Connect控制台,在“实例”页面单击实例上的“查看控制台”,进入实例控制台。
  2. 在左侧的导航栏选择“服务集成 APIC > API管理”,在“自定义认证”页签中单击“创建自定义认证”。
  3. 在创建自定义认证弹窗中配置前端自定义认证信息,完成后单击“创建”。
    表1 前端自定义认证配置

    参数

    配置说明

    认证名称

    填写自定义认证的名称,根据规划自定义。建议您按照一定的命名规则填写自定义认证名称,方便您快速识别和查找。

    类型

    创建前端自定义认证时,选择“前端”。

    集成应用

    选择自定义认证所属的集成应用。

    函数地址

    选择用于前端自定义认证的函数后端,仅可以选择状态为“已部署”的函数后端。

    身份来源

    添加用于认证的请求参数,支持添加Header参数和Query参数。

    当“缓存时间”不为0时,必须添加请求参数。当缓存认证结果时,此参数将作为认证结果的缓存索引。

    缓存时间

    填写认证结果的缓存时间。值为0时代表不缓存,最大支持3600秒。

    是否发送body

    是否把API请求的body信息发送给认证函数。

    用户数据

    自定义的认证请求参数,与“身份来源”一同作为认证请求参数。