# 配置API的后端自定义认证
如果您需要把自己的认证系统用于API调用的认证鉴权，可以使用自定义认证来实现。
- 前端自定义认证：指APIG使用自定义的认证函数，对收到的API请求进行安全认证。
- 后端自定义认证：指API的后端服务使用自定义的认证函数，对来自APIG转发的后端服务请求进行安全认证。
本章节主要介绍如何创建一个后端自定义认证。您需要先创建一个函数后端作为认证函数，并在自定义认证中使用该函数后端作为认证后端。
图1后端自定义认证示意图   
![](https://support.huaweicloud.com/usermanual-apig/zh-cn_image_0000002076520558.png "点击放大")
使用自定义认证调用API的流程如下图所示：
图2使用自定义认证调用API   
![](https://support.huaweicloud.com/usermanual-apig/zh-cn_image_0000002112004973.png "点击放大")
#### 费用说明
函数计费详情请参考[函数工作流计费说明](https://support.huaweicloud.com/price-functiongraph/functiongraph_00_0003.html)。
#### 约束与限制
自定义认证依赖函数服务。如果当前Region没有上线函数服务，则不支持使用自定义认证。
 #### 创建用于后端自定义认证的函数
1. 进入[FunctionGraph控制台](https://console.huaweicloud.com/functiongraph/#/serverless/dashboard)。
2. 在左侧导航栏中选择"函数 \> 函数列表"。
3. 单击"创建函数"，根据下表参数说明，创建一个函数。 
   表1配置函数 
   | 参数     | 说明                                                                                                 |
   |:---|:---|
   | 选择创建方式 | 默认"创建空白函数"。                                                                                        |
   | 函数类型   | 选择函数的类型，此处默认"事件函数"。                                                                                |
   | 区域     | 选择与API网关相同区域。                                                                                      |
   | 项目     | 华为云的区域默认对应一个项目，这个项目由系统预置，用来隔离物理区域间的资源（计算资源、存储资源和网络资源），以默认项目为单位进行授权，用户可以访问您账号中该区域的所有资源。此处默认为已选择的区域。 |
   | 函数名称   | 根据规划自定义名称。建议您按照一定的命名规则填写名称，方便您快速识别和查找。                                                             |
   | 企业项目   | 企业项目是项目的升级版，针对企业不同项目间资源的分组和管理，是逻辑隔离。此处默认"default"。                                                 |
   | 委托     | 用户委托函数工作流去访问其他的云服务。此处选择"未使用任何委托"。                                                                  |
   | 运行时    | 此处以Python2.7语言为例。                                                                                  |
      
   
   
4. 单击"创建函数"。
5. 函数创建完成后，进入函数详情。 
   函数代码需要满足如下条件：
   - 函数代码只支持您自定义的用户数据，且格式为：event\["user_data"\]。
   
   - 函数代码获取的请求参数与API网关自定义认证中的参数关系为：函数请求参数中的自定义用户数据对应API网关自定义认证中的用户数据，参数值在您创建API网关自定义认证时输入，用户数据格式不限制，您可以自行指定。
   
   - 函数的返回值不能大于1M，必须满足如下格式：
     ```
     {
         "statusCode":200,
         "body": "{\"status\": \"allow\", \"context\": {\"user\": \"abc\"}}"
     }
     ```
     其中，body字段的内容为字符串格式，json解码之后为：
     ```
     {
     "status": "allow/deny",
     "context": {
     "user": "abc"
     }
     }
     ```
     - "statusCode"字段为必选，函数服务正常且自定义认证函数代码符合规范时，statusCode的值则为自定义认证函数的响应码。
       - 调用自定义认证的API，当自定义认证函数的响应码为非200时，API网关认为函数服务异常，并返回错误码"500"，错误信息为"Internal server error"。
       
       - 调用自定义认证的API，如果自定义认证开启宽松模式，当自定义认证函数连接失败、返回"500"或者"503"时，自定义认证不会校验body字段里面的status字段，直接返回调用成功，同时从函数代码中获取到的context字段也为空。
        
     
     - "status"字段为必选，用于标识认证结果。只支持"allow"或"deny"，"allow"表示认证成功，"deny"表示认证失败。
     
     - "context"字段为可选，支持字符串类型键值对，当实例支持authorizer_context_support_num_bool特性时，键值对的值支持number类型和boolean类型，键值不支持JSON对象或数组。 context中的数据为您自定义的字段，认证通过后作为认证参数映射到API网关后端参数中，其中context中的参数名称与系统参数名称必须完全一致，且区分大小写。context中的参数名称必须以英文字母开头，支持英文大小写字母、数字、下划线和中划线，且长度为1\~32个字符。
       后端认证通过后，context中的user的值abc映射到后端服务Header位置的test参数中，并将其传递给API的后端服务。
       
      
   
   
   **用户数据定义代码示例**：
   ```
   # -*- coding:utf-8 -*-
   import json
   import base64
   def handler(event, context):
       exampleuserdata=base64.b64encode(event["user_data"])
       resp = {
           'statusCode': 200,
           'body': json.dumps({
               "status":"allow",
               "context":{
                   "user":exampleuserdata
               }
           })   
       }
       return json.dumps(resp)
   ```
   
   
6. 测试函数。在测试事件的"事件模板"中选择"空白模板"，内容为： 
   ```
   {"user_data": "123"}
   ```
   根据实际情况修改后保存测试模板，单击"测试"。
   执行结果为"成功"时，表示测试成功。
   接下来您需要进入API网关界面创建后端自定义认证。
   
   
 
#### 创建后端自定义认证
在创建后端自定义认证前，请确保已有用于后端自定义认证的函数后端，否则请提前[创建用于后端自定义认证的函数]。
1. 进入[API网关控制台](https://console.huaweicloud.com/apig2/#/overview)页面。
2. 根据实际业务在左侧导航栏上方选择实例。

3. 在左侧导航栏选择"API管理 \> API策略"。
4. 在"自定义认证"页面，单击"创建自定义认证"。根据下表参数说明，配置自定义认证参数。 
   表2自定义认证参数说明 
   | 参数       | 说明                                                                                                                                                                                                                                                                                                                                         |
   |:---|:---|
   | 认证名称     | 填写您自定义的认证名称，用于区分不同的自定义认证。支持中文、英文、数字、下划线，只能以中文或英文开头，长度为3\~64个字符。                                                                                                                                                                                                                                                                            |
   | 类型       | 创建后端自定义认证时，选择"后端"。                                                                                                                                                                                                                                                                                                                         |
   | 函数地址     | 选择用于后端自定义认证的函数后端，仅可以选择状态为"已部署"的函数后端。                                                                                                                                                                                                                                                                                                       |
   | 版本或别名    | 选择函数的版本或别名，函数的版本或别名功能请参考[《函数工作流 FunctionGraph用户指南》](https://support.huaweicloud.com/usermanual-functiongraph/functiongraph_01_0180.html)。                                                                                                                                                                                                  |
   | 网络架构     | 选择函数网络架构。网络架构受限使用，如需使用，请[提交工单](https://support.huaweicloud.com/usermanual-ticket/zh-cn_topic_0127038618.html)开通。 - V1：对接函数的非VPC架构  - V2：对接函数的VPC架构   |
   | 超时时间(毫秒) | 设置函数认证的超时时间，仅当"网络架构"为"V2"时需要配置。 取值范围为1ms\~600000ms，最大支持600000ms，且不超过所选函数的超时时间。                                                                                                                                                                                                                            |
   | 缓存时间(秒)  | 设置认证结果缓存的时间。 取值范围为0s\~3600s，值为0时代表不缓存，最大支持3600s。                                                                                                                                                                                                                                                             |
   | 宽松模式     | - 开关开启后，当函数服务不可用（与函数服务建立连接失败或者函数服务返回5*xx*）时，API网关仍然接受客户端请求。如果有重试请求，以最后一次返回结果为准。  - 开关开启后，如果API的后端认证使用了自定义认证，那么后端认证参数获取到的值为空。   **开启宽松模式存在安全风险，请谨慎操作。**                         |
   | 身份来源     | 设置用于认证的请求参数。 当"类型"为"前端"，且"缓存时间"不为0时，必须设置此参数。使用缓存时，此参数将作为搜索条件来查询认证结果。                                                                                                                                                                                                                                          |
   | 是否发送body | 指是否将API请求的body体内容传递给认证函数。body体内容传给函数的方式，与header、query内容传递一致。                                                                                                                                                                                                                                                                               |
   | 用户数据     | 自定义的请求参数，APIG调用函数时，与"身份来源"一同作为请求参数。长度为1\~2048个字符。                                                                                                                                                                                                                                                                                          |
      
   
   
5. 单击"确定"，完成自定义认证的创建。 
   在自定义认证列表中显示已创建的自定义认证，表示认证创建成功。
   
   
 
#### 相关文档
- 自定义认证创建完成后，您可以创建自定义认证类型的API。具体操作，请参考[创建API](https://support.huaweicloud.com/usermanual-apig/apig_03_0010.html)章节。
- 如果您希望通过API创建后端自定义认证，请参考[创建自定义认证](https://support.huaweicloud.com/api-apig/CreateCustomAuthorizerV2.html)。