doc: add missed chinese readme for extensions (#3890)

Signed-off-by: zhoujinyu <2319109590@qq.com>
This commit is contained in:
FAUST
2026-06-07 12:26:08 +08:00
committed by GitHub
parent 57db9ccc46
commit b69b5c7c10
7 changed files with 325 additions and 0 deletions

View File

@@ -0,0 +1,84 @@
# 功能说明
`jwt-auth` 插件基于 JWT 对请求进行认证鉴权,支持内联 JWKS 或远程 JWKS 拉取可从请求头、URL 参数或 Cookie 中提取 Token校验通过后可把 Payload 中的 Claim 写入请求头转发给后端。
更完整的说明见官方文档:[JWT 认证插件](https://higress.io/zh-cn/docs/plugins/jwt-auth)。
# 运行属性
插件执行阶段:认证阶段
# 配置字段
## 全局配置
| 名称 | 数据类型 | 填写要求 | 默认值 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| consumers | array of object | 必填 | - | 调用方Consumer列表至少配置一项 |
| global_auth | bool | 选填 | - | `true` 全局生效;`false` 仅对配置了 `_rules_` 的域名/路由生效;未配置时无规则则全局生效 |
### consumers 项
| 名称 | 数据类型 | 填写要求 | 默认值 | 描述 |
| -------- | -------- | -------- | -------- | -------- |
| name | string | 必填 | - | Consumer 名称 |
| issuer | string | 必填 | - | JWT 签发者,需与 payload 中 `iss` 一致 |
| jwks | string | 与 remote_jwks 二选一 | - | 内联 JWKS JSON 字符串 |
| remote_jwks | object | 与 jwks 二选一 | - | 远程 JWKS 端点(需 Higress 可发现的服务) |
| jwks_cache_duration | number | 选填 | 600 | 远程 JWKS 缓存时间(秒) |
| jwks_fetch_timeout | number | 选填 | 1500 | 远程 JWKS 拉取超时(毫秒) |
| claims_to_headers | array of object | 选填 | - | 将 Claim 写入请求头 |
| from_headers | array of object | 选填 | Authorization: Bearer | 从请求头提取 JWT |
| from_params | array of string | 选填 | access_token | 从 URL 参数提取 JWT |
| from_cookies | array of string | 选填 | - | 从 Cookie 提取 JWT |
| clock_skew_seconds | number | 选填 | 60 | 校验 `exp`/`iat` 的时钟偏移(秒) |
| keep_token | bool | 选填 | true | 转发时是否保留原 JWT |
### remote_jwks
| 名称 | 数据类型 | 填写要求 | 描述 |
| -------- | -------- | -------- | -------- |
| service_name | string | 必填 | Higress 服务名(如 `issuer.example.com.dns` |
| service_host | string | 选填 | JWKS 请求的 Host |
| service_port | number | 选填 | 端口,默认 443 |
| path | string | 必填 | JWKS 路径,如 `/.well-known/jwks.json` |
### claims_to_headers 项
| 名称 | 数据类型 | 描述 |
| -------- | -------- | -------- |
| claim | string | JWT payload 中的字段名 |
| header | string | 写入的请求头名 |
| override | bool | 是否覆盖同名请求头,默认 true |
## 路由/域名级配置_rules_
| 名称 | 数据类型 | 填写要求 | 描述 |
| -------- | -------- | -------- | -------- |
| allow | array of string | 必填 | 允许访问的 consumer 名称列表 |
# 配置示例
```yaml
consumers:
- name: example-consumer
issuer: https://issuer.example.com
remote_jwks:
service_name: issuer.example.com.dns
service_host: issuer.example.com
service_port: 443
path: /.well-known/jwks.json
jwks_cache_duration: 600
jwks_fetch_timeout: 1500
- name: inline-consumer
issuer: https://issuer.example.com
jwks: '{"keys":[...]}'
```
```yaml
_rules_:
- _match_route_:
- route-a
allow:
- example-consumer
```