接口安全控制

risenet-y9boot-support-api-access-control 组件加入了对接口安全的控制，下面介绍组件的使用

黑名单

对于加入黑名单的客户端访问接口会被拒绝

输入的名单可以是多个，用英文逗号分割，支持具体 IP、IP 网段格式。示例：

192.168.1.1
192.168.1.0/24
192.168.1.1-100
192.168.1.*

白名单

只有在白名单内的客户端才允许访问接口，如果此过滤项开启时，而此时没有添加允许的记录，默认允许所有请求通过

白名单的配置格式可参考黑名单的配置格式

接口签名

接口签名验证，如果此过滤项开启则对应的请求必须有签名，且客户端的签名需跟服务端计算的签名一致放可放行。接口签名机制可以识别请求用户的身份，防止请求的篡改，以及防止一定程度的重放攻击

需要在数字底座中申请 API 密钥，方便后续生成接口请求的签名，请求使用 UTF-8 编码

签名计算伪代码：

String stringToSign = appId + path + sortedQueryString + body + timestamp;
String sign = HMAC-SHA256 (app_secret, stringToSign);

接下来以数字底座中的一个接口为例说明

http

GET http://localhost:7055/platform/services/rest/v1/organization/get?tenantId=11111111-1111-1111-1111-111111111113&
    organizationId=11111111-1111-1111-1111-111111111115

参与签名的各个参数

参数名	描述	参考值
app_secret	数字底座生成的 API 密钥中的 appSecret	`bfyu9pJxm0M2KfhblOG9QNTns17Vz3yz3v5Jbq`
appId	数字底座生成的 API 密钥中的 appId	`1732477113216737280`
path	请求的 URL 的部分，移除协议、域名及请求参数部分	`/platform/services/rest/v1/person/get`
sortedQueryString	按 key 名称以字典顺序排序后的查询参数字符串	`organizationId=1666895850885423104&tenantId=11111111-1111-1111-1111-111111111113`
body	原始的请求 body，如果为空则用 "" 空字符串代替
timestamp	请求的秒级时间戳	`1734329686`

参数签名示例

String stringToSign = "1732477113216737280"
        + "/platform/services/rest/v1/person/get"
        + "organizationId=1666895850885423104&tenantId=11111111-1111-1111-1111-111111111113"
        + ""
        + "1734329686";
String sign = HMAC-SHA256 ("bfyu9pJxm0M2KfhblOG9QNTns17Vz3yz3v5Jbq", stringToSign);

需传递的请求头

请求头	描述	参考值
x-app-id	数字底座生成的密钥对中的 appId	`1732477113216737280`
x-timestamp	秒级的时间戳，可用于防止一定程度的重放攻击	`1734329686`
x-signature	客户端计算的签名值，十六进制的大写字符串	`5B3C73712158048EA34837B7BFA204AACA2E669ADDA94998A6E532E48AD685FD`

最终请求

http

GET http://localhost:7055/platform/services/rest/v1/organization/get?organizationId=1666895850843480064&
    tenantId=11111111-1111-1111-1111-111111111113
x-app-id: 1732477113216737280
x-timestamp: 1734329686
x-signature: 5B3C73712158048EA34837B7BFA204AACA2E669ADDA94998A6E532E48AD685FD

组件使用

工程中需要添加接口安全控制的特性，需引入依赖包，添加配置方可使其生效

Maven pom.xml

添加依赖包

xml


<dependency>
    <groupId>net.risesoft</groupId>
    <artifactId>risenet-y9boot-support-api-access-control</artifactId>
    <version>[最新版本]</version>
</dependency>

如果需要使用 snapshot 版本，还需添加私服仓库方能下载

xml


<repositories>
    <repository>
        <id>nexus</id>
        <name>local private nexus</name>
        <url>https://svn.youshengyun.com:9900/nexus/repository/maven-public/</url>
    </repository>
</repositories>
<pluginRepositories>
<pluginRepository>
    <id>nexus</id>
    <name>local private nexus</name>
    <url>https://svn.youshengyun.com:9900/nexus/repository/maven-public/</url>
</pluginRepository>
</pluginRepositories>

属性文件 application.yml

可配置的属性可参考 net.risesoft.y9.configuration.feature.apiacl.Y9ApiAccessControlProperties

yaml

y9:
    feature:
        api-access-control:
            url-patterns: '/services/rest/*'
            black-list:
                enabled: true
            white-list:
                enabled: true
            sign:
                enabled: true

处理逻辑

安全控制基于 Servlet Filter 做过滤，需要考虑过滤器之间的优先级

默认优先级黑名单、白名单再到密钥签名，如优先级较高的不通过则不再校验，直接返回失败。当然，可以通过修改配置项调整优先级

接口安全控制 ​

黑名单 ​

白名单 ​

接口签名 ​

组件使用 ​

Maven pom.xml ​

属性文件 application.yml ​

处理逻辑 ​