You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by GitBox <gi...@apache.org> on 2022/04/21 02:33:31 UTC
[GitHub] [apisix] hf400159 opened a new pull request, #6895: docs: update "Authentication" Plugins
hf400159 opened a new pull request, #6895:
URL: https://github.com/apache/apisix/pull/6895
### Description
Updates the Chinese documentation of the "Authentication" Plugins.
Fixes issue [6833](https://github.com/apache/apisix/issues/6833).
### Checklist
- [ ] I have explained the need for this PR and the problem it solves
- [ ] I have explained the changes or the new features added to this PR
- [ ] I have added tests corresponding to this change
- [ ] I have updated the documentation to reflect this change
- [ ] I have verified that this change is backward compatible (If not, please discuss on the [APISIX mailing list](https://github.com/apache/apisix/tree/master#community) first)
<!--
Note
1. Mark the PR as draft until it's ready to be reviewed.
2. Always add/update tests for any changes unless you have a good reason.
3. Always update the documentation to reflect the changes made in the PR.
4. Make a new commit to resolve conversations instead of `push -f`.
5. To resolve merge conflicts, merge master instead of rebasing.
6. Use "request review" to notify the reviewer after making changes.
7. Only a reviewer can mark a conversation as resolved.
-->
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854895134
##########
docs/zh/latest/plugins/hmac-auth.md:
##########
@@ -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 UI 完成操作。
Review Comment:
```suggestion
你也可以通过 [APISIX Dashboard](/docs/dashboard/USER_GUIDE) 的 Web UI 完成操作。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854902926
##########
docs/zh/latest/plugins/hmac-auth.md:
##########
@@ -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 中的某一项不存在，也需要使用一个空字符串代替。
+签名的计算公式为 `signature = HMAC-SHAx-HEX(secret_key, signing_string)`。
Review Comment:
```suggestion
需注意，在使用 `hmac-auth` 插件时，会涉及到签名。签名的计算公式为 `signature = HMAC-SHAx-HEX(secret_key, signing_string)`。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854918379
##########
docs/zh/latest/plugins/jwt-auth.md:
##########
@@ -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 一起使用
Review Comment:
```suggestion
### 与 HashiCorp Vault 集成使用
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854995733
##########
docs/zh/latest/plugins/authz-keycloak.md:
##########
@@ -23,43 +29,131 @@ 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 与此值进行比较。 |
+
+<!--
+下述描述需要认真 review！
+-->
+
+### Discovery and endpoints
+
+使用 `discovery` 属性后，`authz-keycloak` 插件就可以从中发现 Keycloak API 的端点。
+
+如果你设置了该参数，`token_endpoint` 和 `resource_registration_endpoint` 将覆盖从发现文档中获得的值。
+
+### Client ID and secret
+
+该插件需要配置 `client_id` 或 `audience`（用于向后兼容）属性来识别，并且此属性指定该插件在与 Keycloak 交互时进行评估权限的背景。
+
+如果两者都已经配置，则 `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
-**Enforcing**
+有效权限可以是单个资源，也可以是与一个或多个范围配对的资源。
-- 默认模式，如果资源没有绑定任何访问策略，请求默认会被拒绝。
+:::
-**Permissive**
+如果 `lazy_load_paths` 属性设置为 `true`，则请求 URI 将解析为使用资源注册端点在 Keycloak 中配置的一个或多个资源。已经解析的资源被用作于检查的权限。
-- 如果资源没有绑定任何访问策略，请求会被允许。
+:::note
+
+需要该插件从令牌端点为自己获取单独的访问令牌。因此，请确保在 Keycloak 的客户端设置中设置了 `Service Accounts Enabled` 选项。
+
+还需要确保颁发的访问令牌包含具有 `uma_protection` 角色的 `resource_access` 声明，以保证插件能够通过 Protection API 查询资源。
+
+:::
+
+### Automatically mapping HTTP method to scope
+
+`http_method_as_scope` 通常与 `lazy_load_paths` 一起使用，但也可以与静态权限列表一起使用。
+
+如果 `http_method_as_scope` 属性设置为 `true`，插件会将请求的 HTTP 方法映射到同名范围。然后将范围添加到每个要检查的权限。
+
+如果 `lazy_load_paths` 属性设置为 `false`，则插件会将映射范围添加到 `permissions` 属性中配置的任意一个静态权限——即使它们已经包含一个或多个范围。
Review Comment:
```suggestion
- 如果 `http_method_as_scope` 属性设置为 `true`，插件会将请求的 HTTP 方法映射到同名范围。然后将范围添加到每个要检查的权限。
- 如果 `lazy_load_paths` 属性设置为 `false`，则插件会将映射范围添加到 `permissions` 属性中配置的任意一个静态权限——即使它们已经包含一个或多个范围。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY merged pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY merged PR #6895:
URL: https://github.com/apache/apisix/pull/6895
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854852611
##########
docs/zh/latest/plugins/authz-casbin.md:
##########
@@ -194,33 +214,39 @@ p, admin, *, *
g, alice, admin
```
-以上授权策略规定了任何人都可以使用 `GET` 请求方法访问主页（`/`），而只有具有管理权限的用户可以访问其他页面和使用其他请求方法。
+如果想要了解更多关于 `policy` 和 `model` 的配置，请参考 [examples](https://github.com/casbin/lua-casbin/tree/master/examples)。
+
+上述配置将允许所有人使用 `GET` 请求访问主页（`/`），而只有具有管理员权限的用户才可以访问其他页面并使用其他请求方法。
-例如，在这里，任何人都可以用 `GET` 请求方法访问主页，返回正常。
+如果我们向主页发出 `GET` 请求：
Review Comment:
```suggestion
假设我们向主页发出 `GET` 请求，通常都可以返回正常结果。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854893630
##########
docs/zh/latest/plugins/forward-auth.md:
##########
@@ -106,9 +111,9 @@ curl -X PUT 'http://127.0.0.1:9080/apisix/admin/routes/1' \
}'
```
-我们可以进行下面三个测试：
+完成上述配置后，我们可以通过以下三种方式进行测试：
-1. **request_headers** 从 `client` 转发请求头到 `authorization` 服务
+- 在请求标头中发送认证的详细信息：
Review Comment:
```suggestion
- 在请求头中发送认证的详细信息：
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854916458
##########
docs/zh/latest/plugins/jwt-auth.md:
##########
@@ -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。 |
## 接口
Review Comment:
```suggestion
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854921765
##########
docs/zh/latest/plugins/jwt-auth.md:
##########
@@ -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 UI 完成上述操作。
Review Comment:
```suggestion
你还可以通过 [APISIX Dashboard](https://github.com/apache/apisix-dashboard) 的 Web 界面完成上述操作。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854988133
##########
docs/zh/latest/plugins/authz-keycloak.md:
##########
@@ -23,43 +29,131 @@ 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 与此值进行比较。 |
+
+<!--
+下述描述需要认真 review！
+-->
+
+### Discovery and endpoints
+
+使用 `discovery` 属性后，`authz-keycloak` 插件就可以从中发现 Keycloak API 的端点。
+
+如果你设置了该参数，`token_endpoint` 和 `resource_registration_endpoint` 将覆盖从发现文档中获得的值。
+
+### Client ID and secret
+
+该插件需要配置 `client_id` 或 `audience`（用于向后兼容）属性来识别，并且此属性指定该插件在与 Keycloak 交互时进行评估权限的背景。
+
+如果两者都已经配置，则 `client_id` 优先级最高。
+
+如果 `lazy_load_paths` 属性被设置为 `true`，那么该插件还需要从 Keycloak 中为自己获得一个访问令牌。在这种情况下，如果客户端对 Keycloak 的访问是加密的，就需要配置 `client_secret` 属性。
+
+### Policy enforcement mode
+
+`policy_enforcement_mode` 属性指定了在处理发送到服务器的授权请求时，该插件如何执行策略。
+
+#### `ENFORCING` mode
+
+即使没有与资源关联的策略，请求也会默认被拒绝。
+
+`policy_enforcement_mode` 默认设置为 `ENFORCING`。
+
+#### `PERMISSIVE` mode
+
+如果资源没有绑定任何访问策略，请求会被允许。
Review Comment:
```suggestion
- 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：如果资源没有绑定任何访问策略，也允许请求。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854915132
##########
docs/zh/latest/plugins/jwt-auth.md:
##########
@@ -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 的默认配置。
+:::
Review Comment:
```suggestion
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854932924
##########
docs/zh/latest/plugins/openid-connect.md:
##########
@@ -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）。
-下图显示了通过网关进行令牌自省的示例（成功）流程。
-
+首先我们应该在身份认证服务器中创建受信任的客户端，并生成用于自省的有效令牌（JWT）。
+
+下图展示了通过网关进行令牌自省的示例（成功）流程。
+
+
-以下是 curl 命令，用于将插件启用到外部服务。
-通过自省请求标头中提供的令牌，此路由将保护 https://httpbin.org/get（echo 服务）。
+以下示例是在 Route 上启用插件。该 Rouet 将通过自省请求标头中提供的令牌来保护上游：
Review Comment:
```suggestion
以下示例是在 Route 上启用插件。该 Route 将通过自省请求头中提供的令牌来保护上游：
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854884753
##########
docs/zh/latest/plugins/basic-auth.md:
##########
@@ -23,33 +29,32 @@ title: basic-auth
## 描述
-`basic-auth` 是一个认证插件，它需要与 `consumer` 一起配合才能工作。
+`basic-auth` 插件用于将 [Basic_access_authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) 添加到路由或服务中。
-添加 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 的消费者可以将它们的密钥添加到请求头中以验证其的请求。
Review Comment:
```suggestion
该插件需要与 [Consumer](../architecture-design/consumer.md) 一起使用。API 的消费者可以将它们的密钥添加到请求头中以验证其请求。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854903447
##########
docs/zh/latest/plugins/hmac-auth.md:
##########
@@ -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 中的某一项不存在，也需要使用一个空字符串代替。
+签名的计算公式为 `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` 中的某一项不存在，也需要使用一个空字符串代替：
Review Comment:
```suggestion
为了生成签名需要两个参数：`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` 中的某一项不存在，则需要使用一个空字符串代替：
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854931591
##########
docs/zh/latest/plugins/openid-connect.md:
##########
@@ -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 授权服务器验证令牌来帮助验证请求。
Review Comment:
```suggestion
令牌自省是通过针对 Oauth 2 授权的服务器来验证令牌及相关请求。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854919928
##########
docs/zh/latest/plugins/jwt-auth.md:
##########
@@ -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 算法。
Review Comment:
```suggestion
当前版本的 Apache APISIX 期望存储在 Vault 中机密的密钥名称位于 `secret`、`public_key` 和 `private_key` 之间。前一个用于 HS256/HS512 算法，后两个用于 RS256 算法。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854923662
##########
docs/zh/latest/plugins/key-auth.md:
##########
@@ -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) 一起配合才能工作。然后，消费者将其密钥添加到查询字符串参数或标头中以验证其请求。
Review Comment:
```suggestion
它需要与 [Consumer](../architecture-design/consumer.md) 一起配合才能工作，通过 Consumer 将其密钥添加到查询字符串参数或标头中以验证其请求。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854824796
##########
docs/zh/latest/plugins/authz-casbin.md:
##########
@@ -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 鉴权策略的文本定义。 |
Review Comment:
```suggestion
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854952539
##########
docs/zh/latest/plugins/authz-keycloak.md:
##########
@@ -23,43 +29,131 @@ 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 与此值进行比较。 |
+
+<!--
+下述描述需要认真 review！
+-->
+
Review Comment:
```suggestion
除上述释义外，还有以下需要注意的点：
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854895713
##########
docs/zh/latest/plugins/hmac-auth.md:
##########
@@ -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 UI 完成操作。
-2. 创建 Route 或 Service 对象，并开启 `hmac-auth` 插件。
+<!--
+
+
+
+-->
+
+然后，你可以在 Route 或 Service 中启用插件，如下所示：
Review Comment:
```suggestion
然后就可以在 Route 或 Service 中启用插件，如下所示：
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854938325
##########
docs/zh/latest/plugins/wolf-rbac.md:
##########
@@ -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) 一起使用。
## 属性
Review Comment:
```suggestion
## 属性及接口
```
##########
docs/zh/latest/plugins/wolf-rbac.md:
##########
@@ -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`。|
## 接口
Review Comment:
```suggestion
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854852989
##########
docs/zh/latest/plugins/authz-casbin.md:
##########
@@ -194,33 +214,39 @@ 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`）则可以访问其它页面。
Review Comment:
```suggestion
而拥有管理权限的用户（如 `alice`）则可以访问其它页面。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854852834
##########
docs/zh/latest/plugins/authz-casbin.md:
##########
@@ -194,33 +214,39 @@ 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 错误：
Review Comment:
```suggestion
但如果是一个未经授权的普通用户（例如：`bob` ）访问除 `/` 以外的其他页面，则他将得到一个 403 错误：
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854855175
##########
docs/zh/latest/plugins/authz-keycloak.md:
##########
@@ -23,43 +29,131 @@ title: authz-keycloak
## 描述
-目前 `authz-plugin` 仅支持通过定义资源名和访问权限范畴来应用 `route` 的访问策略。但是 Keycloak 官方适配的其他语言的客户端 (Java, JS) 还可以通过动态查询 Keycloak 路径以及懒加载身份资源的路径来支持路径匹配。未来版本的 `authz-plugin` 将会支持这项功能。
+`authz-keycloak` 插件可用于通过 [Keycloak Identity Server](https://www.keycloak.org/) 添加身份验证。
Review Comment:
```suggestion
使用 `authz-keycloak` 插件可通过 [Keycloak Identity Server](https://www.keycloak.org/) 添加身份验证。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854944649
##########
docs/zh/latest/plugins/wolf-rbac.md:
##########
@@ -138,79 +147,95 @@ 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 系统中真实存在的。
Review Comment:
```suggestion
上述示例中，`appid`、`username` 和 `password` 必须为 wolf 系统中真实存在的。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854956474
##########
docs/zh/latest/plugins/authz-keycloak.md:
##########
@@ -116,21 +213,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 路径以及延迟加载身份资源的路径来提供路径匹配。 即将发布的插件将支持此功能。
Review Comment:
```suggestion
- 目前，`authz-keycloak` 插件通过要求定义资源名称和所需的范围，来强制执行路由策略。但 Keycloak 官方适配的其他语言客户端（Java、JavaScript）仍然可以通过动态查询 Keycloak 路径以及延迟加载身份资源的路径来提供路径匹配。在 Apache APISIX 之后发布的插件中即将支持此功能。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854857844
##########
docs/zh/latest/plugins/authz-keycloak.md:
##########
@@ -23,43 +29,131 @@ 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 与此值进行比较。 |
+
+<!--
+下述描述需要认真 review！
+-->
+
+### Discovery and endpoints
+
+使用 `discovery` 属性后，`authz-keycloak` 插件就可以从中发现 Keycloak API 的端点。
+
+如果你设置了该参数，`token_endpoint` 和 `resource_registration_endpoint` 将覆盖从发现文档中获得的值。
+
+### Client ID and secret
+
+该插件需要配置 `client_id` 或 `audience`（用于向后兼容）属性来识别，并且此属性指定该插件在与 Keycloak 交互时进行评估权限的背景。
+
+如果两者都已经配置，则 `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
-**Enforcing**
+有效权限可以是单个资源，也可以是与一个或多个范围配对的资源。
-- 默认模式，如果资源没有绑定任何访问策略，请求默认会被拒绝。
+:::
-**Permissive**
+如果 `lazy_load_paths` 属性设置为 `true`，则请求 URI 将解析为使用资源注册端点在 Keycloak 中配置的一个或多个资源。已经解析的资源被用作于检查的权限。
-- 如果资源没有绑定任何访问策略，请求会被允许。
+:::note
+
+需要该插件从令牌端点为自己获取单独的访问令牌。因此，请确保在 Keycloak 的客户端设置中设置了 `Service Accounts Enabled` 选项。
+
+还需要确保颁发的访问令牌包含具有 `uma_protection` 角色的 `resource_access` 声明，以保证插件能够通过 Protection API 查询资源。
+
+:::
+
+### Automatically mapping HTTP method to scope
+
+`http_method_as_scope` 通常与 `lazy_load_paths` 一起使用，但也可以与静态权限列表一起使用。
+
+如果 `http_method_as_scope` 属性设置为 `true`，插件会将请求的 HTTP 方法映射到同名范围。然后将范围添加到每个要检查的权限。
+
+如果 `lazy_load_paths` 属性设置为 `false`，则插件会将映射范围添加到 `permissions` 属性中配置的任意一个静态权限——即使它们已经包含一个或多个范围。
+
+### Generating a token using `password` grant
+
+如果要使用 `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` 名称：
Review Comment:
```suggestion
以下示例为你展示了如何在指定 Route 中启用 `authz-keycloak` 插件，其中 `${realm}` 是 Keycloak 中的 `realm` 名称：
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854926250
##########
docs/zh/latest/plugins/key-auth.md:
##########
@@ -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 UI 完成上述操作。
Review Comment:
```suggestion
你还可以通过 [APISIX Dashboard](https://github.com/apache/apisix-dashboard) 的 Web 界面完成上述操作。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854929528
##########
docs/zh/latest/plugins/openid-connect.md:
##########
@@ -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 浏览器进行交互的用户。
Review Comment:
```suggestion
2. 可以将插件配置为：通过 OIDC 授权对没有有效令牌的请求进行身份验证，其中该插件充当 OIDC 依赖方。在这种情况下，认证成功后，该插件可以获得并管理会话 Cookie 中的访问令牌，包含 Cookie 的后续请求将使用访问令牌。你需要将 `bearer_only` 属性设置为 `false` 才可以使用这种模式。这种操作模式可用于支持以下情况：客户端或请求者是通过 Web 浏览器进行交互的用户。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854994052
##########
docs/zh/latest/plugins/authz-keycloak.md:
##########
@@ -23,43 +29,131 @@ 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 与此值进行比较。 |
+
+<!--
+下述描述需要认真 review！
+-->
+
+### Discovery and endpoints
+
+使用 `discovery` 属性后，`authz-keycloak` 插件就可以从中发现 Keycloak API 的端点。
+
+如果你设置了该参数，`token_endpoint` 和 `resource_registration_endpoint` 将覆盖从发现文档中获得的值。
+
+### Client ID and secret
+
+该插件需要配置 `client_id` 或 `audience`（用于向后兼容）属性来识别，并且此属性指定该插件在与 Keycloak 交互时进行评估权限的背景。
+
+如果两者都已经配置，则 `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
-**Enforcing**
+有效权限可以是单个资源，也可以是与一个或多个范围配对的资源。
-- 默认模式，如果资源没有绑定任何访问策略，请求默认会被拒绝。
+:::
-**Permissive**
+如果 `lazy_load_paths` 属性设置为 `true`，则请求 URI 将解析为使用资源注册端点在 Keycloak 中配置的一个或多个资源。已经解析的资源被用作于检查的权限。
-- 如果资源没有绑定任何访问策略，请求会被允许。
+:::note
+
+需要该插件从令牌端点为自己获取单独的访问令牌。因此，请确保在 Keycloak 的客户端设置中设置了 `Service Accounts Enabled` 选项。
+
+还需要确保颁发的访问令牌包含具有 `uma_protection` 角色的 `resource_access` 声明，以保证插件能够通过 Protection API 查询资源。
+
+:::
+
+### Automatically mapping HTTP method to scope
+
+`http_method_as_scope` 通常与 `lazy_load_paths` 一起使用，但也可以与静态权限列表一起使用。
+
+如果 `http_method_as_scope` 属性设置为 `true`，插件会将请求的 HTTP 方法映射到同名范围。然后将范围添加到每个要检查的权限。
+
+如果 `lazy_load_paths` 属性设置为 `false`，则插件会将映射范围添加到 `permissions` 属性中配置的任意一个静态权限——即使它们已经包含一个或多个范围。
+
+### Generating a token using `password` grant
Review Comment:
```suggestion
### 使用`password`授权生成令牌
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854989046
##########
docs/zh/latest/plugins/authz-keycloak.md:
##########
@@ -23,43 +29,131 @@ 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 与此值进行比较。 |
+
+<!--
+下述描述需要认真 review！
+-->
+
+### Discovery and endpoints
+
+使用 `discovery` 属性后，`authz-keycloak` 插件就可以从中发现 Keycloak API 的端点。
+
+如果你设置了该参数，`token_endpoint` 和 `resource_registration_endpoint` 将覆盖从发现文档中获得的值。
+
+### Client ID and secret
+
+该插件需要配置 `client_id` 或 `audience`（用于向后兼容）属性来识别，并且此属性指定该插件在与 Keycloak 交互时进行评估权限的背景。
+
+如果两者都已经配置，则 `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 的权限。
Review Comment:
```suggestion
- 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 的权限。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854909492
##########
docs/zh/latest/plugins/hmac-auth.md:
##########
@@ -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 中的某一项不存在，也需要使用一个空字符串代替。
+签名的计算公式为 `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` 可以是空字符串。
Review Comment:
```suggestion
2. 当该项同时有 `key` 和 `value` 时，转换公式为 `key + "=" + value` 。此处 `value` 可以是空字符串。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854913222
##########
docs/zh/latest/plugins/hmac-auth.md:
##########
@@ -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 名称。如下所示：
Review Comment:
```suggestion
除了配置签名外，你还可以在 `conf/config.yaml` 配置文件中的`plugin_attr` 配置项下，添加 `hmac-auth` 插件的属性来自定义参数 header 名称。如下所示：
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854946940
##########
docs/zh/latest/plugins/wolf-rbac.md:
##########
@@ -138,79 +147,95 @@ 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 \
-H "Content-Type: application/x-www-form-urlencoded" \
-d 'appid=restful&username=test&password=user-password'
```
-#### 使用获取到的 token 进行请求尝试
+现在开始测试路由：
-* 缺少 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` 用户信息
+获取用户信息：
Review Comment:
```suggestion
- 获取用户信息：
```
##########
docs/zh/latest/plugins/wolf-rbac.md:
##########
@@ -229,25 +254,27 @@ HTTP/1.1 200 OK
}
```
-#### 修改 `RBAC` 用户密码
+更改用户的密码：
Review Comment:
```suggestion
- 更改用户的密码：
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854934470
##########
docs/zh/latest/plugins/openid-connect.md:
##########
@@ -87,26 +107,29 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-以下命令可用于访问新路由。
+以下命令可用于访问新路由：
-```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 授权服务器返回结果里面除了 token 之外还有过期时间，token 将在 APISIX 中缓存直至过期。有关更多详细信息，请参考：
Review Comment:
```suggestion
当 Oauth 2 授权服务器返回结果里除了令牌之外还有过期时间，其中令牌将在 APISIX 中缓存直至过期。有关更多详细信息，请参考：
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854933286
##########
docs/zh/latest/plugins/openid-connect.md:
##########
@@ -87,26 +107,29 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-以下命令可用于访问新路由。
+以下命令可用于访问新路由：
-```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 对象。
Review Comment:
```suggestion
在此示例中，插件强制在请求头中设置访问令牌和 Userinfo 对象。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854943569
##########
docs/zh/latest/plugins/wolf-rbac.md:
##########
@@ -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 UI 完成上述操作。
Review Comment:
```suggestion
你还可以通过 [APISIX Dashboard](https://github.com/apache/apisix-dashboard) 的 Web 界面完成上述操作。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854994799
##########
docs/zh/latest/plugins/authz-keycloak.md:
##########
@@ -23,43 +29,131 @@ 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 与此值进行比较。 |
+
+<!--
+下述描述需要认真 review！
+-->
+
+### Discovery and endpoints
+
+使用 `discovery` 属性后，`authz-keycloak` 插件就可以从中发现 Keycloak API 的端点。
+
+如果你设置了该参数，`token_endpoint` 和 `resource_registration_endpoint` 将覆盖从发现文档中获得的值。
+
+### Client ID and secret
+
+该插件需要配置 `client_id` 或 `audience`（用于向后兼容）属性来识别，并且此属性指定该插件在与 Keycloak 交互时进行评估权限的背景。
+
+如果两者都已经配置，则 `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
-**Enforcing**
+有效权限可以是单个资源，也可以是与一个或多个范围配对的资源。
-- 默认模式，如果资源没有绑定任何访问策略，请求默认会被拒绝。
+:::
-**Permissive**
+如果 `lazy_load_paths` 属性设置为 `true`，则请求 URI 将解析为使用资源注册端点在 Keycloak 中配置的一个或多个资源。已经解析的资源被用作于检查的权限。
-- 如果资源没有绑定任何访问策略，请求会被允许。
+:::note
+
+需要该插件从令牌端点为自己获取单独的访问令牌。因此，请确保在 Keycloak 的客户端设置中设置了 `Service Accounts Enabled` 选项。
+
+还需要确保颁发的访问令牌包含具有 `uma_protection` 角色的 `resource_access` 声明，以保证插件能够通过 Protection API 查询资源。
+
+:::
+
+### Automatically mapping HTTP method to scope
+
+`http_method_as_scope` 通常与 `lazy_load_paths` 一起使用，但也可以与静态权限列表一起使用。
+
+如果 `http_method_as_scope` 属性设置为 `true`，插件会将请求的 HTTP 方法映射到同名范围。然后将范围添加到每个要检查的权限。
+
+如果 `lazy_load_paths` 属性设置为 `false`，则插件会将映射范围添加到 `permissions` 属性中配置的任意一个静态权限——即使它们已经包含一个或多个范围。
+
+### Generating a token using `password` grant
+
+如果要使用 `password` 授权生成令牌，你可以设置 `password_grant_token_generation_incoming_uri` 属性的值。
+
+如果传入的 URI 与配置的属性匹配并且请求方法是 POST，则使用 `token_endpoint` 生成一个令牌。
+
+你还需要添加 `application/x-www-form-urlencoded` 作为 `Content-Type` 标头以及 `username` 和 `password` 作为参数。
Review Comment:
```suggestion
同时，你还需要添加 `application/x-www-form-urlencoded` 作为 `Content-Type` 标头，`username` 和 `password` 作为参数。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854995300
##########
docs/zh/latest/plugins/authz-keycloak.md:
##########
@@ -23,43 +29,131 @@ 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 与此值进行比较。 |
+
+<!--
+下述描述需要认真 review！
+-->
+
+### Discovery and endpoints
+
+使用 `discovery` 属性后，`authz-keycloak` 插件就可以从中发现 Keycloak API 的端点。
+
+如果你设置了该参数，`token_endpoint` 和 `resource_registration_endpoint` 将覆盖从发现文档中获得的值。
+
+### Client ID and secret
+
+该插件需要配置 `client_id` 或 `audience`（用于向后兼容）属性来识别，并且此属性指定该插件在与 Keycloak 交互时进行评估权限的背景。
+
+如果两者都已经配置，则 `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
-**Enforcing**
+有效权限可以是单个资源，也可以是与一个或多个范围配对的资源。
-- 默认模式，如果资源没有绑定任何访问策略，请求默认会被拒绝。
+:::
-**Permissive**
+如果 `lazy_load_paths` 属性设置为 `true`，则请求 URI 将解析为使用资源注册端点在 Keycloak 中配置的一个或多个资源。已经解析的资源被用作于检查的权限。
-- 如果资源没有绑定任何访问策略，请求会被允许。
+:::note
+
+需要该插件从令牌端点为自己获取单独的访问令牌。因此，请确保在 Keycloak 的客户端设置中设置了 `Service Accounts Enabled` 选项。
+
+还需要确保颁发的访问令牌包含具有 `uma_protection` 角色的 `resource_access` 声明，以保证插件能够通过 Protection API 查询资源。
+
+:::
+
+### Automatically mapping HTTP method to scope
Review Comment:
```suggestion
### 自动将 HTTP method 映射到作用域
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854852611
##########
docs/zh/latest/plugins/authz-casbin.md:
##########
@@ -194,33 +214,39 @@ p, admin, *, *
g, alice, admin
```
-以上授权策略规定了任何人都可以使用 `GET` 请求方法访问主页（`/`），而只有具有管理权限的用户可以访问其他页面和使用其他请求方法。
+如果想要了解更多关于 `policy` 和 `model` 的配置，请参考 [examples](https://github.com/casbin/lua-casbin/tree/master/examples)。
+
+上述配置将允许所有人使用 `GET` 请求访问主页（`/`），而只有具有管理员权限的用户才可以访问其他页面并使用其他请求方法。
-例如，在这里，任何人都可以用 `GET` 请求方法访问主页，返回正常。
+如果我们向主页发出 `GET` 请求：
Review Comment:
```suggestion
简单举例来说，假设我们向主页发出 `GET` 请求，通常都可以返回正常结果。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854825250
##########
docs/zh/latest/plugins/authz-casbin.md:
##########
@@ -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 鉴权策略的文本定义。 |
Review Comment:
I think this part is similar to lines 40/41, so no need to post again
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854920470
##########
docs/zh/latest/plugins/jwt-auth.md:
##########
@@ -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 验证。
Review Comment:
```suggestion
该插件将在提供的 Vault 路径（<vault.prefix>/consumer/jack/jwt-auth）中查找密钥 `secret`，并将其用于 JWT 身份验证。如果在同一路径中找不到密钥，插件会记录错误并且无法执行 JWT 验证。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854922529
##########
docs/zh/latest/plugins/jwt-auth.md:
##########
@@ -212,26 +244,32 @@ $ curl http://127.0.0.1:9080/apisix/admin/routes/jas -H 'X-API-KEY: edd1c9f03433
}'
```
-之后，我们就可以调用它获取 token 了。
+之后，你就可以调用它获取 token 了。
Review Comment:
```suggestion
之后就可以通过调用它来获取 token 了。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854910994
##########
docs/zh/latest/plugins/hmac-auth.md:
##########
@@ -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`。
Review Comment:
```suggestion
2. SIGNED_HEADERS 为客户端指定的加入加密计算的 headers。若存在多个 headers 需以 ";" 分割，例如：`x-custom-header-a;x-custom-header-b`。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854920865
##########
docs/zh/latest/plugins/jwt-auth.md:
##########
@@ -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 时选择的基本路径进行设置。
Review Comment:
```suggestion
`vault.prefix` 会在配置文件（`conf/config.yaml`）中根据启用 Vault kv secret engine 时选择的基本路径进行设置。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854914239
##########
docs/zh/latest/plugins/jwt-auth.md:
##########
@@ -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` 中用来验证其请求。
Review Comment:
```suggestion
通过 Consumer 将其密匙添加到查询字符串参数、请求头或 `cookie` 中用来验证其请求。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854895134
##########
docs/zh/latest/plugins/hmac-auth.md:
##########
@@ -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 UI 完成操作。
Review Comment:
```suggestion
你也可以通过 [APISIX Dashboard](/docs/dashboard/USER_GUIDE) 的 Web 界面完成操作。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854887804
##########
docs/zh/latest/plugins/forward-auth.md:
##########
@@ -23,36 +28,36 @@ title: forward-auth
## 描述
-`forward-auth` 插件使用的是经典外部认证。在认证失败的时候，我们可以实现自定义错误或者重定向到认证页面。
+`forward-auth` 插件使用的是经典外部认证。当身份认证失败时，你可以实现自定义错误或者重定向到认证页面。
Review Comment:
```suggestion
`forward-auth` 插件使用的是经典外部认证。当身份认证失败时，可以实现自定义错误或者重定向到认证页面的场景。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] juzhiyuan commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r857474278
##########
docs/zh/latest/plugins/authz-casbin.md:
##########
@@ -194,33 +214,39 @@ 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 错误：
Review Comment:
```suggestion
但如果是一个未经授权的普通用户（例如：`bob`）访问除 `/` 以外的其他页面，将得到一个 403 错误：
```
##########
docs/zh/latest/plugins/basic-auth.md:
##########
@@ -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 | 该参数设置为 `ture` 时，则会将 Authorization 请求头传递给 Upstream。|
Review Comment:
```suggestion
| hide_credentials | boolean | 否 | false | 该参数设置为 `true` 时，则会将 Authorization 请求头传递给 Upstream。|
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854885367
##########
docs/zh/latest/plugins/basic-auth.md:
##########
@@ -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) 完成上面的操作。
Review Comment:
```suggestion
你也可以通过 [APISIX Dashboard](/docs/dashboard/USER_GUIDE) 完成上述操作。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854909134
##########
docs/zh/latest/plugins/hmac-auth.md:
##########
@@ -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 中的某一项不存在，也需要使用一个空字符串代替。
+签名的计算公式为 `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` 可以是空字符串。
Review Comment:
```suggestion
2. 当该项同时有 `key` 和 `value` 时，转换公式为 `url_encode(key) + "=" + url_encode(value)` 。此处 `value` 可以是空字符串。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854942846
##########
docs/zh/latest/plugins/wolf-rbac.md:
##########
@@ -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 控制台中已经存在的。
Review Comment:
```suggestion
示例中填写的 `appid`，必须是已经在 wolf 控制台中存在的。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854894490
##########
docs/zh/latest/plugins/hmac-auth.md:
##########
@@ -23,30 +29,31 @@ title: hmac-auth
## 描述
-`hmac-auth` 是一个认证插件，它需要与 `consumer` 一起配合才能工作。
+`hmac-auth` 插件可以将 [HMAC authentication](https://en.wikipedia.org/wiki/HMAC)添加到 Route 或者 Service。
Review Comment:
```suggestion
`hmac-auth` 插件可以将 [HMAC authentication](https://en.wikipedia.org/wiki/HMAC) 添加到 Route 或者 Service。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854892584
##########
docs/zh/latest/plugins/forward-auth.md:
##########
@@ -106,9 +111,9 @@ curl -X PUT 'http://127.0.0.1:9080/apisix/admin/routes/1' \
}'
```
-我们可以进行下面三个测试：
+完成上述配置后，我们可以通过以下三种方式进行测试：
Review Comment:
```suggestion
完成上述配置后，可通过以下三种方式进行测试：
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854858099
##########
docs/zh/latest/plugins/authz-keycloak.md:
##########
@@ -80,29 +174,32 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f13
## 测试插件
-获取 `{JWT Token}`
+通过上述命令启用插件后，可以通过以下方法测试插件。
+
+首先你必须从 Keycloak 获取 JWT 令牌：
Review Comment:
```suggestion
首先需要从 Keycloak 获取 JWT 令牌：
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854927658
##########
docs/zh/latest/plugins/openid-connect.md:
##########
@@ -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。 |
Review Comment:
```suggestion
| discovery | string | 是 | | | 身份服务器发现端点的 URL。 |
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854989046
##########
docs/zh/latest/plugins/authz-keycloak.md:
##########
@@ -23,43 +29,131 @@ 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 与此值进行比较。 |
+
+<!--
+下述描述需要认真 review！
+-->
+
+### Discovery and endpoints
+
+使用 `discovery` 属性后，`authz-keycloak` 插件就可以从中发现 Keycloak API 的端点。
+
+如果你设置了该参数，`token_endpoint` 和 `resource_registration_endpoint` 将覆盖从发现文档中获得的值。
+
+### Client ID and secret
+
+该插件需要配置 `client_id` 或 `audience`（用于向后兼容）属性来识别，并且此属性指定该插件在与 Keycloak 交互时进行评估权限的背景。
+
+如果两者都已经配置，则 `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 的权限。
Review Comment:
```suggestion
- 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 的权限。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854884059
##########
docs/zh/latest/plugins/basic-auth.md:
##########
@@ -23,33 +29,32 @@ title: basic-auth
## 描述
-`basic-auth` 是一个认证插件，它需要与 `consumer` 一起配合才能工作。
+`basic-auth` 插件用于将 [Basic_access_authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) 添加到路由或服务中。
Review Comment:
```suggestion
使用 `basic-auth` 插件可将 [Basic_access_authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) 添加到路由或服务中。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854915936
##########
docs/zh/latest/plugins/jwt-auth.md:
##########
@@ -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-一起使用) 中了解更多信息。
## 属性
Review Comment:
```suggestion
## 属性及接口
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854914239
##########
docs/zh/latest/plugins/jwt-auth.md:
##########
@@ -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` 中用来验证其请求。
Review Comment:
```suggestion
之后 Consumer 会将其密匙添加到查询字符串参数、请求头或 `cookie` 中用来验证其请求。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854921765
##########
docs/zh/latest/plugins/jwt-auth.md:
##########
@@ -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 UI 完成上述操作。
Review Comment:
```suggestion
你还可以通过 [APISIX Dashboard](https://github.com/apache/apisix-dashboard) 的 Web UI 完成上述操作。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854935267
##########
docs/zh/latest/plugins/openid-connect.md:
##########
@@ -87,26 +107,29 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-以下命令可用于访问新路由。
+以下命令可用于访问新路由：
-```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 授权服务器返回结果里面除了 token 之外还有过期时间，token 将在 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 令牌的公钥进行验证。如果使用了公共密钥和令牌自省端点，就会执行公共密钥工作流，而不是通过身份服务器进行验证。如果要减少额外的网络调用并加快过程，可以使用此方法。
Review Comment:
```suggestion
除了令牌自省外，还可以使用 JWT 令牌的公钥进行验证。如果使用了公共密钥和令牌自省端点，就会执行公共密钥工作流，而不是通过身份服务器进行验证。如果要减少额外的网络调用并加快过程，可以使用此方法。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854904348
##########
docs/zh/latest/plugins/hmac-auth.md:
##########
@@ -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 中的某一项不存在，也需要使用一个空字符串代替。
+签名的计算公式为 `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**：从请求头中获取客户端指定的字段，并按顺序拼接字符串的结果。
Review Comment:
```suggestion
- **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**：从请求头中获取客户端指定的字段，并按顺序拼接字符串的结果。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854855538
##########
docs/zh/latest/plugins/authz-keycloak.md:
##########
@@ -23,43 +29,131 @@ 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 协议的身份认证软件一起使用。
Review Comment:
```suggestion
虽然该插件是为了与 Keycloak 一起使用而开发的，但它也可以与任何符合 OAuth/OIDC 或 UMA 协议的身份认证软件一起使用。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854889310
##########
docs/zh/latest/plugins/forward-auth.md:
##########
@@ -23,36 +28,36 @@ title: forward-auth
## 描述
-`forward-auth` 插件使用的是经典外部认证。在认证失败的时候，我们可以实现自定义错误或者重定向到认证页面。
+`forward-auth` 插件使用的是经典外部认证。当身份认证失败时，你可以实现自定义错误或者重定向到认证页面。
-Forward Auth 巧妙地将认证和授权逻辑移到了一个专门的外部服务中，网关将用户的请求转发给认证服务并阻塞原始请求，并在认证服务以非 2xx 状态响应时替换结果。
+`forward-auth` 插件巧妙地将身份认证和授权逻辑移到了一个专门的外部服务中，APISIX 将用户的请求转发给认证服务并阻塞原始请求，并且在认证服务以非 2xx 状态响应时替换结果。
Review Comment:
```suggestion
`forward-auth` 插件巧妙地将身份认证和授权逻辑移到了一个专门的外部服务中，APISIX 将用户的请求转发给认证服务并阻塞原始请求，然后在认证服务下以非 2xx 状态响应时进行结果替换。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854932216
##########
docs/zh/latest/plugins/openid-connect.md:
##########
@@ -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）。
-下图显示了通过网关进行令牌自省的示例（成功）流程。
-
+首先我们应该在身份认证服务器中创建受信任的客户端，并生成用于自省的有效令牌（JWT）。
Review Comment:
```suggestion
首先，需要在身份认证服务器中创建受信任的客户端，并生成用于自省的有效令牌（JWT）。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854931591
##########
docs/zh/latest/plugins/openid-connect.md:
##########
@@ -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 授权服务器验证令牌来帮助验证请求。
Review Comment:
```suggestion
令牌自省是通过针对 Oauth 2 授权的服务器来验证令牌及请求。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854928815
##########
docs/zh/latest/plugins/openid-connect.md:
##########
@@ -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` 属性。这种操作模式可用于服务到服务的通信，在这种模式下，请求者可以合理地获取和管理有效的令牌。
Review Comment:
```suggestion
1. 可以将**插件**配置为：仅验证预期会出现在请求头中的访问令牌。在这种模式下，没有令牌或带有无效令牌的请求将被拒绝。这需要将 `bearer_only` 属性设置为 `true` 并配置 `introspection_endpoint` 或 `public_key` 属性。这种操作模式可用于服务端之间的通信，在这种模式下，请求者可以合理地获取和管理有效的令牌。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854916692
##########
docs/zh/latest/plugins/jwt-auth.md:
##########
@@ -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` 接口。
Review Comment:
```suggestion
同时，该插件会增加 `/apisix/plugin/jwt/sign` 接口。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854919498
##########
docs/zh/latest/plugins/jwt-auth.md:
##########
@@ -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` 插件。
Review Comment:
```suggestion
因此，如果你的企业经常更改 secret/keys（HS256/HS512 的密钥或 RS256 的 public_key 和 private_key）并且你不想每次都更新 APISIX 的 Consumer，或者你不想通过 Admin API（减少信息泄漏），你可以将 Vault 和 `jwt-auth` 插件一起使用。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854923662
##########
docs/zh/latest/plugins/key-auth.md:
##########
@@ -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) 一起配合才能工作。然后，消费者将其密钥添加到查询字符串参数或标头中以验证其请求。
Review Comment:
```suggestion
它需要与 [Consumer](../architecture-design/consumer.md) 一起配合才能工作，通过消费者将其密钥添加到查询字符串参数或标头中以验证其请求。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #6895: docs: update "Authentication" Plugins
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #6895:
URL: https://github.com/apache/apisix/pull/6895#discussion_r854941630
##########
docs/zh/latest/plugins/wolf-rbac.md:
##########
@@ -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`、`普通用户`、`permission`、`resource`和用户授权到 [wolf-console](https://github.com/iGeeky/wolf/blob/master/docs/usage.md)。
Review Comment:
```suggestion
完成后，你需要添加`application`、`admin`、`regular user`、`permission`、`resource` 等字段，并将用户授权到 [wolf-console](https://github.com/iGeeky/wolf/blob/master/docs/usage.md)。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org