第三方鉴权插件

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

1. 概述

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

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

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

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

image

2. 插件配置

重要

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

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透传给客户端

2.7 支持缓存鉴权应答

API网关为提高业务处理的平滑度,减少用户鉴权服务的压力,支持缓存鉴权应答,目前缓存是将apiuid + 所有authparameters 拼接成主键,鉴权应答作为缓存的值进行缓存的。缓存鉴权应答的时间最长为10分钟。

3. 日志

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

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