mirror of
https://github.com/alibaba/higress.git
synced 2026-04-20 19:47:29 +08:00
209 lines
10 KiB
Markdown
209 lines
10 KiB
Markdown
---
|
||
title: APISIX HMAC 认证
|
||
keywords: [higress,hmac auth,apisix]
|
||
description: APISIX HMAC 认证插件配置参考
|
||
---
|
||
|
||
## 功能说明
|
||
|
||
`hmac-auth-apisix` 插件兼容 Apache APISIX 的 HMAC 认证机制，通过 HMAC 算法为 HTTP 请求生成防篡改的数字签名，实现请求的身份认证和权限控制。该插件完全兼容 Apache APISIX HMAC 认证插件的配置和签名算法，签名生成方法可参考 [Apache APISIX HMAC 认证文档](https://apisix.apache.org/docs/apisix/plugins/hmac-auth/)
|
||
|
||
## 运行属性
|
||
|
||
插件执行阶段：`认证阶段`
|
||
插件执行优先级：`330`
|
||
|
||
## 配置字段
|
||
|
||
**注意：**
|
||
|
||
- 在一个规则里，鉴权配置和认证配置不可同时存在
|
||
- 对于通过认证鉴权的请求，请求的 header 会被添加一个 `X-Mse-Consumer` 字段，用以标识调用者的名称
|
||
|
||
### 认证配置
|
||
|
||
| 名称 | 数据类型 | 填写要求 | 默认值 | 描述 |
|
||
| ----------------------- | --------------- | -------------------------- | ------------------------------------------- | ------------------------------------------------------------ |
|
||
| `global_auth` | bool | 选填（**仅实例级别配置**） | - | 只能在实例级别配置，若配置为 true，则全局生效认证机制；若配置为 false，则只对做了配置的域名和路由生效认证机制，若不配置则仅当没有域名和路由配置时全局生效（兼容老用户使用习惯） |
|
||
| `consumers` | array of object | 必填 | - | 配置服务的调用者，用于对请求进行认证 |
|
||
| `allowed_algorithms` | array of string | 选填 | ["hmac-sha1", "hmac-sha256", "hmac-sha512"] | 允许的 HMAC 算法列表。有效值为 "hmac-sha1"、"hmac-sha256" 和 "hmac-sha512" 的组合 |
|
||
| `clock_skew` | number | 选填 | 300 | 客户端请求的时间戳与 Higress 服务器当前时间之间允许的最大时间差（以秒为单位）。这有助于解决客户端和服务器之间的时间同步差异，并防止重放攻击。时间戳将根据 Date 头中的时间（必须为 GMT 格式）进行计算。如果配置为0，会跳过该校验 |
|
||
| `signed_headers` | array of string | 选填 | - | 客户端请求的 HMAC 签名中应包含的 HMAC 签名头列表 |
|
||
| `validate_request_body` | boolean | 选填 | false | 如果为 true，则验证请求正文的完整性，以确保在传输过程中没有被篡改。具体来说，插件会创建一个 SHA-256 的 base64 编码 digest，并将其与 `Digest` 头进行比较。如果 `Digest` 头丢失或 digest 不匹配，验证将失败 |
|
||
| `hide_credentials` | boolean | 选填 | false | 如果为 true，则不会将授权请求头传递给上游服务 |
|
||
| `anonymous_consumer` | string | 选填 | - | 匿名消费者名称。如果已配置，则允许匿名用户绕过身份验证 |
|
||
|
||
|
||
`consumers`中每一项的配置字段说明如下：
|
||
|
||
| 名称 | 数据类型 | 填写要求 | 默认值 | 描述 |
|
||
| ------------ | -------- | -------- | ------------ | ---------------------------------------------- |
|
||
| `access_key` | string | 必填 | - | 消费者的唯一标识符，用于标识相关配置，例如密钥 |
|
||
| `secret_key` | string | 必填 | - | 用于生成 HMAC 的密钥 |
|
||
| `name` | string | 选填 | `access_key` | 配置该 consumer 的名称 |
|
||
|
||
### 鉴权配置（非必需）
|
||
|
||
| 名称 | 数据类型 | 填写要求 | 默认值 | 描述 |
|
||
| ------- | --------------- | ------------------------ | ------ | ------------------------------------------------------------ |
|
||
| `allow` | array of string | 选填(**非实例级别配置**) | - | 只能在路由或域名等细粒度规则上配置，对于符合匹配条件的请求，配置允许访问的 consumer，从而实现细粒度的权限控制 |
|
||
|
||
## 配置示例
|
||
|
||
### 全局配置认证和路由粒度鉴权
|
||
|
||
以下配置用于对网关特定路由或域名开启 Hmac Auth 认证和鉴权。**注意：access_key 字段不可重复**
|
||
|
||
#### 示例1：基础路由与域名鉴权配置
|
||
|
||
**实例级别插件配置**：
|
||
```yaml
|
||
global_auth: false
|
||
consumers:
|
||
- name: consumer1
|
||
access_key: consumer1-key
|
||
secret_key: 2bda943c-ba2b-11ec-ba07-00163e1250b5
|
||
- name: consumer2
|
||
access_key: consumer2-key
|
||
secret_key: c8c8e9ca-558e-4a2d-bb62-e700dcc40e35
|
||
```
|
||
|
||
**路由级配置**（适用于 route-a 和 route-b）：
|
||
```yaml
|
||
allow:
|
||
- consumer1 # 仅允许consumer1访问
|
||
```
|
||
|
||
**域名级配置**（适用于 `*.example.com` 和 `test.com`）：
|
||
```yaml
|
||
allow:
|
||
- consumer2 # 仅允许consumer2访问
|
||
```
|
||
|
||
**配置说明**：
|
||
- 路由名称（如 route-a、route-b）对应网关路由创建时定义的名称，匹配时仅允许consumer1访问
|
||
- 域名匹配（如 `*.example.com`、`test.com`）用于过滤请求域名，匹配时仅允许consumer2访问
|
||
- 未在allow列表中的调用者将被拒绝访问
|
||
|
||
**请求与响应示例**：
|
||
|
||
1. **验证通过场景**
|
||
```shell
|
||
curl -X POST 'http://localhost:8082/foo' \
|
||
-H 'Authorization:Signature keyId="consumer1-key",algorithm="hmac-sha256",headers="@request-target date",signature="G2+60rCCHQCQDZOailnKHLCEy++P1Pa5OEP1bG4QlRo="' \
|
||
-H 'Date:Sat, 30 Aug 2025 00:52:39 GMT' \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{}'
|
||
```
|
||
- 响应：返回后端服务正常响应
|
||
- 附加信息：认证通过后会自动添加请求头 `X-Mse-Consumer: consumer1` 传递给后端
|
||
|
||
2. **请求方法修改导致验签失败**
|
||
```shell
|
||
curl -X PUT 'http://localhost:8082/foo' \ # 此处将POST改为PUT
|
||
-H 'Authorization:Signature keyId="consumer1-key",algorithm="hmac-sha256",headers="@request-target date",signature="G2+60rCCHQCQDZOailnKHLCEy++P1Pa5OEP1bG4QlRo="' \
|
||
-H 'Date:Sat, 30 Aug 2025 00:52:39 GMT' \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{}'
|
||
```
|
||
- 响应：`401 Unauthorized`
|
||
- 错误信息：`{"message":"client request can't be validated: Invalid signature"}`
|
||
|
||
3. **不在允许列表中的调用者**
|
||
```shell
|
||
curl -X POST 'http://localhost:8082/foo' \
|
||
-H 'Authorization:Signature keyId="consumer2-key",algorithm="hmac-sha256",headers="@request-target date",signature="5sqSbDX9b91dQsfQra2hpluM7O6/yhS7oLcKPQylyCo="' \
|
||
-H 'Date:Sat, 30 Aug 2025 00:54:18 GMT' \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{}'
|
||
```
|
||
- 响应：`401 Unauthorized`
|
||
- 错误信息：`{"message":"client request can't be validated: consumer 'consumer2' is not allowed"}`
|
||
|
||
4. **时间戳过期**
|
||
```shell
|
||
curl -X POST 'http://localhost:8082/foo' \
|
||
-H 'Authorization: Signature keyId="consumer1-key",algorithm="hmac-sha256",headers="@request-target date",signature="gvIUwoYNiK57w6xX2g1Ntpk8lfgD7z+jgom434r5qwg="' \
|
||
-H 'Date: Sat, 30 Aug 2025 00:40:21 GMT' \ # 过期的时间戳
|
||
-H 'Content-Type: application/json' \
|
||
-d '{}'
|
||
```
|
||
- 响应：`401 Unauthorized`
|
||
- 错误信息：`{"message":"client request can't be validated: Clock skew exceeded"}`
|
||
|
||
#### 示例2：带自定义签名头与请求体验证的配置
|
||
|
||
**实例级别插件配置**：
|
||
```yaml
|
||
global_auth: false
|
||
consumers:
|
||
- name: consumer1
|
||
access_key: consumer1-key
|
||
secret_key: 2bda943c-ba2b-11ec-ba07-00163e1250b5
|
||
- name: consumer2
|
||
access_key: consumer2-key
|
||
secret_key: c8c8e9ca-558e-4a2d-bb62-e700dcc40e35
|
||
signed_headers: # 需要纳入签名的自定义请求头
|
||
- X-Custom-Header-A
|
||
- X-Custom-Header-B
|
||
validate_request_body: true # 启用请求体签名校验
|
||
```
|
||
|
||
**请求与响应示例**：
|
||
|
||
1. **验证通过场景**
|
||
```shell
|
||
curl -X POST 'http://localhost:8082/foo' \
|
||
-H 'Authorization:Signature keyId="consumer1-key",algorithm="hmac-sha256",headers="@request-target date x-custom-header-a x-custom-header-b",signature="+xCWYCmidq3Sisn08N54NWaau5vSY9qEanWoO9HD4mA="' \
|
||
-H 'Date:Sat, 30 Aug 2025 01:04:06 GMT' \
|
||
-H 'Digest:SHA-256=RBNvo1WzZ4oRRq0W9+hknpT7T8If536DEMBg9hyq/4o=' \ # 请求体摘要
|
||
-H 'X-Custom-Header-A:test1' \
|
||
-H 'X-Custom-Header-B:test2' \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{}'
|
||
```
|
||
- 响应：返回后端服务正常响应
|
||
|
||
2. **缺少签名头**
|
||
```shell
|
||
curl -X POST 'http://localhost:8082/foo' \
|
||
-H 'Authorization:Signature keyId="consumer1-key",algorithm="hmac-sha256",headers="@request-target date x-custom-header-a x-custom-header-b",signature="+xCWYCmidq3Sisn08N54NWaau5vSY9qEanWoO9HD4mA="' \
|
||
-H 'Date:Sat, 30 Aug 2025 01:04:06 GMT' \
|
||
-H 'Digest:SHA-256=RBNvo1WzZ4oRRq0W9+hknpT7T8If536DEMBg9hyq/4o=' \
|
||
-H 'X-Custom-Header-B:test2' \ # 缺少X-Custom-Header-A
|
||
-H 'Content-Type: application/json' \
|
||
-d '{}'
|
||
```
|
||
- 响应：`401 Unauthorized`
|
||
- 错误信息：`{"message":"client request can't be validated: expected header "X-Custom-Header-A" missing in signing"}`
|
||
|
||
3. **请求体被篡改**
|
||
```shell
|
||
curl -X POST 'http://localhost:8082/foo' \
|
||
-H 'Authorization:Signature keyId="consumer1-key",algorithm="hmac-sha256",headers="@request-target date x-custom-header-a x-custom-header-b",signature="dSbv6pdQOcgkN89TmSxiT8F9nypbPUqAR2E7ELL8K2s="' \
|
||
-H 'Date:Sat, 30 Aug 2025 01:10:17 GMT' \
|
||
-H 'Digest:SHA-256=RBNvo1WzZ4oRRq0W9+hknpT7T8If536DEMBg9hyq/4o=' \ # 与实际body不匹配
|
||
-H 'X-Custom-Header-A:test1' \
|
||
-H 'X-Custom-Header-B:test2' \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"key":"value"}' # 篡改后的请求体
|
||
```
|
||
- 响应：`401 Unauthorized`
|
||
- 错误信息：`{"message":"client request can't be validated: Invalid digest"}`
|
||
|
||
### 网关实例级别开启全局认证
|
||
|
||
以下配置将在网关实例级别开启 Hmac Auth 认证，**所有请求必须经过认证才能访问**：
|
||
|
||
```yaml
|
||
global_auth: true # 开启全局认证
|
||
consumers:
|
||
- name: consumer1
|
||
access_key: consumer1-key
|
||
secret_key: 2bda943c-ba2b-11ec-ba07-00163e1250b5
|
||
- name: consumer2
|
||
access_key: consumer2-key
|
||
secret_key: c8c8e9ca-558e-4a2d-bb62-e700dcc40e35
|
||
```
|
||
|
||
**说明**：当 `global_auth: true` 时，所有访问网关的请求都需要携带有效的认证信息，未认证的请求将被直接拒绝 |