API令牌合规验证-边缘安全加速(ESA)-阿里云帮助中心

通过添加自定义令牌JWT（JSON Web Token）并绑定待验证的API即可创建API令牌合规验证规则，ESA将针对传入的请求进行令牌合规验证并进行处理，保障您的业务API安全。

配置API令牌规则

在ESA控制台，选择站点管理，在站点列单击目标站点。
在左侧导航栏，选择安全防护 > API安全。
在API安全页面，选择API规则页签，单击令牌配置。
在设置页面，单击添加，添加令牌信息。
按业务需求完成令牌参数填写后，单击确定即可。
- 配置名称：输入您自定义的令牌名称，如JWT-Demo。
- 令牌位置：选择令牌在请求中的位置，可选择标头和Cookie两种字段，并输入对应的键值。
  说明
  为适配不同业务中JWT的所在位置，通过单击Or可以创建逻辑或条件，可同时判断最多4个令牌位置。
- 令牌密钥：通过手动输入或上传JSON文件来添加令牌密钥，密钥要求可参考令牌说明。
  说明
  若配置多个密钥，则会根据kid字段选取密钥进行校验，若有一份密钥校验通过则通过。
完成令牌配置后即可进行API规则创建。返回API规则页签，单击新增规则按钮。
根据业务需求进行令牌校验相关参数配置即可。
- 规则名称：自定义规则名称，如rule-jwt-demo。
- 验证API：单击下拉选择需要进行令牌合规校验的主机记录，选择后ESA将自动为您展示所选主机记录下的API列表，检查并勾选所需的API即可。
- 选择令牌配置：勾选一个或多个需要校验的令牌。当勾选多个令牌时可选择：
  - 至少校验一个配置：请求需要符合多个令牌配置中的一个即可，否则将被判定为不合规请求。
  - 验证所有配置：请求需要同时符合所有令牌配置，否则将被判定为不合规请求。
    说明
    当API请求中缺少令牌时，默认会将请求标记为不合规，若有特殊需要可在对应令牌右侧的缺少令牌时列下拉选择忽略。
- 执行操作：选择对不符合令牌校验的请求的操作：
  - 观察：放行不合规的请求，并记录日志，可通过事件分析查看详情。
  - 拦截：阻止不合规的请求，并记录拦截日志，可通过事件分析查看详情。

防护效果

完成API规则创建后，您可以在左侧导航栏选择安全防护 > 事件分析，在事件分析页面通过筛选器选择防护规则为API规则，下滑即可在采样日志栏中查看详细的防护日志。

令牌说明

当前令牌校验仅用于JWT验证。

字段说明

公钥格式仅支持JWK，且JWT公钥必须含有kid和alg字段。字段含义可参考：

kty：密钥类型，如 EC-椭圆曲线密钥。
use：公钥用途，如 sig - 用于数字签名。
crv：椭圆曲线类型，如 P-256 - NIST标准化的P-256椭圆曲线
kid：自定义的密钥标识符，如esa。JWK必须带有kid字段，用于密钥的选择；同样的，请求的JWT的声明中也必须带有kid字段。使用该字段可用于令牌密钥的轮换。
x：使用椭圆曲线密钥时，椭圆曲线公钥的x坐标。
y：使用椭圆曲线密钥时，椭圆曲线公钥的y坐标。
alg：算法标识，当前支持： ES256 - ECDSA with SHA-256签名算法。

示例

{
  "kty": "EC",
  "use": "sig",
  "crv": "P-256",
  "kid": "esa",
  "x": "QG3VFVwUX4IatQvBy7sqBvvmticCZ-eX5-nbtGKBOfI",
  "y": "A3PXCshn7XcG7Ivvd2K_DerW4LHAlIVKdqhrUnczTD0",
  "alg": "ES256"
}

常见问题

什么是JWT？

JWT（JSON Web Token），是为了在网络应用环境间传递声明而执行的一种基于JSON的开放标准RFC7519。JWT一般可以用作独立的身份验证令牌，可以包含用户标识、用户角色和权限等信息，以便于从资源服务器获取资源，也可以增加一些额外的其他业务逻辑所必需的声明信息，特别适用于分布式站点的登录场景。

JWT由Header、Payload、Signature三部分构成，并分别对每部分进行Base64编码，输出形如Header.Payload.Signature的字符串：

Header：JWT的头部，用于承载声明类型（JWT）以及声明加密的算法。
Payload：JWT的数据部，用于存放有效信息，也可以新增用户系统需要使用的自定义字段。
Signature：JWT的签名部，用于头部和数据部内容的校验。

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ

如何生成JWT？

可使用https://mkjwk.org 生成用于token生成与验证的私钥与公钥：

使用浏览器访问https://mkjwk.org 。
选择EC页签，填写相关参数后，单击Generate生成后，选择Public Key并单击Copy to Clipboard复制公钥即可。
- Curve：选择加密类型为P-256。
- Key Use：选择公钥用途为签名Signature。
- Algorithm：选择算法标识为ES256: ECDSA using P-256 and SHA-256。
- KeyID：输入自定义的密钥标识符，如esa。