网关鉴权组件
组件编码
hzero-gateway-helper-api
组件编码
hzero-gateway-helper-default
简介
-
hzero-gateway-helper-api
提供鉴权的顶层接口端点以及鉴权过滤器接口,产品或项目完全可以自定义鉴权逻辑或者加入特定的鉴权逻辑。 -
hzero-gateway-helper-default
是hzero-gateway-helper-api
的默认实现 -
组件坐标
<dependency> <groupId>org.hzero</groupId> <artifactId>hzero-gateway-helper</artifactId> <version>${hzero.service.version}</version> </dependency>
黑名单和白名单
- 黑名单禁止某些符合特定规则的IP访问;白名单仅允许某些符合特定规则的IP访问。
- 使用时需要在
hzero-gateway-helper
服务的配置文件中添加下面的配置:
hzero:
filter:
# 白名单配置
white-list:
# 是否启用,默认不启用
enable: true
# 匹配规则
ip:
- 172.10,11.0-100.*
- 192.10,11.0-100.*
# 白名单配置
black-list:
# 是否启用,默认不启用
enable: true
# 匹配规则
ip:
- 172.10,11.0-100.*
- 192.10,11.0-100.*
- 在配置匹配的
IP
时,可以使用特定的规则来简化配置:- 匹配某个固定值:
固定值
(例如:172.20.0.128) - 匹配多个值:
值1,值2,值3
(例如:172.20.0.128,129) - 匹配一个段:
值1-值2
(例如:172-192.20.0.128-255; 注意:值1-
等同于固定值;值1-值2-值3
等同于值1-值3
) - 匹配任意直:
*
(例如:172.20.0.*) - 多个规则之间可以组合使用,例如10,172-192.20.0-10.*
- 多个规则之间不能嵌套,*例如172-会无法识别
- 匹配某个固定值:
GatewayHelper 鉴权
鉴权过滤器
GatewayHelper 组件提供了一组过滤器来对API及用户鉴权,具体可参考 基础服务调用链路
自定义鉴权
- hzero 提供了
hzero-gateway-helper-api
鉴权接口包 和hzero-gateway-helper-default
默认实现。 - 如果需要对鉴权逻辑进行整体改造,可以通过实现 org.hzero.gateway.helper.api.AuthenticationHelper 接口来完全定制化鉴权的部分。
- 如果仅需要对现有鉴权逻辑新增逻辑,可以通过实现 org.hzero.gateway.helper.api.HelperFilter 接口来新增鉴权逻辑。
/**
* 自定义鉴权过滤器,实现 org.hzero.gateway.helper.api.HelperFilter 接口
*/
@Component
public class CustomFilter implements HelperFilter {
public CustomFilter() {
}
/**
* 指定过滤器顺序,可在标准过滤器之前执行,数字越小,优先级越高
*/
@Override
public int filterOrder() {
return 50;
}
/**
* 是否执行此过滤器,false 则跳过此过滤器
*/
@Override
public boolean shouldFilter(RequestContext context) {
return true;
}
/**
* 具体的鉴权逻辑,返回 true,则鉴权通过,返回 false,则鉴权不通过
*
* @param context RequestContext 包含了API请求相关的所有信息
*/
@Override
public boolean run(RequestContext context) {
if (true) {
context.response.setStatus(CheckState.SUCCESS_PASS_SITE);
context.response.setMessage("Have access to this api.");
return true;
} else {
context.response.setStatus(CheckState.PERMISSION_NOT_PASS);
context.response.setMessage("No access to this api.");
return false;
}
}
}
签名API
GatewayHelper 支持签名方式对API鉴权,调用方通过提供的算法生成签名,网关验证签名通过后,即可访问API。需注意的是,签名API与公开API类似,无法获取用户信息。
启用签名鉴权
- 首先需在gateway配置文件中启用API签名鉴权,然后配置客户端签名ID和签名密钥,并分发给客户端使用。
hzero:
gateway:
helper:
## 启用API签名
signature:
enabled: false
secrets:
- secretId: hzero
secretKey: xxxxxxxxxxxxxx
- secretId: srm
secretKey: xxxxxxxxxxxxxxxx
客户端签名
-
客户端需先下载客户端签名工具:ClientSignatureUtils.java
-
在调用HZERO API前,需先将请求参数封装到 Map 中,然后调用
ClientSignatureUtils.buildSignature
方法生成签名
/**
* 根据参数等信息获取签名
*
* @param params 请求参数
* @param method 请求方法,支持 HttpMethod#POST、HttpMethod#GET、HttpMethod#DELETE、HttpMethod#PUT
* @param secretId 密钥Id
* @param secretKey 签名密钥
* @return 签名
*/
public static String buildSignature(Map<String, Object> params, HttpMethod method, String secretId, String secretKey) {
// ...
}
- 生成签名后,将签名加入参数中再调用HZERO API即可。
定制化签名
如果标准的签名方式或算法不满足需求,可在gateway服务中定制签名认证。
-
定义
org.hzero.gateway.helper.service.SignatureService
的实现类,实现verifySignature
方法即可。方法返回true
则表示签名认证通过,返回false
则表示签名认证不通过。具体的签名算法和客户端签名工具可自行实现。public interface SignatureService { /** * API 签名验证 * * @param requestContext RequestContext,包含请求的所有信息 * @return true-验证通过; false-验证不通过 */ boolean verifySignature(RequestContext requestContext); }