This is an automated email from the ASF dual-hosted git repository.
sylviasu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new 8df9a7d26 docs: update "Authentication" Plugins (#6895)
8df9a7d26 is described below
commit 8df9a7d26585f30f273f819a21c96cf8c9104349
Author: homeward <[email protected]>
AuthorDate: Tue Apr 26 16:40:54 2022 +0800
docs: update "Authentication" Plugins (#6895)
* docs: update Authentication Plugins
---
docs/zh/latest/plugins/authz-casbin.md | 100 ++++++++------
docs/zh/latest/plugins/authz-keycloak.md | 152 ++++++++++++++-------
docs/zh/latest/plugins/basic-auth.md | 85 ++++++------
docs/zh/latest/plugins/forward-auth.md | 79 +++++++----
docs/zh/latest/plugins/hmac-auth.md | 224 +++++++++++++++----------------
docs/zh/latest/plugins/jwt-auth.md | 214 ++++++++++++++++++-----------
docs/zh/latest/plugins/key-auth.md | 90 ++++++++-----
docs/zh/latest/plugins/openid-connect.md | 122 ++++++++++-------
docs/zh/latest/plugins/wolf-rbac.md | 129 +++++++++++-------
9 files changed, 713 insertions(+), 482 deletions(-)
diff --git a/docs/zh/latest/plugins/authz-casbin.md
b/docs/zh/latest/plugins/authz-casbin.md
index 0f700893f..a224212cc 100644
--- a/docs/zh/latest/plugins/authz-casbin.md
+++ b/docs/zh/latest/plugins/authz-casbin.md
@@ -1,5 +1,11 @@
---
title: authz-casbin
+keywords:
+ - APISIX
+ - Plugin
+ - Authz Casbin
+ - authz-casbin
+description: 本文介绍了关于 Apache APISIX `authz-casbin` 插件的基本信息及使用方法。
---
<!--
@@ -23,37 +29,44 @@ title: authz-casbin
## 描述
-`authz-casbin` 是一个基于 [Lua Casbin](https://github.com/casbin/lua-casbin/)
的访问控制插件，该插件支持基于各种访问控制模型的授权场景。
-
-有关如何创建鉴权模型和鉴权策略的详细文档，请参阅 [Casbin](https://casbin.org/docs/en/supported-models)。
+`authz-casbin` 插件是一个基于 [Lua Casbin](https://github.com/casbin/lua-casbin/)
的访问控制插件，该插件支持各种 [access control
models](https://casbin.org/docs/en/supported-models) 的强大授权场景。
## 属性
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| ----------- | ------ | ------ | ------- | ----- |
--------------------------- |
-| model_path | string | 必须 | | | Casbin 鉴权模型配置文件路径 |
-| policy_path | string | 必须 | | | Casbin 鉴权策略配置文件路径 |
-| model | string | 必须 | | | Casbin 鉴权模型的文本定义 |
-| policy | string | 必须 | | | Casbin 鉴权策略的文本定义 |
-| username | string | 必须 | | | 描述请求中有可以通过访问控制的用户名 |
+| 名称 | 类型 | 必选项 | 描述 |
+| ----------- | ------ | ------- | ---------------------------------- |
+| model_path | string | 是 | Casbin 鉴权模型配置文件路径。 |
+| policy_path | string | 是 | Casbin 鉴权策略配置文件路径。 |
+| model | string | 是 | Casbin 鉴权模型的文本定义。 |
+| policy | string | 是 | Casbin 鉴权策略的文本定义。 |
+| username | string | 是 | 描述请求中有可以通过访问控制的用户名。 |
+
+:::note
+
+你必须在插件配置中指定 `model_path`、`policy_path` 和 `username` 或者指定 `model`、`policy` 和
`username` 才能使插件生效。
+
+如果你想要使所有的 Route 共享 Casbin 配置，你可以先在插件元数据中指定 `model` 和 `policy`，在插件配置中仅指定
`username`，这样所有 Route 都可以使用 Casbin 插件配置。
-**注意**: 在插件配置中指定 `model_path`、`policy_path` 和 `username`，或者在插件配置中指定
`model`、`policy` 和 `username` 来使插件生效。如果想要使所有的路由共享 Casbin
配置，可以先在插件元数据中指定鉴权模型和鉴权策略，然后在指定路由的插件配置中指定 `username`。
+::::
## 元数据
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| ----------- | ------ | ------ | ----- | ----- | ------------------ |
-| model | string | 必须 | | | Casbin 鉴权模型的文本定义 |
-| policy | string | 必须 | | | Casbin 鉴权策略的文本定义 |
+| 名称 | 类型 | 必选项 | 描述 |
+| ----------- | ------ | ------- | ------------------------------|
+| model | string | 是 | Casbin 鉴权模型的文本定义。 |
+| policy | string | 是 | Casbin 鉴权策略的文本定义。 |
-## 如何启用
+## 启用插件
-该插件可以通过在任意路由上配置 `鉴权模型/鉴权策略文件路径` 或 `鉴权模型/鉴权策略文本` 来启用。
+你可以使用 model/policy 文件路径或使用插件 configuration/metadata 中的 model/policy 文本配置在
Route 上启用插件。
-### 通过配置文件启用
+### 通过 model/policy 文件路径启用插件
+
+以下示例展示了通过 model/policy 配置文件来设置 Casbin 身份验证：
```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"plugins": {
"authz-casbin": {
@@ -72,12 +85,13 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f13
}'
```
-上述请求会根据鉴权模型/鉴权策略文件中的定义创建一个 Casbin enforcer。
+### 通过 model/policy 文本配置启用插件
-### 通过路由配置启用
+以下示例展示了通过你的 model/policy 文本来设置 Casbin 身份验证：
```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"plugins": {
"authz-casbin": {
@@ -113,14 +127,15 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f13
}'
```
-上述请求会根据鉴权模型和鉴权策略的定义创建一个 Casbin enforcer。
-
### 通过 plugin metadata 配置模型/策略
-首先，使用 Admin API 发送一个 `PUT`
请求，将鉴权模型和鉴权策略的配置信息添加到插件的元数据中。所有通过这种方式创建的路由都会带有一个带插件元数据配置的 Casbin
enforcer。同时也可以使用 `PUT` 请求更新鉴权模型和鉴权策略配置信息，该插件将会自动同步最新的配置信息。
+首先，我们需要使用 Admin API 发送一个 `PUT` 请求，将 `model` 和 `policy` 的配置添加到插件的元数据中。
+
+所有通过这种方式创建的 Route 都会带有一个带插件元数据配置的 Casbin enforcer。你也可以使用这种方式更新
model/policy，该插件将会自动同步最新的配置信息。
```shell
-curl http://127.0.0.1:9080/apisix/admin/plugin_metadata/authz-casbin -H
'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -i -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/plugin_metadata/authz-casbin \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -i -X PUT -d '
{
"model": "[request_definition]
r = sub, obj, act
@@ -143,10 +158,11 @@ g, alice, admin"
}'
```
-通过发送以下请求可以将该插件添加到路由上。注意，此处只需要配置 `username`，不需要再增加鉴权模型/鉴权策略的定义。
+更新插件元数据后，可以将插件添加到指定 Route 中：
```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"plugins": {
"authz-casbin": {
@@ -163,7 +179,11 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f13
}'
```
-**注意**:
插件路由配置比插件元数据配置有更高的优先级。因此，如果插件路由配置中存在鉴权模型/鉴权策略配置，插件将优先使用插件路由的配置而不是插件元数据中的配置。
+:::note
+
+插件路由的配置比插件元数据的配置有更高的优先级。因此，如果插件路由的配置中存在 model/policy
配置，插件将优先使用插件路由的配置而不是插件元数据中的配置。
+
+:::
## 测试插件
@@ -194,22 +214,27 @@ p, admin, *, *
g, alice, admin
```
-以上授权策略规定了任何人都可以使用 `GET` 请求方法访问主页（`/`），而只有具有管理权限的用户可以访问其他页面和使用其他请求方法。
+如果想要了解更多关于 `policy` 和 `model` 的配置，请参考
[examples](https://github.com/casbin/lua-casbin/tree/master/examples)。
+
+上述配置将允许所有人使用 `GET` 请求访问主页（`/`），而只有具有管理员权限的用户才可以访问其他页面并使用其他请求方法。
-例如，在这里，任何人都可以用 `GET` 请求方法访问主页，返回正常。
+简单举例来说，假设我们向主页发出 `GET` 请求，通常都可以返回正常结果。
```shell
curl -i http://127.0.0.1:9080/ -X GET
```
-未经授权的用户如 `bob` 访问除 `/` 以外的任何其他页面将得到一个 403 错误：
+但如果是一个未经授权的普通用户（例如：`bob`）访问除 `/` 以外的其他页面，将得到一个 403 错误：
```shell
curl -i http://127.0.0.1:9080/res -H 'user: bob' -X GET
+```
+
+```
HTTP/1.1 403 Forbidden
```
-拥有管理权限的人 `alice` 则可以访问其它页面。
+而拥有管理权限的用户（如 `alice`）则可以访问其它页面。
```shell
curl -i http://127.0.0.1:9080/res -H 'user: alice' -X GET
@@ -217,10 +242,11 @@ curl -i http://127.0.0.1:9080/res -H 'user: alice' -X GET
## 禁用插件
-在插件配置中删除相应的 json 配置，以禁用 `authz-casbin` 插件。由于 Apache APISIX 插件是热加载的，因此不需要重新启动
Apache APISIX。
+当你需要禁用 `authz-casbin` 插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
"uri": "/*",
@@ -233,7 +259,3 @@ $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335
}
}'
```
-
-## 示例
-
-更多鉴权模型和鉴权策略使用的例子请参考 [Casbin
示例](https://github.com/casbin/lua-casbin/tree/master/examples)。
diff --git a/docs/zh/latest/plugins/authz-keycloak.md
b/docs/zh/latest/plugins/authz-keycloak.md
index c715e81a8..7cc1ae7fc 100644
--- a/docs/zh/latest/plugins/authz-keycloak.md
+++ b/docs/zh/latest/plugins/authz-keycloak.md
@@ -1,5 +1,11 @@
---
title: authz-keycloak
+keywords:
+ - APISIX
+ - Plugin
+ - Authz Keycloak
+ - authz-keycloak
+description: 本文介绍了关于 Apache APISIX `authz-keycloak` 插件的基本信息及使用方法。
---
<!--
@@ -23,43 +29,109 @@ title: authz-keycloak
## 描述
-目前 `authz-plugin` 仅支持通过定义资源名和访问权限范畴来应用 `route` 的访问策略。但是 Keycloak 官方适配的其他语言的客户端
(Java, JS) 还可以通过动态查询 Keycloak 路径以及懒加载身份资源的路径来支持路径匹配。未来版本的 `authz-plugin`
将会支持这项功能。
+`authz-keycloak` 插件可用于通过 [Keycloak Identity Server](https://www.keycloak.org/)
添加身份验证。
+
+:::tip
+
+虽然该插件是为了与 Keycloak 一起使用而开发的，但是它也可以与任何符合 OAuth/OIDC 或 UMA 协议的身份认证软件一起使用。
+
+:::
+
+如果你想了解 Keycloak 的更多信息，请参考 [Authorization Services
Guide](https://www.keycloak.org/docs/latest/authorization_services/)。
## 属性
-| 名称 | 类型 | 必选项 | 默认值 | 有效值
| 描述 |
-| ----------------------- | ------------- | ------ | ----------- |
--------------------------- |----------------------|
-| token_endpoint | string | 必须 | |
| 接受 OAuth2 兼容 token 的接口，需要支持
`urn:ietf:params:oauth:grant-type:uma-ticket` 授权类型 |
-| grant_type | string | 可选 |
"urn:ietf:params:oauth:grant-type:uma-ticket" |
["urn:ietf:params:oauth:grant-type:uma-ticket"] | |
-| audience | string | 可选 | |
| 客户端应用访问相应的资源服务器时所需提供的身份信息。当 permissions 参数有值时这个参数是必填的。 |
-| permissions | array[string] | 可选 | |
| 描述客户端应用所需访问的资源和权限范围的字符串。格式必须为：`RESOURCE_ID#SCOPE_ID` |
-| timeout | integer | 可选 | 3000 | [1000,
...] | 与身份认证服务器的 http 连接的超时时间 |
-| access_token_expires_in | integer | 可选 | 300 | [1, ...]
| access token 的过期时间（秒）|
-| access_token_expires_leeway | integer | 可选 | 0 | [0, ...]
| access token 提前更新时间（秒，如果设置了此值，允许在该时间段内使用相同的 access
token 令牌来解决潜在的网络并发问题）|
-| refresh_token_expires_in | integer | 可选 | 3600 | [1, ...]
| refresh token 的过期时间（秒）|
-| refresh_token_expires_leeway| integer | 可选 | 0 | [0, ...]
| refresh token 提前更新时间（秒，如果设置了此值，允许在该时间段内使用相同的
refresh token 令牌来解决潜在的网络并发问题）|
-| ssl_verify | boolean | 可选 | true | [0, ...]
| 验证 SSL 证书与主机名是否匹配 |
-| policy_enforcement_mode | string | 可选 | "ENFORCING" |
["ENFORCING", "PERMISSIVE"] | |
-| access_denied_redirect_uri | string | 可选 | | [1, 2048]
| 未授权的用户不会返回
`"error_description":"not_authorized"`，而是会定重定向至给定的 uri，如
"http://127.0.0.1/test";|
+| 名称 | 类型 | 必选项 | 默认值
| 有效值
| 描述
|
+|----------------------------------------------|---------------|-------|-----------------------------------------------|--------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| discovery | string | 否 |
|
https://host.domain/auth/realms/foo/.well-known/uma2-configuration | Keycloak
授权服务的 [discovery
document](https://www.keycloak.org/docs/14.0/authorization_services/#_service_authorization_api)
的 URL。
|
+| token_endpoint | string | 否 |
|
https://host.domain/auth/realms/foo/protocol/openid-connect/token | 接受 OAuth2
兼容 token 的接口，需要支持 `urn:ietf:params:oauth:grant-type:uma-ticket` 授权类型。
|
+| resource_registration_endpoint | string | 否 |
|
https://host.domain/auth/realms/foo/authz/protection/resource_set | 符合 UMA
的资源注册端点。如果提供，则覆盖发现中的值。
|
+| client_id | string | 否 |
|
| 客户端正在寻求访问的资源服务器的标识符。需要 `client_id` 或 `audience`。
|
+| audience | string | 否 |
|
| 遗留参数。现在被 `client_id` 替换，以保持向后兼容性。需要 `client_id` 或
`audience`。
|
+| client_secret | string | 否 |
|
| 客户端密码（如果需要）。
|
+| grant_type | string | 否 |
"urn:ietf:params:oauth:grant-type:uma-ticket" |
["urn:ietf:params:oauth:grant-type:uma-ticket"] |
|
+| policy_enforcement_mode | string | 否 |
"ENFORCING" | ["ENFORCING", "PERMISSIVE"]
|
|
+| permissions | array[string] | 否 |
|
|
描述客户端应用所需访问的资源和权限范围的字符串。格式必须为：`RESOURCE_ID#SCOPE_ID`。
|
+| lazy_load_paths | boolean | 否 | false
| [true, false]
| 当设置为 true 时，使用资源注册端点而不是静态权限将请求 URI 动态解析为资源。
|
+| http_method_as_scope | boolean | 否 | false
| [true, false]
| 设置为 true 时，将 HTTP 请求类型映射到同名范围并添加到所有请求的权限。
|
+| timeout | integer | 否 | 3000
| [1000, ...]
| 与 Identity Server 的 HTTP 连接超时（毫秒）。
|
+| access_token_expires_in | integer | 否 | 300
| [1, ...]
| 访问令牌的有效期。 token.
|
+| access_token_expires_leeway | integer | 否 | 0
| [0, ...]
| access_token 更新的到期余地。设置后，令牌将在到期前几秒更新
access_token_expires_leeway。这避免了 access_token 在到达 OAuth 资源服务器时刚刚过期的情况。 |
+| refresh_token_expires_in | integer | 否 | 3600
| [1, ...]
| 刷新令牌的失效时间。
|
+| refresh_token_expires_leeway | integer | 否 | 0
| [0, ...]
| refresh_token 更新的到期余地。设置后，令牌将在到期前几秒刷新
refresh_token_expires_leeway。这样可以避免在到达 OAuth 资源服务器时 refresh_token 刚刚过期的错误。 |
+| ssl_verify | boolean | 否 | true
| [true, false]
| 设置为 `true` 时，验证 TLS 证书是否与主机名匹配。
|
+| cache_ttl_seconds | integer | 否 | 86400
(equivalent to 24h) | positive integer >= 1
| 插件缓存插件用于向 Keycloak 进行身份验证的发现文档和令牌的最长时间（以秒为单位）。
|
+| keepalive | boolean | 否 | true
| [true, false]
| 当设置为 `true` 时，启用 HTTP keep-alive
保证在使用后仍然保持连接打开。如果您期望对 Keycloak 有很多请求，请设置为 `true`。
|
+| keepalive_timeout | integer | 否 | 60000
| positive integer >= 1000
| 已建立的 HTTP 连接将关闭之前的空闲时间。
|
+| keepalive_pool | integer | 否 | 5
| positive integer >= 1
| 连接池中的最大连接数。
|
+| access_denied_redirect_uri | string | 否 |
| [1, 2048]
| 需要将用户重定向到的 URI，而不是返回类似
`"error_description":"not_authorized"` 这样的错误消息。
|
+| password_grant_token_generation_incoming_uri | string | 否 |
| /api/token
| 将此设置为使用密码授予类型生成令牌。该插件会将传入的请求 URI 与此值进行比较。
|
+
+除上述释义外，还有以下需要注意的点：
+
+- Discovery and endpoints
+ - 使用 `discovery` 属性后，`authz-keycloak` 插件就可以从其 URL 中发现 Keycloak API 的端点。该
URL 指向 Keyloak 针对相应领域授权服务的发现文档。
+ - 如果发现文档可用，则插件将根据该文档确定令牌端点 URL。如果 URL 存在，则 `token_endpoint` 和
`resource_registration_endpoint` 的值将被其覆盖。
+- Client ID and secret
+ - 该插件需配置 `client_id` 或 `audience`（用于向后兼容）属性来标识自身，如果两者都已经配置，则 `client_id`
优先级更高。
+ - 如果 `lazy_load_paths` 属性被设置为 `true`，那么该插件还需要从 Keycloak
中获得一个自身访问令牌。在这种情况下，如果客户端对 Keycloak 的访问是加密的，就需要配置 `client_secret` 属性。
+- Policy enforcement mode
+ - `policy_enforcement_mode` 属性指定了在处理发送到服务器的授权请求时，该插件如何执行策略。
+ - `ENFORCING` mode：即使没有与给定资源关联的策略，请求也会默认被拒绝。`policy_enforcement_mode`
默认设置为 `ENFORCING`。
+ - `PERMISSIVE` mode：如果资源没有绑定任何访问策略，也被允许请求。
+- Permissions
+ - 在处理传入的请求时，插件可以根据请求的参数确定静态或动态检查 Keycloak 的权限。
+ - 如果 `lazy_load_paths` 参数设置为 `false`，则权限来自 `permissions` 属性。`permissions`
中的每个条目都需要按照令牌端点预设的 `permission` 属性进行格式化。详细信息请参考 [Obtaining
Permissions](https://www.keycloak.org/docs/latest/authorization_services/index.html#_service_obtaining_permissions).
+
+ :::note
+
+ 有效权限可以是单个资源，也可以是与一个或多个范围配对的资源。
+
+ :::
+
+ 如果 `lazy_load_paths` 属性设置为 `true`，则请求 URI 将解析为使用资源注册端点在 Keycloak
中配置的一个或多个资源。已经解析的资源被用作于检查的权限。
+
+ :::note
+
+ 需要该插件从令牌端点为自己获取单独的访问令牌。因此，请确保在 Keycloak 的客户端设置中设置了 `Service Accounts
Enabled` 选项。
+
+ 还需要确保颁发的访问令牌包含具有 `uma_protection` 角色的 `resource_access` 声明，以保证插件能够通过
Protection API 查询资源。
-### 策略执行模式
+ :::
-定义了在处理身份认证请求时如何应用策略
+- 自动将 HTTP method 映射到作用域
-**Enforcing**
+ `http_method_as_scope` 通常与 `lazy_load_paths` 一起使用，但也可以与静态权限列表一起使用。
-- 默认模式，如果资源没有绑定任何访问策略，请求默认会被拒绝。
+ - 如果 `http_method_as_scope` 属性设置为 `true`，插件会将请求的 HTTP
方法映射到同名范围。然后将范围添加到每个要检查的权限。
-**Permissive**
+ - 如果 `lazy_load_paths` 属性设置为 `false`，则插件会将映射范围添加到 `permissions`
属性中配置的任意一个静态权限——即使它们已经包含一个或多个范围。
-- 如果资源没有绑定任何访问策略，请求会被允许。
+- 使用 `password` 授权生成令牌
+
+ - 如果要使用 `password` 授权生成令牌，你可以设置
`password_grant_token_generation_incoming_uri` 属性的值。
+
+ - 如果传入的 URI 与配置的属性匹配并且请求方法是 POST，则使用 `token_endpoint` 生成一个令牌。
+
+ 同时，你还需要添加 `application/x-www-form-urlencoded` 作为 `Content-Type`
标头，`username` 和 `password` 作为参数。
+
+ 如下示例是当 `password_grant_token_generation_incoming_uri` 设置为 `/api/token`
时的命令：
+
+ ```shell
+ curl --location --request POST 'http://127.0.0.1:9080/api/token' \
+ --header 'Accept: application/json, text/plain, */*' \
+ --header 'Content-Type: application/x-www-form-urlencoded' \
+ --data-urlencode 'username=<User_Name>' \
+ --data-urlencode 'password=<Password>'
+ ```
## 如何启用
-创建一个 `route` 对象，并在该 `route` 对象上启用 `authz-keycloak` 插件，`${realm}` 是 `Keycloak`
中的 `realm` 名称：
+以下示例为你展示了如何在指定 Route 中启用 `authz-keycloak` 插件，其中 `${realm}` 是 Keycloak 中的
`realm` 名称：
```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/get",
"plugins": {
@@ -80,29 +152,32 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H
'X-API-KEY: edd1c9f034335f13
## 测试插件
-获取 `{JWT Token}`
+通过上述命令启用插件后，可以通过以下方法测试插件。
+
+首先需要从 Keycloak 获取 JWT 令牌：
```shell
curl \
-d "client_id=<YOUR_CLIENT_ID>" \
-d "username=<YOUR_USERNAMED>" \
-d "password=<YOUR_PASSWORD>" \
- -d "grant_type=password" \
-
"http://<YOUR_KEYCLOAK_HOST>/auth/realms/${realm}/protocol/openid-connect/token"
+ -d "grant_type=password"
"http://<YOUR_KEYCLOAK_HOST>/auth/realms/${realm}/protocol/openid-connect/token"
```
-验证
+之后就可以使用获得的 JWT 令牌发起请求：
```shell
-curl http://127.0.0.1:9080/get -H 'Authorization: Bearer {JWT Token}'
+curl http://127.0.0.1:9080/get \
+-H 'Authorization: Bearer {JWT Token}'
```
## 禁用插件
-在插件设置页面中删除相应的 json 配置即可禁用 `authz-keycloak` 插件。APISIX 的插件是热加载的，因此无需重启 APISIX 服务。
+当你需要禁用 `authz-keycloak` 插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/get",
"plugins": {
@@ -116,21 +191,8 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H
'X-API-KEY: edd1c9f034335f13
}'
```
-## 示例
-
-请查看 authz-keycloak.t 中的单元测试来了解如何将身份认证策略与您的 API 工作流集成。运行以下 docker 镜像并访问
`http://localhost:8090` 来查看单元测试中绑定的访问策略：
-
-```bash
-docker run -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=123456 -p 8090:8080
sshniro/keycloak-apisix
-```
-
-下面这张截图显示了如何在 Keycloak 服务器上配置访问策略：
-
-
-
-## 后续开发
+## 插件 Roadmap
-- 目前 `authz-plugin` 仅支持通过定义资源名和访问权限范畴来应用 `route` 的访问策略。但是 Keycloak
官方适配的其他语言的客户端 (Java, JS) 还可以通过动态查询 Keycloak
- 路径以及懒加载身份资源的路径来支持路径匹配。未来版本的 `authz-plugin` 将会支持这项功能。
+- 目前，`authz-keycloak` 插件通过要求定义资源名称和所需的范围，来强制执行路由策略。但 Keycloak
官方适配的其他语言客户端（Java、JavaScript）仍然可以通过动态查询 Keycloak 路径以及延迟加载身份资源的路径来提供路径匹配。在
Apache APISIX 之后发布的插件中即将支持此功能。
- 支持从 Keycloak JSON 文件中读取权限范畴和其他配置项。
diff --git a/docs/zh/latest/plugins/basic-auth.md
b/docs/zh/latest/plugins/basic-auth.md
index 739b0485a..f95167adc 100644
--- a/docs/zh/latest/plugins/basic-auth.md
+++ b/docs/zh/latest/plugins/basic-auth.md
@@ -1,5 +1,11 @@
---
title: basic-auth
+keywords:
+ - APISIX
+ - Plugin
+ - Basic Auth
+ - basic-auth
+description: 本文介绍了关于 Apache APISIX `basic-auth` 插件的基本信息及使用方法。
---
<!--
@@ -23,33 +29,32 @@ title: basic-auth
## 描述
-`basic-auth` 是一个认证插件，它需要与 `consumer` 一起配合才能工作。
+使用 `basic-auth` 插件可以将
[Basic_access_authentication](https://en.wikipedia.org/wiki/Basic_access_authentication)
添加到 Route 或 Service 中。
-添加 Basic Authentication 到一个 `service` 或 `route`。 然后 `consumer`
将其用户名和密码添加到请求头中以验证其请求。
-
-有关 Basic Authentication 的更多信息，可参考
[维基百科](https://zh.wikipedia.org/wiki/HTTP%E5%9F%BA%E6%9C%AC%E8%AE%A4%E8%AF%81)
查看更多信息。
+该插件需要与 [Consumer](../architecture-design/consumer.md) 一起使用。API
的消费者可以将它们的密钥添加到请求头中以验证其请求。
## 属性
-consumer 端配置：
+Consumer 端：
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述
|
-| -------- | ------ | ------ | ------ | ------ |
------------------------------------------------------------------------------------------------------------------
|
-| username | string | 必须 | | | 不同的 `consumer`
对象应有不同的值，它应当是唯一的。不同 consumer 使用了相同的 `username` ，将会出现请求匹配异常。 |
-| password | string | 必须 | | | 用户的密码
|
+| 名称 | 类型 | 必选项 | 描述
|
+| -------- | ------ | -----|
-----------------------------------------------------------------------------------------------
|
+| username | string | 是 | Consumer 的用户名并且该用户名是唯一，如果多个 Consumer 使用了相同的
`username`，将会出现请求匹配异常。|
+| password | string | 是 | 用户的密码。
|
-router 端配置：
+Route 端：
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述
|
-| -------- | ------ | ------ | ------ | ------ |
------------------------------------------------------------------------------------------------------------------
|
-| hide_credentials | boolean | 可选 | false | | 是否将 Authorization
请求头传递给 upstream。
|
+| 名称 | 类型 | 必选项 | 默认值 | 描述
|
+| ---------------- | ------- | ------ | ------ |
--------------------------------------------------------------- |
+| hide_credentials | boolean | 否 | false | 该参数设置为 `true` 时，则会将
Authorization 请求头传递给 Upstream。|
-## 如何启用
+## 启用插件
-### 1. 创建一个 consumer 对象，并设置插件 `basic-auth` 的值。
+如果需要启用插件，就必须创建一个具有身份验证配置的 Consumer：
```shell
-curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/consumers \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"username": "foo",
"plugins": {
@@ -61,18 +66,19 @@ curl http://127.0.0.1:9080/apisix/admin/consumers -H
'X-API-KEY: edd1c9f034335f1
}'
```
-你也可以通过 web 界面来完成上面的操作，先增加一个 consumer：
-
-
+你也可以通过 [APISIX Dashboard](/docs/dashboard/USER_GUIDE) 完成上述操作。
-然后在 consumer 页面中添加 basic-auth 插件：
+<!--
+
-
+
+-->
-### 2. 创建 Route 或 Service 对象，并开启 `basic-auth` 插件。
+创建 Consumer 后，就可以通过配置 Route 或 Service 来验证插件，以下是配置 Route 的命令：
```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
"uri": "/hello",
@@ -90,50 +96,43 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f13
## 测试插件
-- 缺少 Authorization header
+通过上述命令启用插件后，可以通过以下方法测试插件。
```shell
-$ curl -i http://127.0.0.1:9080/hello
-HTTP/1.1 401 Unauthorized
-...
-{"message":"Missing authorization in request"}
+curl -i -ubar:bar http://127.0.0.1:9080/hello
```
-- 用户名不存在：
+如果配置成功则返回如下结果：
```shell
-$ curl -i -ubar:bar http://127.0.0.1:9080/hello
-HTTP/1.1 401 Unauthorized
+HTTP/1.1 200 OK
...
-{"message":"Invalid user authorization"}
+hello, world
```
-- 密码错误：
+如果请求未授权，则返回如下结果：
```shell
-$ curl -i -ufoo:foo http://127.0.0.1:9080/hello
HTTP/1.1 401 Unauthorized
...
-{"message":"Invalid user authorization"}
-...
+{"message":"Missing authorization in request"}
```
-- 成功请求：
+如果用户名和密码错则返回如下结果：
```shell
-$ curl -i -ufoo:bar http://127.0.0.1:9080/hello
-HTTP/1.1 200 OK
-...
-hello, foo!
+HTTP/1.1 401 Unauthorized
...
+{"message":"Invalid user authorization"}
```
## 禁用插件
-当你想去掉 `basic-auth` 插件的时候，很简单，在插件的配置中把对应的 `json` 配置删除即可，无须重启服务，即刻生效：
+当你需要禁用 `basic-auth` 插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
"uri": "/hello",
diff --git a/docs/zh/latest/plugins/forward-auth.md
b/docs/zh/latest/plugins/forward-auth.md
index 4a3f6d394..b2dd8cf41 100644
--- a/docs/zh/latest/plugins/forward-auth.md
+++ b/docs/zh/latest/plugins/forward-auth.md
@@ -1,7 +1,12 @@
---
title: forward-auth
+keywords:
+ - APISIX
+ - Plugin
+ - Forward Authentication
+ - forward-auth
+description: 本文介绍了关于 Apache APISIX `forward-auth` 插件的基本信息及使用方法。
---
-
<!--
#
# Licensed to the Apache Software Foundation (ASF) under one or more
@@ -23,36 +28,36 @@ title: forward-auth
## 描述
-`forward-auth` 插件使用的是经典外部认证。在认证失败的时候，我们可以实现自定义错误或者重定向到认证页面。
+`forward-auth` 插件使用的是经典外部认证。当身份认证失败时，可以实现自定义错误或者重定向到认证页面的场景。
-Forward Auth 巧妙地将认证和授权逻辑移到了一个专门的外部服务中，网关将用户的请求转发给认证服务并阻塞原始请求，并在认证服务以非 2xx
状态响应时替换结果。
+`forward-auth` 插件巧妙地将身份认证和授权逻辑移到了一个专门的外部服务中，APISIX
将用户的请求转发给认证服务并阻塞原始请求，然后在认证服务下以非 2xx 状态响应时进行结果替换。
## 属性
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| -- | -- | -- | -- | -- | -- |
-| uri | string | 必须 | | | 设置 `authorization` 服务的地址 (eg.
https://localhost:9188) |
-| ssl_verify | boolean | 可选 | true | | 是否验证证书 |
-| request_method | string | 可选 | GET | ["GET","POST"] | `client` 请求
`authorization` 服务的方法。当设置为 POST 时，会将 request body 转发至`authorization` 服务。 |
-| request_headers | array[string] | 可选 | | | 设置需要由 `client` 转发到
`authorization` 服务的请求头。未设置时，只有 Apache APISIX 的 (X-Forwarded-XXX) 会被转发到
`authorization` 服务。 |
-| upstream_headers | array[string] | 可选 | | | 认证通过时，设置 `authorization` 服务转发至
`upstream` 的请求头。如果不设置则不转发任何请求头。
-| client_headers | array[string] | 可选 | | | 认证失败时，由 `authorization` 服务向
`client` 发送的响应头。如果不设置则不转发任何响应头。 |
-| timeout | integer | 可选 | 3000ms | [1, 60000]ms | `authorization` 服务请求超时时间 |
-| keepalive | boolean | 可选 | true | | HTTP 长连接 |
-| keepalive_timeout | integer | 可选 | 60000ms | [1000, ...]ms | 长连接超时时间 |
-| keepalive_pool | integer | 可选 | 5 | [1, ...]ms | 长连接池大小 |
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述
|
+| ----------------- | ------------- | ------| ------- | -------------- |
--------------------------------------------------------------------------------------------------------------------
|
+| uri | string | 是 | | | 设置
`authorization` 服务的地址 (例如：https://localhost:9188)。
|
+| ssl_verify | boolean | 否 | true | [true, false] | 当设置为
`true` 时，验证 SSL 证书。
|
+| request_method | string | 否 | GET | ["GET","POST"] | 客户端向
`authorization` 服务发送请求的方法。当设置为 POST 时，会将 `request body` 转发至 `authorization` 服务。
|
+| request_headers | array[string] | 否 | | |
设置需要由客户端转发到 `authorization` 服务的请求头。如果没有设置，则只发送 APISIX 提供的 headers
(例如：X-Forwarded-XXX)。 |
+| upstream_headers | array[string] | 否 | | |
认证通过时，设置 `authorization` 服务转发至 `upstream` 的请求头。如果不设置则不转发任何请求头。
|
+| client_headers | array[string] | 否 | | |
认证失败时，由 `authorization` 服务向 `client` 发送的响应头。如果不设置则不转发任何响应头。
|
+| timeout | integer | 否 | 3000ms | [1, 60000]ms |
`authorization` 服务请求超时时间。
|
+| keepalive | boolean | 否 | true | [true, false] | HTTP
长连接。
|
+| keepalive_timeout | integer | 否 | 60000ms | [1000, ...]ms |
长连接超时时间。
|
+| keepalive_pool | integer | 否 | 5 | [1, ...]ms |
长连接池大小。
|
## 数据定义
-request_headers 属性中转发到 `authorization` 服务中的 Apache APISIX 内容清单
+APISIX 将生成并发送如下所示的请求头到认证服务：
-| Scheme | HTTP Method | Host | URI | Source IP |
-| -- | -- | -- | -- | -- |
-| X-Forwarded-Proto | X-Forwarded-Method | X-Forwarded-Host | X-Forwarded-Uri
| X-Forwarded-For |
+| Scheme | HTTP Method | Host | URI
| Source IP |
+| ----------------- | ------------------ | ----------------- | ---------------
| --------------- |
+| X-Forwarded-Proto | X-Forwarded-Method | X-Forwarded-Host | X-Forwarded-Uri
| X-Forwarded-For |
-## 示例
+## 使用示例
-首先，你需要设置一个认证服务。这里使用的是 Apache APISIX 无服务器插件模拟的示例。
+首先，你需要设置一个外部认证服务。以下示例使用的是 Apache APISIX 无服务器插件模拟服务：
```shell
curl -X PUT 'http://127.0.0.1:9080/apisix/admin/routes/auth' \
@@ -82,7 +87,7 @@ curl -X PUT 'http://127.0.0.1:9080/apisix/admin/routes/auth' \
}'
```
-下一步，我们创建一个测试路由。
+现在你可以在指定 Route 上启用 `forward-auth` 插件：
```shell
curl -X PUT 'http://127.0.0.1:9080/apisix/admin/routes/1' \
@@ -106,9 +111,9 @@ curl -X PUT 'http://127.0.0.1:9080/apisix/admin/routes/1' \
}'
```
-我们可以进行下面三个测试：
+完成上述配置后，可通过以下三种方式进行测试：
-1. **request_headers** 从 `client` 转发请求头到 `authorization` 服务
+- 在请求头中发送认证的详细信息：
```shell
curl http://127.0.0.1:9080/headers -H 'Authorization: 123'
@@ -123,7 +128,7 @@ curl http://127.0.0.1:9080/headers -H 'Authorization: 123'
}
```
-2. **upstream_headers** 转发 `authorization` 服务响应头到 `upstream`
+- 转发认证服务响应头到 Upstream。
```shell
curl http://127.0.0.1:9080/headers -H 'Authorization: 321'
@@ -139,15 +144,33 @@ curl http://127.0.0.1:9080/headers -H 'Authorization: 321'
}
```
-3. **client_headers** 当授权失败时转发 `authorization` 服务响应头到 `client`
+- 当授权失败时，认证服务可以向用户发送自定义响应：
```shell
curl -i http://127.0.0.1:9080/headers
```
-```
+```shell
HTTP/1.1 403 Forbidden
Location: http://example.com/auth
```
-最后，你可以通过在路由中移除的方式禁用 `forward-auth` 插件。
+## 禁用插件
+
+当你需要禁用 `forward-auth` 插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "methods": ["GET"],
+ "uri": "/hello",
+ "plugins": {},
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "httpbin.org:80": 1
+ }
+ }
+}'
+```
diff --git a/docs/zh/latest/plugins/hmac-auth.md
b/docs/zh/latest/plugins/hmac-auth.md
index db51afae0..16beab6d6 100644
--- a/docs/zh/latest/plugins/hmac-auth.md
+++ b/docs/zh/latest/plugins/hmac-auth.md
@@ -1,5 +1,11 @@
---
title: hmac-auth
+keywords:
+ - APISIX
+ - Plugin
+ - HMAC Authentication
+ - hmac-auth
+description: 本文介绍了关于 Apache APISIX `hmac-auth` 插件的基本信息及使用方法。
---
<!--
@@ -23,30 +29,31 @@ title: hmac-auth
## 描述
-`hmac-auth` 是一个认证插件，它需要与 `consumer` 一起配合才能工作。
+`hmac-auth` 插件可以将 [HMAC authentication](https://en.wikipedia.org/wiki/HMAC)
添加到 Route 或者 Service。
-添加 HMAC Authentication 到一个 `service` 或 `route`。 然后 `consumer` 将其签名添加到请求头以验证其请求。
+该插件需要和 Consumer 一起使用，API 的使用者必须将密匙添加到请求头中以验证其请求。
## 属性
-| 名称 | 类型 | 必选项 | 默认值 | 有效值
| 描述
|
-| ---------------- | ------------- | ------ | ------------- |
------------------------------------------- |
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
|
-| access_key | string | 必须 | |
| 不同的 `consumer` 对象应有不同的值，它应当是唯一的。不同 consumer 使用了相同的
`access_key` ，将会出现请求匹配异常。
|
-| secret_key | string | 必须 | |
| 与 `access_key` 配对使用。
|
-| algorithm | string | 可选 | "hmac-sha256" | ["hmac-sha1",
"hmac-sha256", "hmac-sha512"] | 加密算法。
|
-| clock_skew | integer | 可选 | 0 |
| 签名允许的时间偏移，以秒为单位的计时。比如允许时间偏移 10 秒钟，那么就应设置为
`10`。特别地，`0` 表示不对 `Date` 进行检查。
|
-| signed_headers | array[string] | 可选 | |
| 限制加入加密计算的 headers ，指定后客户端请求只能在此范围内指定 headers
，此项为空时将把所有客户端请求指定的 headers 加入加密计算。如： ["User-Agent", "Accept-Language",
"x-custom-a"] |
-| keep_headers | boolean | 可选 | false | [ true, false ]
| 认证成功后的 http 请求中是否需要保留
`X-HMAC-SIGNATURE`、`X-HMAC-ALGORITHM` 和 `X-HMAC-SIGNED-HEADERS` 的请求头。true: 表示保留
http 请求头，false: 表示移除 http 请求头。 |
-| encode_uri_param | boolean | 可选 | true | [ true, false ]
| 是否对签名中的 uri 参数进行编码，例如：`params1=hello%2Cworld`
进行了编码，`params2=hello,world` 没有进行编码。true: 表示对签名中的 uri 参数进行编码，false: 不对签名中的 uri
参数编码。 |
-| validate_request_body | boolean | 可选 | false | [ true, false ]
| 是否对请求 body 做签名校验。|
-| max_req_body | integer | 可选 | 512 * 1024 |
| 最大允许的 body 大小。|
+| 名称 | 类型 | 必选项 | 默认值 | 有效值
| 描述
|
+| ---------------- | ------------- | ------ | ------------- |
------------------------------------------|
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
|
+| access_key | string | 是 | |
| Consumer 的 `access_key` 必须是唯一的。如果不同 Consumer 使用了相同的
`access_key` ，将会出现请求匹配异常。
|
+| secret_key | string | 是 | |
| 与 `access_key` 配对使用。
|
+| algorithm | string | 否 | "hmac-sha256" | ["hmac-sha1",
"hmac-sha256", "hmac-sha512"] | 可以使用的加密算法。
|
+| clock_skew | integer | 否 | 0 |
| 签名允许的时间偏移（以秒为单位）。比如允许时间偏移 10 秒钟，那么就应设置为 `10`。如果将其设置为
`0`，则表示表示跳过日期检查。
|
+| signed_headers | array[string] | 否 | |
| 要在加密计算中使用的 headers 列表。指定后客户端请求只能在此范围内指定
headers，如果未指定，就会在所有客户端请求指定的 headers 加入加密计算。如： ["User-Agent", "Accept-Language",
"x-custom-a"]。 |
+| keep_headers | boolean | 否 | false | [ true, false ]
| 当设置为 `true` 时，认证成功后的 HTTP 请求中则会保留
`X-HMAC-SIGNATURE`、`X-HMAC-ALGORITHM` 和 `X-HMAC-SIGNED-HEADERS` 的请求头。否则将移除 HTTP
请求头。 |
+| encode_uri_param | boolean | 否 | true | [ true, false ]
| 当设置为 `true` 时，对签名中的 URI
参数进行编码。例如：`params1=hello%2Cworld` 进行了编码，`params2=hello,world` 没有进行编码。设置为
`false` 时则不对签名中的 URI 参数编码。 |
+| validate_request_body | boolean | 否 | false | [ true, false ]
| 当设置为 `true` 时，对请求 body 做签名校验。
|
+| max_req_body | integer | 否 | 512 * 1024 |
| 最大允许的 body 大小。
|
-## 如何启用
+## 启用插件
-1. 创建一个 consumer 对象，并设置插件 `hmac-auth` 的值。
+首先，我们需要在 Consumer 中启用该插件，如下所示：
```shell
-curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/consumers \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"username": "jack",
"plugins": {
@@ -60,12 +67,19 @@ curl http://127.0.0.1:9080/apisix/admin/consumers -H
'X-API-KEY: edd1c9f034335f1
}'
```
-默认 `keep_headers` 为 false，`encode_uri_param` 为 true。
+你也可以通过 [APISIX Dashboard](/docs/dashboard/USER_GUIDE) 的 Web 界面完成操作。
-2. 创建 Route 或 Service 对象，并开启 `hmac-auth` 插件。
+<!--
+
+
+
+-->
+
+然后就可以在 Route 或 Service 中启用插件，如下所示：
```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/index.html",
"plugins": {
@@ -84,34 +98,33 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f13
### 签名生成公式
-签名的计算公式为 `signature = HMAC-SHAx-HEX(secret_key,
signing_string)`，从公式可以看出，想要获得签名需要得到 `secret_key` 和 `signing_string` 两个参数。其中
`secret_key` 为对应 consumer 所配置的， `signing_string` 的计算公式为 `signing_string = HTTP
Method + \n + HTTP URI + \n + canonical_query_string + \n + access_key + \n +
Date + \n + signed_headers_string`。如果 signing_string 中的某一项不存在，也需要使用一个空字符串代替。
+需注意，在使用 `hmac-auth` 插件时，会涉及到签名。签名的计算公式为 `signature = HMAC-SHAx-HEX(secret_key,
signing_string)`。
+
+为了生成签名需要两个参数：`secret_key` 和 `signing_string`。其中 `secret_key` 由对应 Consumer
配置，`signing_string` 的计算公式为 `signing_string = HTTP Method + \n + HTTP URI + \n +
canonical_query_string + \n + access_key + \n + Date + \n +
signed_headers_string`。如果 `signing_string` 中的某一项不存在，则需要使用一个空字符串代替：
-1. **HTTP Method**：指 HTTP 协议中定义的 GET、PUT、POST 等请求方法，必须使用全大写的形式。
-2. **HTTP URI**：要求必须以“/”开头，不以“/”开头的需要补充上，空路径为“/”。
-3. **Date**：请求头中的 Date（ GMT 格式 ）。
-4. **canonical_query_string**：是对于 URL 中的 query（ query 即 URL 中 ? 后面的
key1=valve1&key2=valve2 字符串）进行编码后的结果。
-5. **signed_headers_string**：是从请求头中获取客户端指定的字段，并按顺序拼接字符串的结果。
+- **HTTP Method**：指 HTTP 协议中定义的 GET、PUT、POST 等请求方法，必须使用全大写的形式。
+- **HTTP URI**：HTTP URI。必须以 “/” 开头，“/” 表示空路径。
+- **Date**：请求头中的日期（GMT 格式）。
+- **canonical_query_string**：对 URL 中的 query（query 即 URL 中 `?` 后面的
`key1=valve1&key2=valve2` 字符串）进行编码后的结果。
+- **signed_headers_string**：从请求头中获取客户端指定的字段，并按顺序拼接字符串的结果。
-> canonical_query_string 编码步骤如下：
+> 生成 `canonical_query_string` 的算法描述如下：
-* 提取 URL 中的 query 项，即 URL 中 ? 后面的 key1=valve1&key2=valve2 字符串。
-* 将 query 根据&分隔符拆开成若干项，每一项是 key=value 或者只有 key 的形式。
-* 根据 uri 参数是否编码，有下面两种情况：
-* `encode_uri_param` 为 true 时：
- * 对拆开后的每一项进行编码处理，分以下两种情况：
- * 当该项只有 key 时，转换公式为 url_encode(key) + "=" 的形式。
- * 当该项是 key=value 的形式时，转换公式为 url_encode(key) + "=" + url_encode(value) 的形式。这里
value 可以是空字符串。
- * 将每一项转换后，以 key 按照字典顺序（ ASCII 码由小到大）排序，并使用 & 符号连接起来，生成相应的
canonical_query_string 。
-* `encode_uri_param` 为 false 时：
- * 对拆开后的每一项进行编码处理，分以下两种情况：
- * 当该项只有 key 时，转换公式为 key + "=" 的形式。
- * 当该项是 key=value 的形式时，转换公式为 key + "=" + value 的形式。这里 value 可以是空字符串。
- * 将每一项转换后，以 key 按照字典顺序（ ASCII 码由小到大）排序，并使用 & 符号连接起来，生成相应的
canonical_query_string 。
+1. 提取 URL 中的 query 项。
+2. 使用 `&` 作为分隔符，将 query 拆分成键值对。
+3. 如果 `encode_uri_param` 为 true 时：
+ 1. 当该项有 `key` 时，转换公式为 `url_encode(key) + "="`。
+ 2. 当该项同时有 `key` 和 `value` 时，转换公式为 `url_encode(key) + "=" +
url_encode(value)` 。此处 `value` 可以是空字符串。
+ 3. 将每一项转换后，以 key 按照字典顺序（ ASCII 码由小到大）排序，并使用 & 符号连接起来，生成相应的
`canonical_query_string` 。
+4. 如果 `encode_uri_param` 为 false 时：
+ 1. 当该项只有 `key` 时，转换公式为 `key + "="` 。
+ 2. 当该项同时有 `key` 和 `value` 时，转换公式为 `key + "=" + value` 。此处 `value` 可以是空字符串。
+ 3. 将每一项转换后，以 key 按照字典顺序（ ASCII 码由小到大）排序，并使用 `&` 符号连接起来，生成相应的
`canonical_query_string`。
-> signed_headers_string 生成步骤如下：
+> 生成 `signed_headers_string` 的算法如下：
-* 从请求头中获取指定加入计算的 headers ，具体请参考下节 `使用生成好的签名进行请求尝试` 中的 `SIGNED_HEADERS` 放置的位置。
-* 从请求头中按顺序取出 `SIGNED_HEADERS` 指定的 headers ，并按顺序用 `name:value` 方式拼接起来，拼接完后就生成了
`signed_headers_string`。
+1. 从请求头中获取指定的 headers 加入计算中。
+2. 从请求头中按顺序取出 `SIGNED_HEADERS` 指定的 headers，并按顺序用 `name:value` 方式拼接起来，拼接完后就生成了
`signed_headers_string`。
```plain
HeaderKey1 + ":" + HeaderValue1 + "\n"\+
@@ -120,18 +133,16 @@ HeaderKey2 + ":" + HeaderValue2 + "\n"\+
HeaderKeyN + ":" + HeaderValueN + "\n"
```
-**签名字符串拼接示例**
-
-以下面请求为例：
+以下示例为你展示了签名字符串的拼接：
```shell
-$ curl -i http://127.0.0.1:9080/index.html?name=james&age=36 \
+curl -i http://127.0.0.1:9080/index.html?name=james&age=36 \
-H "X-HMAC-SIGNED-HEADERS: User-Agent;x-custom-a" \
-H "x-custom-a: test" \
-H "User-Agent: curl/7.29.0"
```
-根据 `签名生成公式` 生成的 `signing_string` 为：
+根据上述算法生成的 `signing_string` 为：
```plain
"GET
@@ -144,11 +155,9 @@ x-custom-a:test
"
```
-注意：最后一个请求头也需要 + `\n`。
-
-**生成签名**
+最后一个请求头也需要 + `\n`。
-使用 Python 来生成签名 `SIGNATURE`：
+以下示例是通过使用 Python 来生成签名 `SIGNATURE`：
```python
import base64
@@ -175,22 +184,30 @@ print(base64.b64encode(hash.digest()))
| --------- | -------------------------------------------- |
| SIGNATURE | 8XV1GB7Tq23OJcoz6wjqTs4ZLxr9DiLoY4PxzScWGYg= |
+您也可以参考 [Generating HMAC
signatures](../examples/plugins-hmac-auth-generate-signature.md)
了解如何为不同的编程语言生成签名。
+
### Body 校验
-`validate_request_body` 设置为 true 时，插件将计算请求 body 的 `hmac-sha` 值，并与请求 headers 中的
`X-HMAC-DIGEST` 的值进行校验。
+当 `validate_request_body` 设置为 `true` 时，插件将计算请求 body 的 `hmac-sha` 值，并与请求
headers 中的 `X-HMAC-DIGEST` 的值进行校验。
```
X-HMAC-DIGEST: base64(hmac-sha(<body>))
```
-当没有请求 body 时，插件会计算长度为 0 的空字符串的 hmac-sha 值。
+如果没有请求 body，你可以将 `X-HMAC-DIGEST` 的值设置为空字符串的 HMAC-SHA。
+
+:::note
+
+当开启 body 校验时，为了计算请求 body 的 `hmac-sha` 值，插件会把 body 加载到内存中，在请求 body
较大的情况下，可能会造成较高的内存消耗。为了避免这种情况，你可以通过设置 `max_req_body`（默认值是 512KB）配置项来配置最大允许的 body
大小，body 超过此大小的请求会被拒绝。
-**注：**当开启 body 校验时，为了计算请求 body 的 `hmac-sha` 值，插件会把 body 加载到内存中，在请求 body
较大的情况下，可能会造成较高的内存消耗。插件提供了 `max_req_body`（默认值 512KB）配置项来配置最大允许的 body 大小，body
超过此大小的请求会被拒绝。
+:::
### 使用生成好的签名进行请求尝试
+你可以通过以下示例使用生成的签名发起请求：
+
```shell
-$ curl -i "http://127.0.0.1:9080/index.html?name=james&age=36"; \
+curl -i "http://127.0.0.1:9080/index.html?name=james&age=36"; \
-H "X-HMAC-SIGNATURE: 8XV1GB7Tq23OJcoz6wjqTs4ZLxr9DiLoY4PxzScWGYg=" \
-H "X-HMAC-ALGORITHM: hmac-sha256" \
-H "X-HMAC-ACCESS-KEY: user-key" \
@@ -198,7 +215,9 @@ $ curl -i
"http://127.0.0.1:9080/index.html?name=james&age=36"; \
-H "X-HMAC-SIGNED-HEADERS: User-Agent;x-custom-a" \
-H "x-custom-a: test" \
-H "User-Agent: curl/7.29.0"
+```
+```shell
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Transfer-Encoding: chunked
@@ -208,12 +227,14 @@ Server: APISIX/2.2
......
```
-**下面是签名信息的两种组装形式**
+签名可以放到请求头 `Authorization` 字段中：
-* 签名信息拼一起放到请求头 `Authorization` 字段中：
+```shell
+curl http://127.0.0.1:9080/index.html \
+-H 'Authorization: hmac-auth-v1# + ACCESS_KEY + # + base64_encode(SIGNATURE) +
# + ALGORITHM + # + DATE + # + SIGNED_HEADERS' -i
+```
```shell
-$ curl http://127.0.0.1:9080/index.html -H 'Authorization: hmac-auth-v1# +
ACCESS_KEY + # + base64_encode(SIGNATURE) + # + ALGORITHM + # + DATE + # +
SIGNED_HEADERS' -i
HTTP/1.1 200 OK
Content-Type: text/html
Content-Length: 13175
@@ -225,10 +246,18 @@ Accept-Ranges: bytes
...
```
-- 签名信息分开分别放到请求头：
+也可以将签名单独放在另一个请求头中：
+
+```shell
+curl http://127.0.0.1:9080/index.html \
+-H 'X-HMAC-SIGNATURE: base64_encode(SIGNATURE)' \
+-H 'X-HMAC-ALGORITHM: ALGORITHM' \
+-H 'Date: DATE' \
+-H 'X-HMAC-ACCESS-KEY: ACCESS_KEY' \
+-H 'X-HMAC-SIGNED-HEADERS: SIGNED_HEADERS' -i
+```
```shell
-$ curl http://127.0.0.1:9080/index.html -H 'X-HMAC-SIGNATURE:
base64_encode(SIGNATURE)' -H 'X-HMAC-ALGORITHM: ALGORITHM' -H 'Date: DATE' -H
'X-HMAC-ACCESS-KEY: ACCESS_KEY' -H 'X-HMAC-SIGNED-HEADERS: SIGNED_HEADERS' -i
HTTP/1.1 200 OK
Content-Type: text/html
Content-Length: 13175
@@ -239,17 +268,19 @@ Accept-Ranges: bytes
<html lang="cn">
```
-**注：**
+:::note
-1. **ACCESS_KEY, SIGNATURE, ALGORITHM, DATE, SIGNED_HEADERS 分别代表对应的变量**
-2. **SIGNED_HEADERS 为客户端指定的加入加密计算的 headers。若存在多个 headers 需以 ";"
分割：`x-custom-header-a;x-custom-header-b`**
-3. **SIGNATURE 需要使用 base64 进行加密：`base64_encode(SIGNATURE)`**
+1. ACCESS_KEY、SIGNATURE、ALGORITHM、DATE、SIGNED_HEADERS 分别代表对应的变量。
+2. SIGNED_HEADERS 为客户端指定的加入加密计算的 headers。若存在多个 headers 需以 “;”
分割，例如：`x-custom-header-a;x-custom-header-b`。
+3. SIGNATURE 需要使用 base64 进行加密：`base64_encode(SIGNATURE)`。
+
+:::
## 自定义 header 名称
-我们可以在 `conf/config.yaml` 中，`plugin_attr` 下添加插件的属性配置来自定义参数 header 名称。
+除了配置签名外，你还可以在配置文件（`conf/config.yaml`）中的`plugin_attr` 配置项下，添加 `hmac-auth`
插件的属性来自定义参数 header 名称。如下所示：
-```yaml
+```yaml title="conf/config.yaml"
plugin_attr:
hmac-auth:
signature_key: X-APISIX-HMAC-SIGNATURE
@@ -260,10 +291,19 @@ plugin_attr:
body_digest_key: X-APISIX-HMAC-BODY-DIGEST
```
-**自定义 header 后，请求示例：**
+配置完成后，你可以使用自定义的 header 发起请求。
```shell
-$ curl http://127.0.0.1:9080/index.html -H 'X-APISIX-HMAC-SIGNATURE:
base64_encode(SIGNATURE)' -H 'X-APISIX-HMAC-ALGORITHM: ALGORITHM' -H
'X-APISIX-DATE: DATE' -H 'X-APISIX-HMAC-ACCESS-KEY: ACCESS_KEY' -H
'X-APISIX-HMAC-SIGNED-HEADERS: SIGNED_HEADERS' -H 'X-APISIX-HMAC-BODY-DIGEST:
BODY_DIGEST' -i
+curl http://127.0.0.1:9080/index.html \
+-H 'X-APISIX-HMAC-SIGNATURE: base64_encode(SIGNATURE)' \
+-H 'X-APISIX-HMAC-ALGORITHM: ALGORITHM' \
+-H 'X-APISIX-DATE: DATE' \
+-H 'X-APISIX-HMAC-ACCESS-KEY: ACCESS_KEY' \
+-H 'X-APISIX-HMAC-SIGNED-HEADERS: SIGNED_HEADERS' \
+-H 'X-APISIX-HMAC-BODY-DIGEST: BODY_DIGEST' -i
+```
+
+```
HTTP/1.1 200 OK
Content-Type: text/html
Content-Length: 13175
@@ -274,35 +314,13 @@ Accept-Ranges: bytes
<html lang="cn">
```
-### 开启 body 校验
-
-```shell
-$ curl -X "POST" "http://localhost:9080/index.html?age=36&name=james"; \
- -H 'X-HMAC-ACCESS-KEY: my-access-key' \
- -H 'X-HMAC-SIGNATURE: lSWO4vcyVoZG5bn8miHudzABAeJQd8tqEHyM7RsjeiU=' \
- -H 'X-HMAC-ALGORITHM: hmac-sha256' \
- -H 'Date: Tue, 24 Aug 2021 03:19:21 GMT' \
- -H 'X-HMAC-SIGNED-HEADERS: User-Agent;X-HMAC-DIGEST' \
- -H 'User-Agent: curl/7.29.0' \
- -H 'X-HMAC-DIGEST: L9b/+QMvhvnoUlSw5vq+kHPqnZiHGl61T8oavMVTaC4=' \
- -H 'Content-Type: text/plain; charset=utf-8' \
- -d "{\"hello\":\"world\"}"
-
-HTTP/1.1 200 OK
-Content-Type: text/html; charset=utf-8
-Transfer-Encoding: chunked
-Connection: keep-alive
-Date: Tue, 14 Sep 2021 03:28:14 GMT
-Server: APISIX/2.9
-...
-```
-
## 禁用插件
-当你想去掉 `hmac-auth` 插件的时候，很简单，在插件的配置中把对应的 `json` 配置删除即可，无须重启服务，即刻生效：
+当你需要禁用 `hmac-auth` 插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/index.html",
"plugins": {},
@@ -314,23 +332,3 @@ $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f
}
}'
```
-
-## 签名生成示例
-
-以 HMAC SHA256 为例，介绍一下各种语言的签名生成示例。需要注意各种语言中对签名字符串的换行符的处理方式，这很容易导致出现
`{"message":"Invalid signature"}` 的问题。
-
-示例入参说明：
-
-| Variable | Value |
-| -------- | -------------------------- |
-| secret | the shared secret key here |
-| message | this is signature string |
-
-示例出参说明：
-
-| Type | Hash |
-| ------ | ---------------------------------------------------------------- |
-| hexit | ad1b76c7e5054009380edca35d3f36cc5b6f45c82ee02ea3af64197ebddb9345 |
-| base64 | rRt2x+UFQAk4DtyjXT82zFtvRcgu4C6jr2QZfr3bk0U= |
-
-具体代码请参考：[**HMAC Generate Signature
Examples**](../../../en/latest/examples/plugins-hmac-auth-generate-signature.md)
diff --git a/docs/zh/latest/plugins/jwt-auth.md
b/docs/zh/latest/plugins/jwt-auth.md
index 0383d1179..acdac432e 100644
--- a/docs/zh/latest/plugins/jwt-auth.md
+++ b/docs/zh/latest/plugins/jwt-auth.md
@@ -1,5 +1,11 @@
---
title: jwt-auth
+keywords:
+ - APISIX
+ - Plugin
+ - JWT Auth
+ - jwt-auth
+description: 本文介绍了关于 Apache APISIX `jwt-auth` 插件的基本信息及使用方法。
---
<!--
@@ -23,49 +29,62 @@ title: jwt-auth
## 描述
-`jwt-auth` 是一个认证插件，它需要与 `consumer` 一起配合才能工作。
+`jwt-auth` 插件用于将 [JWT](https://jwt.io/) 身份验证添加到
[Service](../terminology/service.md) 或 [Route](../terminology/route.md) 中。
-添加 JWT Authentication 到一个 `service` 或 `route`。 然后 `consumer`
将其密钥添加到查询字符串参数、请求头或 `cookie` 中以验证其请求。
+通过 Consumer 将其密匙添加到查询字符串参数、请求头或 `cookie` 中用来验证其请求。
-有关 JWT 的更多信息，可参考 [JWT](https://jwt.io/) 查看更多信息。
-
-`jwt-auth` 插件可以与 HashiCorp Vault 集成，用于存储和获取密钥，从其加密的 KV 引擎获取 RSA 密钥对。 阅读下面的
[例子](#enable-jwt-auth-with-vault-compatibility) 来了解它如何工作。
+`jwt-auth` 插件可以与 [HashiCorp Vault](https://www.vaultproject.io/)
集成，用于存储和获取密钥，并从 HashiCorp Vault 的 [encrypted KV
engine](https://www.vaultproject.io/docs/secrets/kv)中获取 RSA 密匙对。你可以从下面的
[示例](#与-HashiCorp-Vault-一起使用) 中了解更多信息。
## 属性
-consumer 端配置：
+Consumer 端：
+
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述
|
+| ------------- | ------- | ----- | ------- | --------------------------- |
------------------------------------------------------------------------------------------------------------
|
+| key | string | 是 | | |
Consumer 的 `access_key` 必须是唯一的。如果不同 Consumer 使用了相同的 `access_key` ，将会出现请求匹配异常。 |
+| secret | string | 否 | | |
加密秘钥。如果未指定，后台将会自动生成。
|
+| public_key | string | 否 | | | RSA
公钥， `algorithm` 属性选择 `RS256` 算法时必选。
|
+| private_key | string | 否 | | | RSA
私钥， `algorithm` 属性选择 `RS256` 算法时必选。
|
+| algorithm | string | 否 | "HS256" | ["HS256", "HS512", "RS256"] |
加密算法。
|
+| exp | integer | 否 | 86400 | [1,...] |
token 的超时时间。
|
+| base64_secret | boolean | 否 | false | |
当设置为 `true` 时，密钥为 base64 编码。
|
+| vault | object | 否 | | |
是否使用 Vault 作为存储和检索密钥（HS256/HS512 的密钥或 RS256 的公钥和私钥）的方式。该插件默认使用
`kv/apisix/consumer/<consumer name>/jwt-auth` 路径进行密钥检索。 |
+
+:::info IMPORTANT
+
+如果你想要启用 Vault 集成，你需要在
[config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml)
配置文件中，更新你的 Vault 服务器配置、主机地址和访问令牌。
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述
|
-| :------------ | :------ | :----- | :------ | :-------------------------- |
:------------------------------------------------------------------------------------------------------------
|
-| key | string | 必须 | | | 不同的
`consumer` 对象应有不同的值，它应当是唯一的。不同 consumer 使用了相同的 `key` ，将会出现请求匹配异常。 |
-| secret | string | 可选 | | |
加密秘钥。如果您未指定，后台将会自动帮您生成。
|
-| public_key | string | 可选 | | | RSA
公钥， `algorithm` 属性选择 `RS256` 算法时必填
|
-| private_key | string | 可选 | | | RSA
私钥， `algorithm` 属性选择 `RS256` 算法时必填
|
-| algorithm | string | 可选 | "HS256" | ["HS256", "HS512", "RS256"] |
加密算法
|
-| exp | integer | 可选 | 86400 | [1,...] |
token 的超时时间
|
-| base64_secret | boolean | 可选 | false | |
密钥是否为 base64 编码
|
-| vault | object | 可选 | | |
是否使用 Vault 作为存储和检索密钥（HS256/HS512 的密钥或 RS256 的公钥和私钥）的方式。该插件默认使用
`kv/apisix/consumer/<consumer name>/jwt-auth` 路径进行密钥检索 |
+请参考默认配置文件
[config-default.yaml](https://github.com/apache/apisix/blob/master/conf/config-default.yaml)
中的 Vault 属性下了解相关配置。
-**注意**: 要启用 Vault 集成，首先访问
[config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml)，更新您的
Vault 服务器配置、主机地址和访问令牌。您可以在
[config-default.yaml](https://github.com/apache/apisix/blob/master/conf/config-default.yaml)
中 vault 属性下查看 APISIX 的默认配置。
+:::
-router 端配置：
+Route 端：
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述
|
-| ---- | ------ | ------ | ------ | ------ |
-------------------------------------------------------------------------------------------------------------
|
-| header | string | 可选 | authorization | | 设置我们从哪个 header 获取 token。 |
-| query | string | 可选 | jwt | | 设置我们从哪个 query string 获取 token，优先级低于
header |
-| cookie | string | 可选 | jwt | | 设置我们从哪个 cookie 获取 token，优先级低于 query |
+| 名称 | 类型 | 必选项 | 默认值 | 描述
|
+| ------ | ------ | ------ | -------------
|---------------------------------------------------------|
+| header | string | 否 | authorization | 设置我们从哪个 header 获取 token。
|
+| query | string | 否 | jwt | 设置我们从哪个 query string 获取
token，优先级低于 header。 |
+| cookie | string | 否 | jwt | 设置我们从哪个 cookie 获取 token，优先级低于
query。 |
## 接口
-插件会增加 `/apisix/plugin/jwt/sign` 这个接口，需要通过
[public-api](../../../en/latest/plugins/public-api.md) 插件来暴露它。
+该插件会增加 `/apisix/plugin/jwt/sign` 接口。
+
+:::note
+
+你需要通过 [public-api](../../../en/latest/plugins/public-api.md) 插件来暴露它。
+
+:::
+
+## 启用插件
-## 如何启用
+如果想要启用插件，就必须使用 JWT token 创建一个 Consumer 对象，并将 Route 配置为使用 JWT 身份验证。
-1. 创建一个 consumer 对象，并设置插件 `jwt-auth` 的值。
+首先，你可以通过 Admin API 创建一个 Consumer：
```shell
-curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/consumers \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"username": "jack",
"plugins": {
@@ -77,10 +96,13 @@ curl http://127.0.0.1:9080/apisix/admin/consumers -H
'X-API-KEY: edd1c9f034335f1
}'
```
+:::note
+
`jwt-auth` 默认使用 `HS256` 算法，如果使用 `RS256` 算法，需要指定算法，并配置公钥与私钥，示例如下：
```shell
-curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/consumers \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"username": "kerouac",
"plugins": {
@@ -94,10 +116,13 @@ curl http://127.0.0.1:9080/apisix/admin/consumers -H
'X-API-KEY: edd1c9f034335f1
}'
```
-2. 创建 Route 或 Service 对象，并开启 `jwt-auth` 插件。
+:::
+
+创建 Consumer 对象后，你可以创建 Route 进行验证：
```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
"uri": "/index.html",
@@ -113,18 +138,27 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f13
}'
```
-### Vault 与 APISIX jwt-auth 插件集成的不同用例
+### 与 HashiCorp Vault 集成使用
+
+[HashiCorp Vault](https://www.vaultproject.io/) 提供集中式密钥管理解决方案，可与 APISIX
一起用于身份验证。
+
+因此，如果你的企业经常更改 secret/keys（HS256/HS512 的密钥或 RS256 的 public_key 和
private_key）并且你不想每次都更新 APISIX 的 Consumer，或者你不想通过 Admin API（减少信息泄漏），你可以将 Vault 和
`jwt-auth` 插件一起使用。
-Apache APISIX `jwt-auth` 插件可以被配置为从 Vault 存储中获取简单的文本密钥以及 RS256 公私密钥对。
+:::note
-**注意**：对于该集成支持的早期版本，该插件期望存储在 Vault
路径中的密钥名称为「`secret`，`public_key`，`private_key`」其中之一。在未来的版本中，我们将支持引用自定义命名键。
+当前版本的 Apache APISIX 期望存储在 Vault 中机密的密钥名称位于 `secret`、`public_key` 和
`private_key` 之间。前一个用于 HS256/HS512 算法，后两个用于 RS256 算法。
-要启用 Vault 的兼容性，只需要在 `jwt-auth` 插件内添加空的 Vault 对象。
+在未来的版本中，该插件将支持引用自定义命名键。
-1. 用在 Vault 储存的 HS256 签名密钥来进行 JWT 签名和认证。
+:::
+
+如果你要使用 Vault，可以在配置中添加一个空的 Vault 对象。
+
+例如，如果你在 Vault 中存储了一个 HS256 签名密钥，可以通过以下方式在 APISIX 中使用它：
```shell
-curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/consumers \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"username": "jack",
"plugins": {
@@ -136,14 +170,25 @@ curl http://127.0.0.1:9080/apisix/admin/consumers -H
'X-API-KEY: edd1c9f034335f1
}'
```
-在这里，插件在 Consumer 配置中提到的 Consumer 用户 `jack` 的 Vault 路径（`<vault.prefix from
conf.yaml>/consumer/jack/jwt-auth`）中查找密钥 `secret`，并使用它进行后续的签名和 JWT
验证。如果在该路径中没有找到密钥，该插件将记录一个错误，并且无法执行 JWT 验证。
+该插件将在提供的 Vault 路径（<vault.prefix>/consumer/jack/jwt-auth）中查找密钥 `secret`，并将其用于
JWT 身份验证。如果在同一路径中找不到密钥，插件会记录错误并且无法执行 JWT 验证。
+
+:::note
+
+`vault.prefix` 会在配置文件（`conf/config.yaml`）中根据启用 `Vault kv secret engine`
时选择的基本路径进行设置。
-2. RS256 RSA 密钥对，包括公钥和私钥都存粗在 Vault 中。
+例如，如果设置了 `vault secrets enable -path=foobar kv`，就需要在 `vault.prefix` 中使用
`foobar`。
+
+:::
+
+如果在此路径中找不到密钥，插件将记录错误。
+
+对于 RS256，公钥和私钥都应该存储在 Vault 中，可以通过以下方式配置：
```shell
-curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/consumers \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
- "username": "kowalski",
+ "username": "jack",
"plugins": {
"jwt-auth": {
"key": "rsa-keypair",
@@ -154,20 +199,15 @@ curl http://127.0.0.1:9080/apisix/admin/consumers -H
'X-API-KEY: edd1c9f034335f1
}'
```
-该插件在 Vault 键值对路径（`<vault.prefix from conf.yaml>/consumer/jim/jwt-auth`）中为插件
Vault 配置中提到的用户 `kowalski` 查找 `public_key` 和 `private_key`。如果没有找到，认证失败。
+该插件将在提供的 Vault 键值对路径（`<vault.prefix from conf.yaml>/consumer/jim/jwt-auth`）中查找
`public_key` 和 `private_key`，并将其用于 JWT 身份认证。
-如果你不确定如何将公钥和私钥存储到 Vault 键值对中，请使用这个命令。
+如果在此路径中没有找到密钥，则认证失败，插件将记录错误。
-```shell
-# 提供你当前目录包含的 "public.pem" 和 "private.pem" 文件
-$ vault kv put kv/apisix/consumer/jim/jwt-auth [email protected]
[email protected]
-Success! Data written to: kv/apisix/consumer/jim/jwt-auth
-```
-
-3. 公钥在 Consumer 配置中，而私钥在 Vault 中。
+你还可以在 Consumer 中配置 `public_key` 并使用存储在 Vault 中的 `private_key`：
```shell
-curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/consumers \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"username": "rico",
"plugins": {
@@ -181,29 +221,21 @@ curl http://127.0.0.1:9080/apisix/admin/consumers -H
'X-API-KEY: edd1c9f034335f1
}'
```
-这个插件使用 Consumer 配置中的 RSA 公钥，并直接使用从 Vault 中获取的私钥。
-
-你可以使用 [APISIX Dashboard](https://github.com/apache/apisix-dashboard)，通过 web
界面来完成上面的操作。
-
-1. 先增加一个 consumer：
+你还可以通过 [APISIX Dashboard](https://github.com/apache/apisix-dashboard) 的 Web
界面完成上述操作。
+<!--
-
-然后在 consumer 页面中添加 jwt-auth 插件：
-
-2. 创建 Route 或 Service 对象，并开启 jwt-auth 插件：
-
+-->
## 测试插件
-#### 首先进行登录获取 `jwt-auth` token:
-
-首先，你需要为签发 token 的 API 设置一个路由，它将使用
[public-api](../../../en/latest/plugins/public-api.md) 插件。
+首先，你需要为签发 token 的 API 配置一个 Route，该路由将使用
[public-api](../../../en/latest/plugins/public-api.md) 插件。
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes/jas -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/jas \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/apisix/plugin/jwt/sign",
"plugins": {
@@ -212,12 +244,15 @@ $ curl http://127.0.0.1:9080/apisix/admin/routes/jas -H
'X-API-KEY: edd1c9f03433
}'
```
-之后，我们就可以调用它获取 token 了。
+之后就可以通过调用它来获取 token 了。
* 没有额外的 payload:
```shell
-$ curl http://127.0.0.1:9080/apisix/plugin/jwt/sign?key=user-key -i
+curl http://127.0.0.1:9080/apisix/plugin/jwt/sign?key=user-key -i
+```
+
+```
HTTP/1.1 200 OK
Date: Wed, 24 Jul 2019 10:33:31 GMT
Content-Type: text/plain
@@ -225,13 +260,16 @@ Transfer-Encoding: chunked
Connection: keep-alive
Server: APISIX web server
-eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1c2VyLWtleSIsImV4cCI6MTU2NDA1MDgxMX0.Us8zh_4VjJXF-TmR5f8cif8mBU7SuefPlpxhH0jbPVI
+eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1c2VyLWtleSIsImV4cCI6MTU2NDA1MDgxMXx.Us8zh_4VjJXF-TmR5f8cif8mBU7SuefPlpxhH0jbPVI
```
* 有额外的 payload:
```shell
-$ curl -G --data-urlencode 'payload={"uid":10000,"uname":"test"}'
http://127.0.0.1:9080/apisix/plugin/jwt/sign?key=user-key -i
+curl -G --data-urlencode 'payload={"uid":10000,"uname":"test"}'
http://127.0.0.1:9080/apisix/plugin/jwt/sign?key=user-key -i
+```
+
+```
HTTP/1.1 200 OK
Date: Wed, 21 Apr 2021 06:43:59 GMT
Content-Type: text/plain; charset=utf-8
@@ -242,36 +280,44 @@ Server: APISIX/2.4
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1bmFtZSI6InRlc3QiLCJ1aWQiOjEwMDAwLCJrZXkiOiJ1c2VyLWtleSIsImV4cCI6MTYxOTA3MzgzOX0.jI9-Rpz1gc3u8Y6lZy8I43RXyCu0nSHANCvfn0YZUCY
```
-#### 使用获取到的 token 进行请求尝试
+现在你可以使用获取到的 token 进行请求尝试
-* 缺少 token
+* token 放到请求头中：
```shell
-$ curl http://127.0.0.1:9080/index.html -i
-HTTP/1.1 401 Unauthorized
-...
-{"message":"Missing JWT token in request"}
+curl http://127.0.0.1:9080/index.html \-H 'Authorization:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1c2VyLWtleSIsImV4cCI6MTU2NDA1MDgxMX0.Us8zh_4VjJXF-TmR5f8cif8mBU7SuefPlpxhH0jbPVI'
-i
```
-* token 放到请求头中：
-
```shell
-$ curl http://127.0.0.1:9080/index.html -H 'Authorization:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1c2VyLWtleSIsImV4cCI6MTU2NDA1MDgxMX0.Us8zh_4VjJXF-TmR5f8cif8mBU7SuefPlpxhH0jbPVI'
-i
HTTP/1.1 200 OK
Content-Type: text/html
Content-Length: 13175
...
Accept-Ranges: bytes
-
<!DOCTYPE html>
<html lang="cn">
...
```
+* 缺少 token
+
+```shell
+curl http://127.0.0.1:9080/index.html -i
+```
+
+```shell
+HTTP/1.1 401 Unauthorized
+...
+{"message":"Missing JWT token in request"}
+```
+
* token 放到请求参数中：
```shell
-$ curl
http://127.0.0.1:9080/index.html?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1c2VyLWtleSIsImV4cCI6MTU2NDA1MDgxMX0.Us8zh_4VjJXF-TmR5f8cif8mBU7SuefPlpxhH0jbPVI
-i
+curl
http://127.0.0.1:9080/index.html?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1c2VyLWtleSIsImV4cCI6MTU2NDA1MDgxMX0.Us8zh_4VjJXF-TmR5f8cif8mBU7SuefPlpxhH0jbPVI
-i
+```
+
+```shell
HTTP/1.1 200 OK
Content-Type: text/html
Content-Length: 13175
@@ -286,7 +332,10 @@ Accept-Ranges: bytes
* token 放到 cookie 中：
```shell
-$ curl http://127.0.0.1:9080/index.html --cookie
jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1c2VyLWtleSIsImV4cCI6MTU2NDA1MDgxMX0.Us8zh_4VjJXF-TmR5f8cif8mBU7SuefPlpxhH0jbPVI
-i
+curl http://127.0.0.1:9080/index.html --cookie
jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1c2VyLWtleSIsImV4cCI6MTU2NDA1MDgxMX0.Us8zh_4VjJXF-TmR5f8cif8mBU7SuefPlpxhH0jbPVI
-i
+```
+
+```shell
HTTP/1.1 200 OK
Content-Type: text/html
Content-Length: 13175
@@ -300,10 +349,11 @@ Accept-Ranges: bytes
## 禁用插件
-当你想去掉 `jwt-auth` 插件的时候，很简单，在插件的配置中把对应的 `json` 配置删除即可，无须重启服务，即刻生效：
+当你需要禁用 `jwt-auth` 插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
"uri": "/index.html",
diff --git a/docs/zh/latest/plugins/key-auth.md
b/docs/zh/latest/plugins/key-auth.md
index acbe315fc..1bb44a224 100644
--- a/docs/zh/latest/plugins/key-auth.md
+++ b/docs/zh/latest/plugins/key-auth.md
@@ -1,5 +1,11 @@
---
title: key-auth
+keywords:
+ - APISIX
+ - Plugin
+ - Key Auth
+ - key-auth
+description: 本文介绍了关于 Apache APISIX `key-auth` 插件的基本信息及使用方法。
---
<!--
@@ -23,32 +29,35 @@ title: key-auth
## 描述
-`key-auth` 是一个认证插件，它需要与 `consumer` 一起配合才能工作。
+`key-auth` 插件用于向 Route 或 Service 添加身份验证密钥（API key）。
-添加 Key Authentication 到一个 `service` 或 `route`。 然后，`consumer`
将其密钥添加到查询字符串参数或标头中以验证其请求。
+它需要与 [Consumer](../architecture-design/consumer.md) 一起配合才能工作，通过 Consumer
将其密钥添加到查询字符串参数或标头中以验证其请求。
## 属性
-consumer 端配置：
+Consumer 端：
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述
|
-| ---- | ------ | ------ | ------ | ------ |
-------------------------------------------------------------------------------------------------------------
|
-| key | string | 必需 | | | 不同的 `consumer` 对象应有不同的值，它应当是唯一的。不同
consumer 使用了相同的 `key`，将会出现请求匹配异常。 |
+| 名称 | 类型 | 必选项 | 描述
|
+| ---- | ------ | ------ |
-------------------------------------------------------------------------------------------------------------
|
+| key | string | 是 | 不同的 Consumer 应有不同的 `key`，它应当是唯一的。如果多个 Consumer
使用了相同的 `key`，将会出现请求匹配异常。 |
-router 端配置：
+Router 端：
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述
|
-| ---- | ------ | ------ | ------ | ------ |
-------------------------------------------------------------------------------------------------------------
|
-| header | string | 可选 | apikey | | 设置我们从哪个 header 获取 key。 |
-| query | string | 可选 | apikey | | 设置我们从哪个 query string 获取 key，优先级低于
`header` |
-| hide_credentials | bool | 可选 | false | | 是否将含有认证信息的请求头传递给 upstream。 |
+| 名称 | 类型 | 必选项 | 默认值 | 描述
|
+| ----------------- | ------ | ----- | ------
|-------------------------------------------------------------------------------------------------------------
|
+| header | string | 否 | apikey | 设置我们从哪个 header 获取 key。 |
+| query | string | 否 | apikey | 设置我们从哪个 query string 获取
key，优先级低于 `header` |
+| hide_credentials | bool | 否 | false | 当设置为 `false` 时将含有认证信息的请求头传递给
Upstream。 |
-## 如何启用
+## 启用插件
-1. 创建一个 consumer 对象，并设置插件 `key-auth` 的值。
+如果你要启用插件，就必须使用身份验证密钥创建一个 Consumer 对象，并且需要配置 Route 才可以对请求进行身份验证。
+
+首先，你可以通过 Admin API 创建一个具有唯一 key 的 Consumer：
```shell
-curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/consumers \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"username": "jack",
"plugins": {
@@ -59,16 +68,25 @@ curl http://127.0.0.1:9080/apisix/admin/consumers -H
'X-API-KEY: edd1c9f034335f1
}'
```
-你也可以通过 web 界面来完成上面的操作，先增加一个 consumer：
-
+你还可以通过 [APISIX Dashboard](https://github.com/apache/apisix-dashboard) 的 Web
界面完成上述操作。
+
+<!--
+
+首先创建一个 Consumer：
+
+
-然后在 consumer 页面中添加 key-auth 插件：
-
+然后在 Consumer 页面中添加 `key-auth` 插件：
-2. 创建 route 或 service 对象，并开启 `key-auth` 插件。
+
+
+-->
+
+创建 Consumer 对象后，你可以创建 Route 进行验证：
```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
"uri": "/index.html",
@@ -85,7 +103,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f13
}'
```
-如果不想从默认的 `apikey` header 获取 key，可以自定义 header：
+如果你不想从默认的 `apikey` header 获取 key，可以自定义 header，如下所示：
```json
{
@@ -97,23 +115,34 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f13
## 测试插件
-下面是一个正常通过 `key-auth` 验证的请求：
+通过上述方法配置插件后，可以通过以下命令测试插件：
```shell
-$ curl http://127.0.0.2:9080/index.html -H 'apikey: auth-one' -i
+curl http://127.0.0.2:9080/index.html -H 'apikey: auth-one' -i
+```
+
+```
HTTP/1.1 200 OK
...
```
-如果当前请求没有正确设置 `apikey`，将得到一个 `401` 的应答。
+如果当前请求没有正确配置 `apikey`，将得到一个 `401` 的应答：
+
+```shell
+curl http://127.0.0.2:9080/index.html -i
+```
```shell
-$ curl http://127.0.0.2:9080/index.html -i
HTTP/1.1 401 Unauthorized
...
{"message":"Missing API key found in request"}
+```
-$ curl http://127.0.0.2:9080/index.html -H 'apikey: abcabcabc' -i
+```shell
+curl http://127.0.0.2:9080/index.html -H 'apikey: abcabcabc' -i
+```
+
+```shell
HTTP/1.1 401 Unauthorized
...
{"message":"Invalid API key in request"}
@@ -121,10 +150,11 @@ HTTP/1.1 401 Unauthorized
## 禁用插件
-当你想去掉 `key-auth` 插件的时候，很简单，在插件的配置中把对应的 `json` 配置删除即可，无须重启服务，即刻生效：
+当你需要禁用 `key-auth` 插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
"uri": "/index.html",
@@ -139,5 +169,3 @@ $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f
}
}'
```
-
-现在就已经移除了该插件配置，其他插件的开启和移除也是同样的方法。
diff --git a/docs/zh/latest/plugins/openid-connect.md
b/docs/zh/latest/plugins/openid-connect.md
index cfbe1d528..812b253b5 100644
--- a/docs/zh/latest/plugins/openid-connect.md
+++ b/docs/zh/latest/plugins/openid-connect.md
@@ -1,5 +1,11 @@
---
title: openid-connect
+keywords:
+ - APISIX
+ - Plugin
+ - OpenID Connect
+ - openid-connect
+description: 本文介绍了关于 Apache APISIX `openid-connect` 插件的基本信息及使用方法。
---
<!--
@@ -23,45 +29,59 @@ title: openid-connect
## 描述
-OAuth 2 / Open ID Connect（OIDC）插件为 APISIX 提供身份验证和自省功能。
+`openid-connect` 插件通过 [OpenID Connect](https://openid.net/connect/) 为 APISIX
提供身份验证和自省功能。
## 属性
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 |
描述 |
-| ---------------------------------- | ------- | ------ |
--------------------- | ------- |
---------------------------------------------- |
-| client_id | string | 必须 |
| | OAuth 客户端 ID |
-| client_secret | string | 必须 |
| | OAuth 客户端 secret |
-| discovery | string | 必须 |
| | 身份服务器的发现端点的 URL |
-| scope | string | 可选 | "openid"
| | 用于认证 |
-| realm | string | 可选 | "apisix"
| | 用于认证 |
-| bearer_only | boolean | 可选 | false
| | 设置为 `true` 将检查请求中带有承载令牌的授权标头 |
-| logout_path | string | 可选 | "/logout"
| | |
-| post_logout_redirect_uri | string | 可选 |
| | 调用登出接口后想要跳转的地址 |
-| redirect_uri | string | 可选 | "ngx.var.request_uri"
| | |
-| timeout | integer | 可选 | 3
| [1,...] | 超时时间，单位为秒 |
-| ssl_verify | boolean | 可选 | false
| | |
-| introspection_endpoint | string | 可选 |
| | 身份服务器的令牌验证端点的 URL |
-| introspection_endpoint_auth_method | string | 可选 | "client_secret_basic"
| | 令牌自省的认证方法名称 |
-| public_key | string | 可选 |
| | 验证令牌的公钥 |
-| token_signing_alg_values_expected | string | 可选 |
| | 用于对令牌进行签名的算法 |
-| set_access_token_header | boolean | 可选 | true
| | 在请求头设置访问令牌 |
-| access_token_in_authorization_header | boolean | 可选 | false
| | 当值为 `true` 时，将访问令牌设置在请求头参数 `Authorization`，否则将使用请求头参数
`X-Access-Token`。|
-| set_id_token_header | boolean | 可选 | true
| | 是否将 ID 令牌设置到请求头参数 `X-ID-Token` |
-| set_userinfo_header | boolean | 可选 | true
| | 是否将用户信息对象设置到请求头参数 `X-Userinfo` |
+| 名称 | 类型 | 必选项 | 默认值 | 有效值
| 描述
|
+| ------------------------------------ | ------- | ------ |
--------------------- | ------- |
----------------------------------------------------------------------------------------------------
|
+| client_id | string | 是 |
| | OAuth 客户端 ID。
|
+| client_secret | string | 是 |
| | OAuth 客户端 secret。
|
+| discovery | string | 是 |
| | 身份服务器发现端点的 URL。
|
+| scope | string | 否 | "openid"
| | 用于认证的范围。
|
+| realm | string | 否 | "apisix"
| | 用于认证的领域。
|
+| bearer_only | boolean | 否 | false
| | 设置为 `true` 时，将检查请求中带有承载令牌的授权标头。
|
+| logout_path | string | 否 | "/logout"
| | 登出路径。
|
+| post_logout_redirect_uri | string | 否 |
| | 调用登出接口后想要跳转的 URL。
|
+| redirect_uri | string | 否 |
"ngx.var.request_uri" | | 身份提供者重定向返回的 URI。
|
+| timeout | integer | 否 | 3
| [1,...] | 请求超时时间，单位为秒
|
+| ssl_verify | boolean | 否 | false
| [true, false] | 当设置为 `true` 时，验证身份提供者的 SSL 证书。
|
+| introspection_endpoint | string | 否 |
| | 身份服务器的令牌验证端点的 URL。
|
+| introspection_endpoint_auth_method | string | 否 |
"client_secret_basic" | | 令牌自省的认证方法名称。
|
+| public_key | string | 否 |
| | 验证令牌的公钥。
|
+| token_signing_alg_values_expected | string | 否 |
| | 用于对令牌进行签名的算法。
|
+| set_access_token_header | boolean | 否 | true
| [true, false] | 在请求头设置访问令牌。
|
+| access_token_in_authorization_header | boolean | 否 | false
| [true, false] | 当值为 `true` 时，将访问令牌设置在请求头参数 `Authorization`，否则将使用请求头参数
`X-Access-Token`。|
+| set_id_token_header | boolean | 否 | true
| [true, false] | 是否将 ID 令牌设置到请求头参数 `X-ID-Token`。
|
+| set_userinfo_header | boolean | 否 | true
| [true, false] | 是否将用户信息对象设置到请求头参数 `X-Userinfo`。
|
+
+## 操作模式
+
+`openid-connect` 插件提供三种操作模式：
+
+1. 可以将**插件**配置为：仅验证预期会出现在请求头中的访问令牌。在这种模式下，没有令牌或带有无效令牌的请求将被拒绝。这需要将
`bearer_only` 属性设置为 `true` 并配置 `introspection_endpoint` 或 `public_key`
属性。这种操作模式可用于服务端之间的通信，在这种模式下，请求者可以合理地获取和管理有效的令牌。
+
+2. 可以将插件配置为：通过 OIDC 授权对没有有效令牌的请求进行身份验证，其中该插件充当 OIDC
依赖方。在这种情况下，认证成功后，该插件可以获得并管理会话 Cookie 中的访问令牌，包含 Cookie 的后续请求将使用访问令牌。你需要将
`bearer_only` 属性设置为 `false` 才可以使用这种模式。这种操作模式可用于支持以下情况：客户端或请求者是通过 Web 浏览器进行交互的用户。
+
+3. 插件也可以通过将 `bearer_only` 设置为 `false`，并配置 `introspection_endpoint` 或
`public_key`
属性来支持以上两种场景。在这种情况下，对来自请求头的现有令牌的自省优先于依赖方流程。也就是说，如果一个请求中包含一个无效的令牌，那么该请求将会被拒绝，不会从重定向到
ID 提供者获得一个有效的令牌。
+
+用于验证请求的方法会影响到 header，你可以在将请求发送到上游服务之前对其执行。
### 令牌自省
-令牌自省通过针对 Oauth 2 授权服务器验证令牌来帮助验证请求。
-前提条件是，您应该在身份服务器中创建受信任的客户端，并生成用于自省的有效令牌（JWT）。
-下图显示了通过网关进行令牌自省的示例（成功）流程。
+令牌自省是通过针对 Oauth 2 授权的服务器来验证令牌及相关请求。
+
+首先，需要在身份认证服务器中创建受信任的客户端，并生成用于自省的有效令牌（JWT）。
+
+下图展示了通过网关进行令牌自省的示例（成功）流程。
-
+
-以下是 curl 命令，用于将插件启用到外部服务。
-通过自省请求标头中提供的令牌，此路由将保护 https://httpbin.org/get（echo 服务）。
+以下示例是在 Route 上启用插件。该 Route 将通过自省请求头中提供的令牌来保护上游：
-```bash
-curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri":"/get",
"plugins":{
@@ -87,26 +107,29 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H
'X-API-KEY: edd1c9f034335f13
}'
```
-以下命令可用于访问新路由。
+以下命令可用于访问新 Route：
-```bash
-curl -i -X GET http://127.0.0.1:9080/get -H "Host: httpbin.org" -H
"Authorization: Bearer {replace_jwt_token}"
+```shell
+curl -i -X GET http://127.0.0.1:9080/get \
+-H "Host: httpbin.org" -H "Authorization: Bearer {replace_jwt_token}"
```
-当 Oauth 2 授权服务器返回结果里面除了 token 之外还有过期时间，token 将在 APISIX 中缓存直至过期。
-具体细节参见：
+在此示例中，插件强制在请求头中设置访问令牌和 Userinfo 对象。
-1. [lua-resty-openidc](https://github.com/zmartzone/lua-resty-openidc) 的文档和代码。
+当 Oauth 2 授权服务器返回结果里除了令牌之外还有过期时间，其中令牌将在 APISIX 中缓存直至过期。有关更多详细信息，请参考：
+
+1. [lua-resty-openidc](https://github.com/zmartzone/lua-resty-openidc) 的文档和源代码。
2. `exp` 字段的定义：[Introspection
Response](https://tools.ietf.org/html/rfc7662#section-2.2)。
### 公钥自省
-您还可以提供 JWT
令牌的公钥来验证令牌。如果您提供了公共密钥和令牌自省端点，则将执行公共密钥工作流，而不是通过身份服务器进行验证。如果要减少额外的网络呼叫并加快过程，可以使用此方法。
+除了令牌自省外，还可以使用 JWT
令牌的公钥进行验证。如果使用了公共密钥和令牌自省端点，就会执行公共密钥工作流，而不是通过身份服务器进行验证。如果要减少额外的网络调用并加快过程，可以使用此方法。
-以下配置显示了如何向路由添加公钥自省。
+以下示例展示了如何将公钥添加到 Route 中：
-```bash
-curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri":"/get",
"plugins":{
@@ -136,16 +159,15 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H
'X-API-KEY: edd1c9f034335f13
#### 通过 OIDC 依赖方认证流程进行身份验证
-当一个请求在请求头或会话 Cookie 中不包含访问令牌时，
-插件可以充当 OIDC 依赖方并重定向到身份提供者的授权端点以通过 OIDC 授权代码流程；
-请参阅 https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth 。
-一旦用户通过身份提供者进行身份验证，插件将代表用户从身份提供者获取和管理访问令牌和更多信息。
-该信息当前存储在会话 Cookie 中，该插件将识别 Cookie 并使用其中的信息，以避免再次执行认证流程。
+当一个请求在请求头或会话 Cookie 中不包含访问令牌时，该插件可以充当 OIDC 依赖方并重定向到身份提供者的授权端点以通过 [OIDC
authorization code
flow](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth)。
+
+一旦用户通过身份提供者进行身份验证，插件将代表用户从身份提供者获取和管理访问令牌和更多信息。该信息当前存储在会话 Cookie 中，该插件将会识别
Cookie 并使用其中的信息，以避免再次执行认证流程。
-以下命令将此操作模式添加到路由：
+以下示例是将此操作模式添加到 Route：
-```bash
-curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/get",
"plugins": {
@@ -169,8 +191,8 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H
'X-API-KEY: edd1c9f034335f13
}'
```
-在该例子中，插件可以强制在各自配置的请求头中设置访问令牌、ID 令牌和 UserInfo 对象。
+在以上示例中，该插件可以强制在配置的请求头中设置访问令牌、ID 令牌和 UserInfo 对象。
## 故障排除
-如果 APISIX 无法解析/连接到身份提供者，请检查/修改 DNS 设置（`conf/config.yaml`）。
+如果 APISIX 无法解析或者连接到身份提供者，请检查或修改配置文件（`./conf/config.yaml`）中的 DNS 设置。
diff --git a/docs/zh/latest/plugins/wolf-rbac.md
b/docs/zh/latest/plugins/wolf-rbac.md
index 8e83fca70..6636ecc77 100644
--- a/docs/zh/latest/plugins/wolf-rbac.md
+++ b/docs/zh/latest/plugins/wolf-rbac.md
@@ -1,5 +1,11 @@
---
title: wolf-rbac
+keywords:
+ - APISIX
+ - Plugin
+ - wolf RBAC
+ - wolf-rbac
+description: 本文介绍了关于 Apache APISIX `wolf-rbac` 插件的基本信息及使用方法。
---
<!--
@@ -23,43 +29,43 @@ title: wolf-rbac
## 描述
-`wolf-rbac` 是一个认证及授权 (rbac) 插件，它需要与 `consumer` 一起配合才能工作。同时需要添加 `wolf-rbac` 到一个
`service` 或 `route` 中。
-rbac 功能由 [wolf](https://github.com/iGeeky/wolf) 提供，有关 `wolf` 的更多信息，请参考 [wolf
文档](https://github.com/iGeeky/wolf)。
+`wolf-rbac` 插件为 [role-based access
control](https://en.wikipedia.org/wiki/Role-based_access_control) 系统提供了添加
[wolf](https://github.com/iGeeky/wolf) 到 Route 或 Service 的功能。此插件需要与
[Consumer](../terminology/consumer.md) 一起使用。
## 属性
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述
|
-| ------------- | ------ | ------ | ------------------------ | ------ |
--------------------------------------------------------------------------------------------------------------------------------------------------
|
-| server | string | 可选 | "http://127.0.0.1:12180"; | | 设置
`wolf-server` 的访问地址
|
-| appid | string | 可选 | "unset" | | 设置应用
id，该应用 id，需要是在 `wolf-console` 中已经添加的应用 id
|
-| header_prefix | string | 可选 | "X-" | | 自定义 http
头的前缀。`wolf-rbac`在鉴权成功后，会在请求头 (用于传给后端) 及响应头 (用于传给前端) 中添加 3 个头：`X-UserId`,
`X-Username`, `X-Nickname` |
+| 名称 | 类型 | 必选项 | 默认值 | 描述
|
+| ------------- | ------ | ------ | ------------------------ |
--------------------------------------------------------------------------------------------------------------------------------------------------
|
+| server | string | 否 | "http://127.0.0.1:12180"; | `wolf-server`
的服务地址。
|
+| appid | string | 否 | "unset" | 在 `wolf-console`
中已经添加的应用 id。
|
+| header_prefix | string | 否 | "X-" | 自定义 HTTP
头的前缀。`wolf-rbac` 在鉴权成功后，会在请求头 (用于传给后端) 及响应头 (用于传给前端) 中添加 3 个 header：`X-UserId`,
`X-Username`, `X-Nickname`。|
## 接口
-插件会增加这些接口：
+该插件在启用时将会增加以下接口：
* /apisix/plugin/wolf-rbac/login
* /apisix/plugin/wolf-rbac/change_pwd
* /apisix/plugin/wolf-rbac/user_info
-需要通过 [public-api](../../../en/latest/plugins/public-api.md) 插件来暴露它。
+:::note
-## 依赖项
+以上接口需要通过 [public-api](../../../en/latest/plugins/public-api.md) 插件暴露。
-### 安装 wolf，并启动服务
+:::
-[Wolf
快速起步](https://github.com/iGeeky/wolf/blob/master/quick-start-with-docker/README-CN.md)
+## 前提条件
-### 添加应用，管理员，普通用户，权限，资源 及给用户授权
+如果要使用这个插件，你必须要[安装
wolf](https://github.com/iGeeky/wolf/blob/master/quick-start-with-docker/README.md)
并启动它。
-[Wolf 管理使用](https://github.com/iGeeky/wolf/blob/master/docs/usage.md)
+完成后，你需要添加`application`、`admin`、`regular user`、`permission`、`resource`
等字段，并将用户授权到
[wolf-console](https://github.com/iGeeky/wolf/blob/master/docs/usage.md)。
-## 如何启用
+## 启用插件
-1. 创建一个 consumer 对象，并设置插件 `wolf-rbac` 的值。
+首先需要创建一个 Consumer 并配置该插件，如下所示：
```shell
-curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/consumers \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"username":"wolf_rbac",
"plugins":{
@@ -72,18 +78,17 @@ curl http://127.0.0.1:9080/apisix/admin/consumers -H
'X-API-KEY: edd1c9f034335f
}'
```
-你也可以通过 web 界面来完成上面的操作，先增加一个 consumer：
-
+:::note
-然后在 consumer 页面中添加 wolf-rbac 插件：
-
+示例中填写的 `appid`，必须是已经在 wolf 控制台中存在的。
-注意：上面填写的 `appid` 需要在 wolf 控制台中已经存在的。
+:::
-2. 创建 Route 或 Service 对象，并开启 `wolf-rbac` 插件。
+然后你需要添加 `wolf-rbac` 插件到 Route 或 Service 中。
```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
"uri": "/*",
@@ -99,14 +104,21 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f1
}'
```
-## 测试插件
+你还可以通过 [APISIX Dashboard](https://github.com/apache/apisix-dashboard) 的 Web
界面完成上述操作。
-#### 为 API 设置路由
+<!--
+
-我们使用 [public-api](../../../en/latest/plugins/public-api.md) 插件来暴露这些 public API.
+
+-->
+
+## 测试插件
+
+你可以使用 [public-api](../../../en/latest/plugins/public-api.md) 插件来暴露 API.
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes/wal -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/wal \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/apisix/plugin/wolf-rbac/login",
"plugins": {
@@ -115,20 +127,17 @@ $ curl http://127.0.0.1:9080/apisix/admin/routes/wal -H
'X-API-KEY: edd1c9f03433
}'
```
-你也需要为 `change_pwd` 和 `user_info` 两个 API 配置路由。
-
-#### 首先进行登录获取 `wolf-rbac` token:
+同样，你需要参考上述命令为 `change_pwd` 和 `user_info` 两个 API 配置路由。
-下面的 `appid`, `username`, `password` 必须为 wolf 系统中真实存在的。
-`authType` 为认证类型，`1` 为密码认证，`2` 为 `LDAP` 认证。默认为 `1`. `wolf` 从 0.5.0 版本开始支持了
`LDAP` 认证。
-
-* 以 POST application/json 方式登陆。
+现在你可以登录并获取 wolf `rbac_token`：
```shell
curl http://127.0.0.1:9080/apisix/plugin/wolf-rbac/login -i \
-H "Content-Type: application/json" \
-d '{"appid": "restful", "username":"test", "password":"user-password",
"authType":1}'
+```
+```
HTTP/1.1 200 OK
Date: Wed, 24 Jul 2019 10:33:31 GMT
Content-Type: text/plain
@@ -138,7 +147,15 @@ Server: APISIX web server
{"rbac_token":"V1#restful#eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6NzQ5LCJ1c2VybmFtZSI6InRlc3QiLCJtYW5hZ2VyIjoiIiwiYXBwaWQiOiJyZXN0ZnVsIiwiaWF0IjoxNTc5NDQ5ODQxLCJleHAiOjE1ODAwNTQ2NDF9.n2-830zbhrEh6OAxn4K_yYtg5pqfmjpZAjoQXgtcuts","user_info":{"nickname":"test","username":"test","id":"749"}}
```
-* 以 POST x-www-form-urlencoded 方式登陆
+:::note
+
+上述示例中，`appid`、`username` 和 `password` 必须为 wolf 系统中真实存在的。
+
+`authType` 为认证类型，`1` 为密码认证（默认），`2` 为 LDAP 认证。`wolf` 从 0.5.0 版本开始支持了 LDAP 认证。
+
+:::
+
+也可以使用 x-www-form-urlencoded 方式登陆：
```shell
curl http://127.0.0.1:9080/apisix/plugin/wolf-rbac/login -i \
@@ -146,71 +163,79 @@ curl http://127.0.0.1:9080/apisix/plugin/wolf-rbac/login
-i \
-d 'appid=restful&username=test&password=user-password'
```
-#### 使用获取到的 token 进行请求尝试
+现在开始测试 Route：
-* 缺少 token
+- 缺少 token
```shell
curl http://127.0.0.1:9080/ -H"Host: www.baidu.com" -i
+```
+```shell
HTTP/1.1 401 Unauthorized
...
{"message":"Missing rbac token in request"}
```
-* token 放到请求头 (Authorization) 中：
+- token 放到请求头 (Authorization) 中：
```shell
curl http://127.0.0.1:9080/ -H"Host: www.baidu.com" \
-H 'Authorization:
V1#restful#eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6NzQ5LCJ1c2VybmFtZSI6InRlc3QiLCJtYW5hZ2VyIjoiIiwiYXBwaWQiOiJyZXN0ZnVsIiwiaWF0IjoxNTc5NDQ5ODQxLCJleHAiOjE1ODAwNTQ2NDF9.n2-830zbhrEh6OAxn4K_yYtg5pqfmjpZAjoQXgtcuts'
-i
+```
+```shell
HTTP/1.1 200 OK
<!DOCTYPE html>
```
-* token 放到请求头 (x-rbac-token) 中：
+- token 放到请求头 (x-rbac-token) 中：
```shell
curl http://127.0.0.1:9080/ -H"Host: www.baidu.com" \
-H 'x-rbac-token:
V1#restful#eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6NzQ5LCJ1c2VybmFtZSI6InRlc3QiLCJtYW5hZ2VyIjoiIiwiYXBwaWQiOiJyZXN0ZnVsIiwiaWF0IjoxNTc5NDQ5ODQxLCJleHAiOjE1ODAwNTQ2NDF9.n2-830zbhrEh6OAxn4K_yYtg5pqfmjpZAjoQXgtcuts'
-i
+```
-
+```shell
HTTP/1.1 200 OK
<!DOCTYPE html>
```
-* token 放到请求参数中：
+- token 放到请求参数中：
```shell
curl
'http://127.0.0.1:9080?rbac_token=V1%23restful%23eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6NzQ5LCJ1c2VybmFtZSI6InRlc3QiLCJtYW5hZ2VyIjoiIiwiYXBwaWQiOiJyZXN0ZnVsIiwiaWF0IjoxNTc5NDQ5ODQxLCJleHAiOjE1ODAwNTQ2NDF9.n2-830zbhrEh6OAxn4K_yYtg5pqfmjpZAjoQXgtcuts'
-H"Host: www.baidu.com" -i
+```
-
+```shell
HTTP/1.1 200 OK
<!DOCTYPE html>
```
-* token 放到 cookie 中：
+- token 放到 `cookie` 中：
```shell
curl http://127.0.0.1:9080 -H"Host: www.baidu.com" \
--cookie
x-rbac-token=V1#restful#eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6NzQ5LCJ1c2VybmFtZSI6InRlc3QiLCJtYW5hZ2VyIjoiIiwiYXBwaWQiOiJyZXN0ZnVsIiwiaWF0IjoxNTc5NDQ5ODQxLCJleHAiOjE1ODAwNTQ2NDF9.n2-830zbhrEh6OAxn4K_yYtg5pqfmjpZAjoQXgtcuts
-i
+```
-
+```shell
HTTP/1.1 200 OK
<!DOCTYPE html>
```
-#### 获取 `RBAC` 用户信息
+- 获取用户信息：
```shell
curl http://127.0.0.1:9080/apisix/plugin/wolf-rbac/user_info \
--cookie
x-rbac-token=V1#restful#eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6NzQ5LCJ1c2VybmFtZSI6InRlc3QiLCJtYW5hZ2VyIjoiIiwiYXBwaWQiOiJyZXN0ZnVsIiwiaWF0IjoxNTc5NDQ5ODQxLCJleHAiOjE1ODAwNTQ2NDF9.n2-830zbhrEh6OAxn4K_yYtg5pqfmjpZAjoQXgtcuts
-i
+```
-
+```shell
HTTP/1.1 200 OK
{
"user_info":{
@@ -229,25 +254,27 @@ HTTP/1.1 200 OK
}
```
-#### 修改 `RBAC` 用户密码
+- 更改用户的密码：
```shell
curl http://127.0.0.1:9080/apisix/plugin/wolf-rbac/change_pwd \
-H "Content-Type: application/json" \
--cookie
x-rbac-token=V1#restful#eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6NzQ5LCJ1c2VybmFtZSI6InRlc3QiLCJtYW5hZ2VyIjoiIiwiYXBwaWQiOiJyZXN0ZnVsIiwiaWF0IjoxNTc5NDQ5ODQxLCJleHAiOjE1ODAwNTQ2NDF9.n2-830zbhrEh6OAxn4K_yYtg5pqfmjpZAjoQXgtcuts
-i \
-X PUT -d '{"oldPassword": "old password", "newPassword": "new password"}'
+```
-
+```shell
HTTP/1.1 200 OK
{"message":"success to change password"}
```
## 禁用插件
-当你想去掉 `rbac-wolf` 插件的时候，很简单，在 routes 中的插件配置中把对应的 `插件` 配置删除即可，无须重启服务，即刻生效：
+当你需要禁用 `wolf-rbac` 插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
"uri": "/*",
