# 创建API的前端自定义认证（可选）
如果您需要把自己的认证系统用于API调用的认证鉴权，可以使用自定义认证来实现。
自定义认证包括前端和后端两种类型：
- 前端自定义认证：指ROMA Connect使用自定义的认证函数，对收到的API请求进行安全认证。
- 后端自定义认证：指API的后端服务使用自定义的认证函数，对来自ROMA Connect转发的后端服务请求进行安全认证。
本章节主要介绍如何创建一个前端自定义认证。您需要先创建一个函数后端作为认证函数，并在自定义认证中使用该函数后端作为认证后端。
 #### 创建用于前端认证的函数后端
1. 登录[ROMA Connect控制台](https://console.huaweicloud.com/roma3)，在左侧导航栏选择"资源管理"，在实例页面单击实例，进入实例控制台。
2. 在左侧的导航栏选择"服务集成 APIC \> 自定义后端"，在"后端列表"页签中单击"创建后端"。
3. 在创建后端页面配置后端信息，完成后单击"立即创建"。
   - "后端请求方法"必须为"POST"。
   
   - 入参无需设置，用于自定义认证的函数后端会获取API请求中的Header和Query参数。
   
   - 其他参数请参考[创建函数后端](https://support.huaweicloud.com/usermanual-roma/roma_03_2112.html)进行设置。
   
   
   后端创建完成后，页面自动跳转到该后端的编辑器页面，后端类型默认为数据后端。
   
4. 开发函数后端的功能实现。 在编辑器的左上角单击"文件 \> 新建函数后端 \> 空白模板"，在弹窗中单击"确定"，然后编写用于安全认证的函数脚本，完成后单击"保存"。
   用于前端自定义认证的函数脚本应满足如下条件：
   - 函数脚本支持获取的请求参数：
     - Header参数：自定义认证中定义的Header位置的身份来源参数，参数值从使用该前端自定义认证的API请求中传入。函数脚本中调用参数的格式为：body\["headers"\]\["参数名"\]。
     
     - Query参数：自定义认证中定义的Query位置的身份来源参数，参数值从使用该前端自定义认证的API请求中传入。函数脚本中调用参数的格式为：body\["queryStringParameters"\]\["参数名"\]。
     
     - Body参数：自定义认证中定义的用户数据，参数值在创建自定义认证时设置。函数脚本中调用参数的格式为：body\["user_data"\]。
     
     
     ![](https://support.huaweicloud.com/usermanual-roma/public_sys-resources/note_3.0-zh-cn.png)
     在前端自定义认证过程中，API请求的Header和Query参数会被放到后端请求Body体的headers和queryStringParameters参数中，并传递给认证函数。因此函数脚本中需要调用Header和Query参数时，需要从后端请求的Body体中获取。headers和queryStringParameters参数在后端请求Body体中的示例请参见[测试步骤的示例]。
     
   
   - 函数脚本定义的响应消息： 响应消息体不能大于1MB，响应内容必须满足如下格式：
     ```
     {
       "status": "allow/deny",
       "context": {
         "user": "abc"
       }
     }
     ```
     - status：必选字段，用于标识认证结果。只支持"allow"或"deny"，"allow"表示认证成功，"deny"表示认证失败。
     
     - context：必选字段，为认证的响应结果。只支持字符串类型键值对，键值不支持JSON对象或数组。 context中的数据为您自定义的字段，认证通过后可作为[系统参数](https://support.huaweicloud.com/usermanual-roma/roma_03_2105.html#roma_03_2105__li178566536139)（前端认证参数）映射到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. 在实例控制台左侧的导航栏选择"服务集成 APIC \> API策略"，在"自定义认证"页签下单击"创建自定义认证"。
2. 在创建自定义认证弹窗中配置前端自定义认证信息，完成后单击"确定"。
   表1前端自定义认证配置 
   | 参数       | 说明                                                                                                            |
   |:---|:---|
   | 认证名称     | 填写自定义认证的名称，根据规划自定义。建议您按照一定的命名规则填写自定义认证名称，方便您快速识别和查找。                                                          |
   | 集成应用     | 选择自定义认证所属的集成应用。                                                                                               |
   | 类型       | 创建前端自定义认证时，选择"前端"。                                                                                            |
   | 函数地址     | 选择用于前端自定义认证的函数后端，仅可以选择状态为"已部署"的函数后端。                                                                          |
   | 缓存时间(秒)  | 填写认证结果的缓存时间。值为0时代表不缓存，最大支持3600秒。                                                                              |
   | 宽松模式     | 开启后，当自定义函数服务不可用（与自定义函数服务建立连接失败或者自定义函数服务返回5xx响应）时，ROMA Connect仍然接受客户端请求。                                       |
   | 身份来源     | 添加用于认证的请求参数，支持添加Header参数和Query参数。 当"缓存时间"不为0时，必须添加请求参数。当缓存认证结果时，此参数将作为认证结果的缓存索引。 |
   | 是否发送body | 是否把API请求的Body信息发送给认证函数。                                                                                       |
   | 用户数据     | 自定义的认证请求参数，与"身份来源"一同作为认证请求参数。                                                                                 |
      
   
3. 在自定义认证列表中查看创建的自定义认证，存在则表示认证创建成功。
 
#### 相关文档
自定义认证创建完成后，您可以创建自定义认证类型的API。具体操作，请参考[创建API](https://support.huaweicloud.com/usermanual-roma/roma_03_2105.html)章节。