您可以通过本插件配置自己的鉴权服务为API的访问进行鉴权。
1. 概述
API网关在调用API后端服务之前将先调用用户的鉴权服务,收到鉴权服务的鉴权成功应答后才会继续调用后端服务,否则给客户端返回鉴权失败的应答。第三方鉴权插件支持的功能如下:
允许用户自定义发送给鉴权服务的请求参数;
允许用户将鉴权应答结果在API网关缓存一定时间,保持业务的平滑度;
允许用户自定义鉴权失败的应答;
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"}]