首页 API 网关 插件使用 第三方鉴权插件

第三方鉴权插件

您可以通过本插件配置自己的鉴权服务为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分钟
trimAuthorizationHeaderPrefix: true   # 如果鉴权参数位置在Authorization头中,智能跳过前缀提取参数内容,比如从Authorization:bearer hello这个头提取出来的值是hello,而不是bearer hello
authParameters:                       # 发送给鉴权服务的参数映射
  - targetParameterName: x-userId     # 发送给鉴权服务的参数名称
    sourceParameterName: userId       # 对应的原始请求中的参数名称
    targetLocation: query             # 发送给鉴权服务的参数位置
    sourceLocation: query             # 对应的原始请求中的参数位置
  - targetParameterName: x-passwoed   # 发送给鉴权服务的参数名称
    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分钟
authParameters:                       # 发送给鉴权服务的参数映射
  - targetParameterName: x-userId     # 发送给鉴权服务的参数名称
    sourceParameterName: userId       # 对应的原始请求中的参数名称
    targetLocation: query             # 发送给鉴权服务的参数位置
    sourceLocation: query             # 对应的原始请求中的参数位置
  - targetParameterName: x-passwoed   # 发送给鉴权服务的参数名称
    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授权名称
  path: "/auth"                       # 鉴权服务路径
  timeout: 7000                       # 鉴权服务超时时间,最大为10秒
  method: POST                        # 鉴权服务HTTP Method
passThroughBody: false                # 是否将请求的body透传给鉴权服务
cachedTimeBySecond: 10                # API网关缓存鉴权结果应答的时间,最长为10分钟
authParameters:                       # 发送给鉴权服务的参数映射
  - targetParameterName: x-userId     # 发送给鉴权服务的参数名称
    sourceParameterName: userId       # 对应的原始请求中的参数名称
    targetLocation: query             # 发送给鉴权服务的参数位置
    sourceLocation: query             # 对应的原始请求中的参数位置
  - targetParameterName: x-passwoed   # 发送给鉴权服务的参数名称
    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            # 鉴权失败时,将鉴权应答的的body透传给客户端
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分钟
authParameters:                       # 发送给鉴权服务的参数映射
  - targetParameterName: x-userId     # 发送给鉴权服务的参数名称
    sourceParameterName: userId       # 对应的原始请求中的参数名称
    targetLocation: query             # 发送给鉴权服务的参数位置
    sourceLocation: query             # 对应的原始请求中的参数位置
  - targetParameterName: x-passwoed   # 发送给鉴权服务的参数名称
    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分钟
authParameters:                       # 发送给鉴权服务的参数映射
  - targetParameterName: x-passwoed   # 发送给鉴权服务的参数名称
    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            # 鉴权失败时,将鉴权应答的的body透传给客户端
ignoreAuthException: true             # 如果鉴权发生Exception,比如超时,连接出错,忽略鉴权结果,直接访问后端
orAppAuth: true						  # APP验证和第三方鉴权只要有一个成功了,就算鉴权成功

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

3. 日志

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

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

阿里云首页 API 网关 相关技术圈