全部产品
Search

搜索本产品

    API 网关：第三方鉴权插件

    文档中心

    API 网关：第三方鉴权插件

    更新时间：Jul 15, 2024

    您可以通过本插件配置自己的鉴权服务为API的访问进行鉴权。

    1. 概述

    API网关在调用API后端服务之前将先调用用户的鉴权服务，收到鉴权服务的鉴权成功应答后才会继续调用后端服务，否则给客户端返回鉴权失败的应答。第三方鉴权插件支持的功能如下：

    • 允许用户自定义发送给鉴权服务的请求参数；

    • 允许用户将鉴权应答结果在API网关缓存一定时间，保持业务的平滑度；

    • 允许用户自定义鉴权失败的应答；

    image

    2. 插件配置

    2.1 当鉴权服务为公网地址时，插件配置示例如下：

    ---
parameters:                           # 鉴权结果表达式中使用到的参数定义
  statusCode: "StatusCode"            # http应答码
authUriType: "HTTP"                   # 鉴权服务类型：HTTP:公网的鉴权地址，HTTP-VPC:VPC授权地址
authUri:                              # 鉴权服务定义
  address: "http://auth.com:8080"     # 鉴权服务地址，包括端口号
  path: "/auth"                       # 鉴权服务路径
  timeout: 7000                       # 鉴权服务超时时间，最大为10秒
  method: POST                        # 鉴权服务HTTP Method
passThroughBody: false                # 是否将请求的body透传给鉴权服务
passThroughPath: true                 # 如果为true，请求path将放到X-Ca-Remote-Auth-Raw-Path头中发送给鉴权服务
cachedTimeBySecond: 10                # API网关缓存鉴权结果应答的时间，最长为10分钟（目前缓存是将所有apiuid+authparameters作为主键去缓存的）
trimAuthorizationHeaderPrefix: true   # 如果鉴权参数位置在Authorization头中，智能跳过前缀提取参数内容，比如从Authorization:bearer hello这个头提取出来的值是hello，而不是bearer hello
authParameters:                       # 发送给鉴权服务的参数映射
  - targetParameterName: x-userId     # 发送给鉴权服务的参数名称
    sourceParameterName: userId       # 对应的原始请求中的参数名称
    targetLocation: query             # 发送给鉴权服务的参数位置
    sourceLocation: query             # 对应的原始请求中的参数位置
  - targetParameterName: x-password   # 发送给鉴权服务的参数名称
    sourceParameterName: password     # 对应的原始请求中的参数名称
    targetLocation: query             # 发送给鉴权服务的参数位置
    sourceLocation: query             # 对应的原始请求中的参数位置
  - targetParameterName: token
    sourceParameterName: Authorization
    targetLocation: query
    sourceLocation: header
successCondition: "${statusCode} = 200"  # 判断鉴权应答的表达式，表达式为True表示鉴权成功
errorMessage: "auth failed"           # 鉴权失败时，客户端收到的应答x-ca-errormessage头的值
errorStatusCode : 401                 # 鉴权失败时，客户端收到的http status值
errorPassThroughHeaderList: auth-result1,auth-result2           # 鉴权失败时，透传鉴权应答的指定头给客户端
errorPassThroughBody: true            # 鉴权失败时，将鉴权应答的body透传给客户端
ignoreAuthException: true             # 如果鉴权发生Exception，比如超时，连接出错，忽略鉴权结果，直接访问后端

    绑定了此插件的API，API网关在处理相关请求的时候，会先根据定义组装一个鉴权请求发送给”http://auth.com:8080“，并且根据应答判断鉴权是否通过。如果鉴权没有通过，可以定制鉴权失败的应答返回给客户端。

    2.2 当鉴权服务在VPC资源内时，需先给鉴权服务创建VPC授权，插件配置示例如下：

    ---
parameters:                           # 鉴权结果表达式中使用到的参数定义
  statusCode: "StatusCode"            # http应答码
authUriType: "HTTP-VPC"               # 鉴权服务类型：HTTP为公网的鉴权地址，HTTP-VPC为VPC授权地址
authUri:                              # 鉴权服务定义
  vpcAccessName: "slbAccessForVip"    # 鉴权服务的VPC授权名称
  path: "/auth"                       # 鉴权服务路径
  timeout: 7000                       # 鉴权服务超时时间，最大为10秒
  method: POST                        # 鉴权服务HTTP Method
passThroughBody: false                # 是否将请求的body透传给鉴权服务
cachedTimeBySecond: 10                # API网关缓存鉴权结果应答的时间，最长为10分钟（目前缓存是将所有apiuid+authparameters作为主键去缓存的）
authParameters:                       # 发送给鉴权服务的参数映射
  - targetParameterName: x-userId     # 发送给鉴权服务的参数名称
    sourceParameterName: userId       # 对应的原始请求中的参数名称
    targetLocation: query             # 发送给鉴权服务的参数位置
    sourceLocation: query             # 对应的原始请求中的参数位置
  - targetParameterName: x-password   # 发送给鉴权服务的参数名称
    sourceParameterName: password     # 对应的原始请求中的参数名称
    targetLocation: query             # 发送给鉴权服务的参数位置
    sourceLocation: query             # 对应的原始请求中的参数位置
successCondition: "${statusCode} = 200"  # 判断鉴权应答的表达式，表达式为True表示鉴权成功
errorMessage: "auth failed"           # 鉴权失败时，客户端收到的应答x-ca-errormessage头的值
errorStatusCode : 401                 # 鉴权失败时，客户端收到的http status值
errorPassThroughHeaderList: auth-result1,auth-result2           # 鉴权失败时，透传鉴权应答的指定头给客户端
errorPassThroughBody: true            # 鉴权失败时，将鉴权应答的body透传给客户端
ignoreAuthException: true             # 如果鉴权发生Exception，比如超时，连接出错，忽略鉴权结果，直接访问后端

    2.3 支持提取鉴权结果Body中的JSON中的字段作为表达式的参数

    ---
parameters:                           # 鉴权结果表达式中使用到的参数定义
  clientId: "BodyJsonField:$.clientId"# 鉴权应答BODY中的JSON结构中的参数名为clientId
authUriType: "HTTP-VPC"               # 鉴权服务类型：HTTP:公网的鉴权地址，HTTP-VPC:VPC授权地址
authUri:                              # 鉴权服务定义
  vpcAccessName: "slbAccessForVip"    # 鉴权服务的VPC授权名称
  vpcScheme: "https"                  # 鉴权服务协议指定HTTPS，不指定默认是HTTP
  path: "/auth"                       # 鉴权服务路径
  timeout: 7000                       # 鉴权服务超时时间，最大为10秒
  method: POST                        # 鉴权服务HTTP Method
passThroughBody: false                # 是否将请求的body透传给鉴权服务
cachedTimeBySecond: 10                # API网关缓存鉴权结果应答的时间，最长为10分钟（目前缓存是将所有apiuid+authparameters作为主键去缓存的）
authParameters:                       # 发送给鉴权服务的参数映射
  - targetParameterName: x-userId     # 发送给鉴权服务的参数名称
    sourceParameterName: userId       # 对应的原始请求中的参数名称
    targetLocation: query             # 发送给鉴权服务的参数位置
    sourceLocation: query             # 对应的原始请求中的参数位置
  - targetParameterName: x-password   # 发送给鉴权服务的参数名称
    sourceParameterName: password     # 对应的原始请求中的参数名称
    targetLocation: query             # 发送给鉴权服务的参数位置
    sourceLocation: query             # 对应的原始请求中的参数位置
successCondition: "${clientId} = 10086"  # 判断鉴权应答的表达式，表达式为True表示鉴权成功
errorMessage: "auth failed"           # 鉴权失败时，客户端收到的应答x-ca-errormessage头的值
errorStatusCode : 401                 # 鉴权失败时，客户端收到的http status值
errorPassThroughHeaderList: auth-result1,auth-result2           # 鉴权失败时，透传鉴权应答的指定头给客户端
errorPassThroughBody: true            # 鉴权失败时，将鉴权应答的ody透传给客户端
ignoreAuthException: true             # 如果鉴权发生Exception，比如超时，连接出错，忽略鉴权结果，直接访问后端

    如果鉴权服务返回的应答中的clientId字段为10086，那么鉴权就成功。

    {"code":200,"clientId":10086}

    2.4 支持提取鉴权结果与插件数据集进行身份鉴权，实现动态白名单

    用户通过插件数据集保存一份白名单数据，API网关从第三方鉴权结果的应答中提取用户身份字段，并且验证用户身份是否在白名单中，只有白名单中用户才能通过鉴权。

    ---
parameters:                           # 鉴权结果表达式中使用到的参数定义
  statusCode: "StatusCode"            # http应答码
  clientId: "BodyJsonField:$.clientId"# 鉴权应答BODY中的JSON结构中的参数名为clientId
authUriType: "HTTP-VPC"               # 鉴权服务类型：HTTP:公网的鉴权地址，HTTP-VPC:VPC授权地址
authUri:                              # 鉴权服务定义
  vpcAccessName: "slbAccessForVip"    # 鉴权服务的VPC授权名称
  path: "/auth"                       # 鉴权服务路径
  timeout: 7000                       # 鉴权服务超时时间，最大为10秒
  method: POST                        # 鉴权服务HTTP Method
passThroughBody: false                # 是否将请求的body透传给鉴权服务
cachedTimeBySecond: 10                # API网关缓存鉴权结果应答的时间，最长为10分钟（目前缓存是将所有apiuid+authparameters作为主键去缓存的）
authParameters:                       # 发送给鉴权服务的参数映射
  - targetParameterName: x-userId     # 发送给鉴权服务的参数名称
    sourceParameterName: userId       # 对应的原始请求中的参数名称
    targetLocation: query             # 发送给鉴权服务的参数位置
    sourceLocation: query             # 对应的原始请求中的参数位置
  - targetParameterName: x-password   # 发送给鉴权服务的参数名称
    sourceParameterName: password     # 对应的原始请求中的参数名称
    targetLocation: query             # 发送给鉴权服务的参数位置
    sourceLocation: query             # 对应的原始请求中的参数位置
successCondition: "${statusCode} = 200"  # 判断鉴权应答的表达式
accessParameterName: clientId         # 参与数据集内数据进行比对的参数名称
accessByDataSet: dataset_test         # 参与鉴权的数据集，如果数据集内数据包含了clientId的值，那么鉴权就通过
errorMessage: "auth failed"           # 鉴权失败时，客户端收到的应答x-ca-errormessage头的值
errorStatusCode : 401                 # 鉴权失败时，客户端收到的http status值
errorPassThroughHeaderList: auth-result1,auth-result2           # 鉴权失败时，透传鉴权应答的指定头给客户端
errorPassThroughBody: true            # 鉴权失败时，将鉴权应答的body透传给客户端
ignoreAuthException: true             # 如果鉴权发生Exception，比如超时，连接出错，忽略鉴权结果，直接访问后端

    如果鉴权服务返回的应答中的clientId字段值在名称为dataset_test的插件数据集中存在，那么鉴权就成功。

    2.5 支持与APP验证融合

    ---
parameters:                           # 鉴权结果表达式中使用到的参数定义
  statusCode: "StatusCode"            # http应答码
authUriType: "HTTP-VPC"               # 鉴权服务类型：HTTP:公网的鉴权地址，HTTP-VPC:VPC授权地址
authUri:                              # 鉴权服务定义
  vpcAccessName: "slbAccessForVip"    # 鉴权服务的VPC授权名称
  path: "/auth"                       # 鉴权服务路径
  timeout: 7000                       # 鉴权服务超时时间，最大为10秒
  method: POST                        # 鉴权服务HTTP Method
cachedTimeBySecond: 10                # API网关缓存鉴权结果应答的时间，最长为10分钟（目前缓存是将所有apiuid+authparameters作为主键去缓存的）
authParameters:                       # 发送给鉴权服务的参数映射
  - targetParameterName: x-password   # 发送给鉴权服务的参数名称
    sourceParameterName: password     # 对应的原始请求中的参数名称
    targetLocation: query             # 发送给鉴权服务的参数位置
    sourceLocation: query             # 对应的原始请求中的参数位置
successCondition: "${statusCode} = 200"  # 判断鉴权应答的表达式
errorMessage: "auth failed"           # 鉴权失败时，客户端收到的应答x-ca-errormessage头的值
errorStatusCode : 401                 # 鉴权失败时，客户端收到的http status值
errorPassThroughHeaderList: auth-result1,auth-result2           # 鉴权失败时，透传鉴权应答的指定头给客户端
errorPassThroughBody: true            # 鉴权失败时，将鉴权应答的ody透传给客户端
ignoreAuthException: true             # 如果鉴权发生Exception，比如超时，连接出错，忽略鉴权结果，直接访问后端
orAppAuth: true						  # APP验证和第三方鉴权只要有一个成功了，就算鉴权成功

    配置了orAppAuth: true参数后，APP验证和第三方鉴权只要有一个成功了，就算鉴权成功。

    2.6 支持从鉴权服务的应答中提取字段发给后端服务

    从鉴权服务返回的应答中提取字段发给后端服务，可以用authResultPassThrough来配置发送给后端服务的参数映射。

    应答提取支持的参数位置：StatusCode、Header、JsonBody。

    后端服务支持的参数位置：Header、Query、Formdata。

    ---
parameters:                         # 鉴权结果表达式中使用到的参数定义
  statusCode: "StatusCode"          # http应答码
  clientId: "BodyJsonField:$.Body"  # 鉴权服务返回的jsonbody
authUriType: "HTTP"                 # 鉴权服务类型：HTTP:公网的鉴权地址，HTTP-VPC:VPC授权地址
authUri:                            # 鉴权服务定义
  address: "http://127.0.0.1:8080"  # 鉴权服务地址，包括端口号
  path: "/web"                      # 鉴权服务路径
  timeout: 7000                     # 鉴权服务超时时间，单位是ms。最大支持10s
  method: POST                      # 鉴权服务HTTP Method
passThroughBody: true               # 是否将请求的body透传给鉴权服务
cachedTimeBySecond: 10              # API网关缓存鉴权结果应答的时间，最长为10分钟（目前缓存是将所有apiuid+authparameters作为主键去缓存的）
authResultPassThrough:              #发送给后端服务的参数映射
  - targetParameterName: x-echo-header-client-id  #发送给后端服务的参数名称
    targetLocation: header                        #发送给后端服务的参数位置
    sourceParameterName: clientId                 #从鉴权服务应答中提取的参数
  - targetParameterName: x-echo-header-status-code
    targetLocation: query
    sourceParameterName: statusCode
successCondition: "${statusCode} = 200"  # 判断鉴权应答的表达式
errorMessage: "auth failed"              # 鉴权失败时，客户端收到的应答x-ca-errormessage头的值
errorStatusCode: 401                     # 鉴权失败时，客户端收到的http status值
errorPassThroughHeaderList: auth-result1,auth-result2   # 鉴权失败时，透传鉴权应答的指定头给客户端
errorPassThroughBody: true               # 鉴权失败时，将鉴权应答的ody透传给客户端
    重要

    2023-05-09号之前购买的专享实例，如果不生效需提交工单联系我们给您升级实例版本。

    3. 日志

    在投递给sls的日志中，有一个plugin字段，里面描述了第三方鉴权的结果，"authSuccess":"0"为鉴权失败，"authSuccess":"1"为鉴权成功

    plugin:[{"context":{"authSuccess":"0"},"pluginName":"remoteAuth"}]