Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

sync ext-auth and replay-protection docs #368

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
+272 −23
Open

sync ext-auth and replay-protection docs #368

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
baa9274
sync ext-auth docs
hanxiantao Feb 22, 2025
098bc7d
sync ext-auth docs
hanxiantao Feb 22, 2025
80205af
sync replay-protection docs
hanxiantao Feb 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 28 additions & 13 deletions src/content/docs/latest/en/plugins/authentication/ext-auth.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,7 @@ Configuration fields for each item of `MatchRule` type. When using `array of Mat
| Name | Data Type | Required | Default Value | Description |
| --- | --- | --- | --- | --- |
| `match_rule_domain` | string | No | - | The domain of the matching rule, supports wildcard patterns, e.g., `*.bar.com` |
| `match_rule_method` | []string | No | - | Matching rule for the request method |
| `match_rule_path` | string | No | - | The rule for matching the request path |
| `match_rule_type` | string | No | - | The type of the rule for matching the request path, can be `exact`, `prefix`, `suffix`, `contains`, `regex` |

Expand All @@ -100,27 +101,41 @@ Supports blacklist and whitelist mode configuration. The default is the whitelis
**Whitelist Mode**

```yaml
# Configuration for the whitelist mode. Requests that match the whitelist rules do not need verification.
match_type: 'whitelist'
match_list:
- match_rule_domain: '*.bar.com'
match_rule_path: '/foo'
match_rule_type: 'prefix'
# Requests with the domain name api.example.com and a path prefixed with /public do not need verification.
- match_rule_domain: 'api.example.com'
match_rule_path: '/public'
match_rule_type: 'prefix'
# For the image resource server images.example.com, all GET requests do not need verification.
- match_rule_domain: 'images.example.com'
match_rule_method: ["GET"]
# For all domains, HEAD requests with an exact path match of /health-check do not need verification.
- match_rule_method: ["HEAD"]
match_rule_path: '/health-check'
match_rule_type: 'exact'
```

Requests with a prefix match of `/foo` under the wildcard domain `*.bar.com` do not need to be verified.

**Blacklist Mode**

```yaml
# Configuration for the blacklist mode. Requests that match the blacklist rules need verification.
match_type: 'blacklist'
match_list:
- match_rule_domain: '*.bar.com'
match_rule_path: '/headers'
match_rule_type: 'prefix'
# Requests with the domain name admin.example.com and a path prefixed with /sensitive need verification.
- match_rule_domain: 'admin.example.com'
match_rule_path: '/sensitive'
match_rule_type: 'prefix'
# For all domains, DELETE requests with an exact path match of /user need verification.
- match_rule_method: ["DELETE"]
match_rule_path: '/user'
match_rule_type: 'exact'
# For the domain legacy.example.com, all POST requests need verification.
- match_rule_domain: 'legacy.example.com'
match_rule_method: ["POST"]
```

Only requests with a prefix match of `/header` under the wildcard domain `*.bar.com` need to be verified.


## Configuration Examples

Expand Down Expand Up @@ -186,13 +201,13 @@ Configuration of the `ext-auth` plugin:
http_service:
authorization_request:
allowed_headers:
- exact: x-auth-version
- exact: x-auth-version
headers_to_add:
x-envoy-header: true
authorization_response:
allowed_upstream_headers:
- exact: x-user-id
- exact: x-auth-version
- exact: x-user-id
- exact: x-auth-version
endpoint_mode: envoy
endpoint:
service_name: ext-auth.backend.svc.cluster.local
Expand Down
109 changes: 109 additions & 0 deletions src/content/docs/latest/en/plugins/security/replay-protection.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
---
title: Replay Attack Prevention
keywords: [higress, replay-protection]
description: Configuration reference for the replay attack prevention plugin
---

## Functional Description

The replay prevention plugin prevents request replay attacks by verifying the one-time random number in the request. Each request needs to carry a unique nonce value. The server will record and verify the uniqueness of this value, thus preventing requests from being maliciously replayed.

Specifically, it includes the following functions:

- **Mandatory or Optional Nonce Verification**: It can be configured to determine whether requests are required to carry a nonce value.
- **Nonce Uniqueness Verification Based on Redis**: The nonce value is stored and verified in Redis to ensure its uniqueness.
- **Configurable Nonce Validity Period**: It supports setting the validity period of the nonce, which will automatically expire after the period.
- **Nonce Format and Length Verification**: It supports verifying the format (Base64) and length of the nonce value.
- **Custom Error Response**: It supports configuring the status code and error message when a request is rejected.
- **Customizable Nonce Request Header**: The name of the request header carrying the nonce can be customized.

## Runtime Attributes

Plugin execution stage: `Authentication Stage`
Plugin execution priority: `800`

## Configuration Fields

| Name | Data Type | Required | Default Value | Description |
|----------------------|--------|------|-----------------|---------------------------------|
| `force_nonce` | bool | No | true | Whether requests are required to carry a nonce value. |
| `nonce_header` | string | No | `X-Higress-Nonce` | Specifies the name of the request header carrying the nonce value. |
| `nonce_ttl` | int | No | 900 | The validity period of the nonce, in seconds. |
| `nonce_min_length` | int | No | 8 | The minimum length of the nonce value. |
| `nonce_max_length` | int | No | 128 | The maximum length of the nonce value. |
| `reject_code` | int | No | 429 | The status code returned when a request is rejected. |
| `reject_msg` | string | No | `Replay Attack Detected` | The error message returned when a request is rejected. |
| `validate_base64` | bool | No | false | Whether to verify the Base64 encoding format of the nonce. |
| `redis` | Object | Yes | - | Redis-related configuration |

Description of each configuration field in `redis`

| Name | Data Type | Required | Default Value | Description|
| -------------- | -------- | ---- |---------------------| --------------------------------------- |
| `service_name` | string | Yes | - | The name of the Redis service, the complete FQDN name with the service type, such as my-redis.dns, redis.my-ns.svc.cluster.local. |
| `service_port` | int | No | 6379 | The port of the Redis service. |
| `username` | string | No | - | The username of Redis. |
| `password` | string | No | - | The password of Redis. |
| `timeout` | int | No | 1000 | The connection timeout time of Redis, in milliseconds. |
| `database` | int | No | 0 | The ID of the database to be used. For example, if it is configured as 1, it corresponds to `SELECT 1`. |
| `key_prefix` | string | No | `replay-protection` | The key prefix of Redis, used to distinguish different nonce keys. |

## Configuration Example

The following is a complete configuration example of the replay attack prevention plugin:

```yaml
force_nonce: true
nonce_header: "X-Higress-Nonce" # Specifies the name of the nonce request header
nonce_ttl: 900 # The validity period of the nonce, set to 900 seconds
nonce_min_length: 8 # The minimum length of the nonce
nonce_max_length: 128 # The maximum length of the nonce
validate_base64: true # Whether to enable Base64 format verification
reject_code: 429 # The HTTP status code returned when a request is rejected
reject_msg: "Replay Attack Detected" # The error message content returned when a request is rejected
redis:
service_name: redis.static # The name of the Redis service
service_port: 80 # The port used by the Redis service
timeout: 1000 # The timeout time of Redis operations (unit: milliseconds)
key_prefix: "replay-protection" # The key prefix in Redis
```

## Usage Instructions

### Request Header Requirements

| Request Header Name | Required | Description |
|-----------------|----------------|------------------------------------------|
| `X-Higress-Nonce` | Determined by the `force_nonce` configuration | The randomly generated nonce value carried in the request, which needs to conform to the Base64 format. |

> **Note**: The name of the request header can be customized through the `nonce_header` configuration. The default value is `X-Higress-Nonce`.

### Usage Example

```bash
# Generate nonce
nonce=$(openssl rand -base64 32)

# Send request
curl -X POST 'https://api.example.com/path' \
-H "X-Higress-Nonce: $nonce" \
-d '{"key": "value"}'
```

## Return Results

```json
{
"code": 429,
"message": "Replay Attack Detected"
}
```

## Error Response Examples

| Error Scenario | Status Code | Error Message |
|------------------------|-------|--------------------|
| Missing nonce request header | 400 | `Missing Required Header` |
| Nonce length does not meet the requirements | 400 | `Invalid Nonce` |
| Nonce format does not conform to Base64 | 400 | `Invalid Nonce` |
| Nonce has been used (replay attack) | 429 | `Replay Attack Detected` |
35 changes: 25 additions & 10 deletions src/content/docs/latest/zh-cn/plugins/authentication/ext-auth.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,7 @@ MatchRule 类型每一项的配置字段说明，在使用 `array of MatchRule`
| 名称 | 数据类型 | 必填 | 默认值 | 描述 |
| ------------------- | -------- | ---- | ------ | ------------------------------------------------------------ |
| `match_rule_domain` | string | 否 | - | 匹配规则域名，支持通配符模式，例如 `*.bar.com` |
| `match_rule_method` | []string | 否 | - | 匹配请求方法 |
| `match_rule_path` | string | 否 | - | 匹配请求路径的规则 |
| `match_rule_type` | string | 否 | - | 匹配请求路径的规则类型，可选 `exact` , `prefix` , `suffix`, `contains`, `regex` |

Expand All @@ -100,27 +101,41 @@ MatchRule 类型每一项的配置字段说明，在使用 `array of MatchRule`
**白名单模式**

```yaml
# 白名单模式配置，符合白名单规则的请求无需验证
match_type: 'whitelist'
match_list:
- match_rule_domain: '*.bar.com'
match_rule_path: '/foo'
match_rule_type: 'prefix'
# 所有以 api.example.com 为域名，且路径前缀为 /public 的请求无需验证
- match_rule_domain: 'api.example.com'
match_rule_path: '/public'
match_rule_type: 'prefix'
# 针对图片资源服务器 images.example.com，所有 GET 请求无需验证
- match_rule_domain: 'images.example.com'
match_rule_method: ["GET"]
# 所有域名下，路径精确匹配 /health-check 的 HEAD 请求无需验证
- match_rule_method: ["HEAD"]
match_rule_path: '/health-check'
match_rule_type: 'exact'
```

泛域名 `*.bar.com` 下前缀匹配 `/foo` 的请求无需验证

**黑名单模式**

```yaml
# 黑名单模式配置，符合黑名单规则的请求需要验证
match_type: 'blacklist'
match_list:
- match_rule_domain: '*.bar.com'
match_rule_path: '/headers'
match_rule_type: 'prefix'
# 所有以 admin.example.com 为域名，且路径前缀为 /sensitive 的请求需要验证
- match_rule_domain: 'admin.example.com'
match_rule_path: '/sensitive'
match_rule_type: 'prefix'
# 所有域名下，路径精确匹配 /user 的 DELETE 请求需要验证
- match_rule_method: ["DELETE"]
match_rule_path: '/user'
match_rule_type: 'exact'
# 所有以 legacy.example.com 为域名的 POST 请求需要验证
- match_rule_domain: 'legacy.example.com'
match_rule_method: ["POST"]
```

只有泛域名 `*.bar.com` 下前缀匹配 `/header` 的请求需要验证

## 配置示例

下面假设 `ext-auth` 服务在 Kubernetes 中 serviceName 为 `ext-auth`，端口 `8090`，路径为 `/auth`，命名空间为 `backend`
Expand Down
110 changes: 110 additions & 0 deletions src/content/docs/latest/zh-cn/plugins/security/replay-protection.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
---
title: 防重放攻击
keywords: [higress,replay-protection]
description: 防重放攻击插件配置参考
---

## 功能说明

防重放插件通过验证请求中的一次性随机数来防止请求重放攻击。每个请求都需要携带一个唯一的 nonce 值，服务器会记录并校验这个值的唯一性，从而防止请求被恶意重放

具体包含一下功能：

- **强制或可选的 nonce 校验**：可根据配置决定是否强制要求请求携带 nonce 值。
- **基于 Redis 的 nonce 唯一性验证**：通过 Redis 存储和校验 nonce 值，确保其唯一性。
- **可配置的 nonce 有效期**：支持设置 nonce 的有效期，过期后自动失效。
- **nonce 格式和长度校验**：支持对 nonce 值的格式（Base64）和长度进行验证。
- **自定义错误响应**：支持配置拒绝请求时的状态码和错误信息。
- **可自定义 nonce 请求头**：可以自定义携带 nonce 的请求头名称。

## 运行属性

插件执行阶段：`认证阶段`
插件执行优先级：`800`

## 配置字段

| 名称 | 数据类型 | 必填 | 默认值 | 描述 |
|----------------------|--------|------|-----------------|---------------------------------|
| `force_nonce` | bool | 否 | true | 是否强制要求请求携带 nonce 值 |
| `nonce_header` | string | 否 | `X-Higress-Nonce` | 指定携带 nonce 值的请求头名称 |
| `nonce_ttl` | int | 否 | 900 | nonce 的有效期，单位秒 |
| `nonce_min_length` | int | 否 | 8 | nonce 值的最小长度 |
| `nonce_max_length` | int | 否 | 128 | nonce 值的最大长度 |
| `reject_code` | int | 否 | 429 | 拒绝请求时返回的状态码 |
| `reject_msg` | string | 否 | `Replay Attack Detected` | 拒绝请求时返回的错误信息 |
| `validate_base64` | bool | 否 | false | 是否校验 nonce 的 base64 编码格式 |
| `redis` | Object | 是 | - | redis 相关配置 |

`redis` 中每一项的配置字段说明

| 名称 | 数据类型 | 必填 | 默认值 | 描述|
| -------------- | -------- | ---- |---------------------| --------------------------------------- |
| `service_name` | string | 是 | - | redis 服务名称，带服务类型的完整 FQDN 名称，例如 my-redis.dns、redis.my-ns.svc.cluster.local |
| `service_port` | int | 否 | 6379 | redis 服务端口|
| `username` | string | 否 | - | redis 用户名|
| `password` | string | 否 | - | redis 密码|
| `timeout` | int | 否 | 1000 | redis 连接超时时间，单位毫秒 |
| database | int | 否 | 0 | 使用的数据库id，例如配置为1，对应`SELECT 1`|
| `key_prefix` | string | 否 | `replay-protection` | redis 键前缀，用于区分不同的 nonce 键 |

## 配置示例

以下是一个防重放攻击插件的完整配置示例：

```yaml
force_nonce: true
nonce_header: "X-Higress-Nonce" # 指定 nonce 请求头名称
nonce_ttl: 900 # nonce 有效期，设置为 900 秒
nonce_min_length: 8 # nonce 的最小长度
nonce_max_length: 128 # nonce 的最大长度
validate_base64: true # 是否开启 base64 格式校验
reject_code: 429 # 当拒绝请求时返回的 HTTP 状态码
reject_msg: "Replay Attack Detected" # 拒绝请求时返回的错误信息内容
redis:
service_name: redis.static # Redis 服务的名称
service_port: 80 # Redis 服务所使用的端口
timeout: 1000 # Redis 操作的超时时间（单位：毫秒）
key_prefix: "replay-protection" # Redis 中键的前缀
```

## 使用说明

### 请求头要求

| 请求头名称 | 是否必须 | 说明 |
|-----------------|----------------|------------------------------------------|
| `X-Higress-Nonce` | 根据 `force_nonce` 配置决定 | 请求中携带的随机生成的 nonce 值，需符合 Base64 格式。 |

> **注意**：可以通过 `nonce_header` 配置自定义请求头名称，默认值为 `X-Higress-Nonce`。

### 使用示例

```bash
# Generate nonce
nonce=$(openssl rand -base64 32)

# Send request
curl -X POST 'https://api.example.com/path' \
-H "X-Higress-Nonce: $nonce" \
-d '{"key": "value"}'
```

## 返回结果

```json
{
"code": 429,
"message": "Replay Attack Detected"
}
```

## 错误响应示例

| 错误场景 | 状态码 | 错误信息 |
|------------------------|-------|--------------------|
| 缺少 nonce 请求头 | 400 | `Missing Required Header` |
| nonce 长度不符合要求 | 400 | `Invalid Nonce` |
| nonce 格式不符合 Base64 | 400 | `Invalid Nonce` |
| nonce 已被使用（重放攻击） | 429 | `Replay Attack Detected` |