diff --git a/src/content/docs/latest/en/plugins/authentication/ext-auth.md b/src/content/docs/latest/en/plugins/authentication/ext-auth.md index f65388266a..8a01216009 100644 --- a/src/content/docs/latest/en/plugins/authentication/ext-auth.md +++ b/src/content/docs/latest/en/plugins/authentication/ext-auth.md @@ -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` | @@ -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 @@ -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 diff --git a/src/content/docs/latest/en/plugins/security/replay-protection.md b/src/content/docs/latest/en/plugins/security/replay-protection.md new file mode 100644 index 0000000000..434003f833 --- /dev/null +++ b/src/content/docs/latest/en/plugins/security/replay-protection.md @@ -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` | diff --git a/src/content/docs/latest/zh-cn/plugins/authentication/ext-auth.md b/src/content/docs/latest/zh-cn/plugins/authentication/ext-auth.md index f19d095764..de7e2feb83 100644 --- a/src/content/docs/latest/zh-cn/plugins/authentication/ext-auth.md +++ b/src/content/docs/latest/zh-cn/plugins/authentication/ext-auth.md @@ -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` | @@ -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` diff --git a/src/content/docs/latest/zh-cn/plugins/security/replay-protection.md b/src/content/docs/latest/zh-cn/plugins/security/replay-protection.md new file mode 100644 index 0000000000..785f5e51b0 --- /dev/null +++ b/src/content/docs/latest/zh-cn/plugins/security/replay-protection.md @@ -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` | +