HMAC 插件基于 HmacSHA256 算法为 HTTP 请求生成不可伪造的 AK/SK 签名，开启后需要携带相关请求头和签名等信息访问当前资源。本文介绍如何创建一个 HMAC 插件。

背景信息

HMAC 是一种哈希函数的消息认证码机制，用于验证 API 请求的身份合法性和数据完成性。API 网关的 HMAC 认证鉴权功能采用 HmacSHA256 签名算法，通过 AK 和 SK 对请求进行签名验证，该机制有效防止请求被篡改或伪造，适用于安全性要求较高的 API 开访场景。具体的认证流程如下所示。

在 API 网关控制台创建消费者，并生成 HMAC 认证信息（AK/SK 密钥对）。

创建 HMAC 插件并绑定到目标服务或路由，启用认证鉴权。

调用方使用 SK 对请求内容进行 HmacSHA256 签名。

调用方将签名结果和 AK 放入请求的 Authorization 头中发送请求。

API 网关收到请求后，根据 AK 查找对应的 SK，使用相同算法重新计算签名，并与请求中携带的签名进行比对。

签名一致则认证通过，请求转发至后端服务；签名不一致则返回认证失败。

前提条件

如果生效级别选择服务级别，请先创建服务。具体操作，请参见创建服务。

如果生效级别选择路由级别，请先创建路由。具体操作，请参见创建路由。

已创建消费者，且生成认证信息。具体操作，请参见创建消费者和生成认证信息。

使用限制

同一插件在同一资源上只能绑定一次。

同一插件在不同级别的资源上绑定时，只匹配生效优先级最高的资源，生效优先级由高到低：路由 > 服务。

例如，服务 Ⅰ 具有两条路由：路由 A 和路由 B，将插件配置在服务 Ⅰ 和路由 A 上，此时路由 A 的生效规则遵循路由 A 的插件配置，路由 B 的生效规则遵循服务 Ⅰ 的插件配置。

实例级别的插件所属实例只能选择2024年1月19日00:00以后创建的网关实例。如果您的控制台无法开启插件，请提交工单。

操作步骤

登录 API 网关控制台。

在顶部导航栏，选择目标地域。

在左侧导航栏实例管理下拉框中选择目标实例后，单击插件中心 > 认证鉴权 > HMAC 插件。

单击创建插件，配置插件参数。

配置项	说明
生效级别	选择 HMAC 插件的生效级别。包括：服务级别、路由级别。说明同一插件在不同级别的资源上绑定时，只会匹配生效优先级最高的资源。生效优先级从高到低：路由 > 服务。
所属服务	生效级别选择服务级别，请选择所属实例和所属服务。
所属路由	生效级别选择路由级别，请选择所属实例、所属服务和所属路由。
备注	可选。您可以根据业务需要选择是否编辑备注内容，例如 HMAC 插件的用途，便于后期识别。
消费者	选择消费者。注意消费者必须已生成认证信息。

单击确定，完成配置。

结果验证

查看配置

配置完成后，在 HMAC 列表将生成一条新的插件记录。插件状态为已启用，表示插件功能生效。

认证测试

使用 API 网关实例中配置的域名访问服务，当访问请求携带 HMAC 认证信息时。HMAC 认证信息的签名方式，请参见签名方法。

预期结果如下，表示能够通过 API 网关访问到后端的服务。

使用 API 网关实例中配置的域名访问服务，当访问请求未携带 HMAC 认证信息时。

预期结果如下，表示认证失败，无法通过 API 网关访问到后端的服务。