This is an automated email from the ASF dual-hosted git repository.
membphis pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-apisix.git
The following commit(s) were added to refs/heads/master by this push:
new 0a8b739 doc: add Chinese translation of authz-keycloak plugin (#1729)
0a8b739 is described below
commit 0a8b73930ef89a0357947766805c3078c73dd0c8
Author: hellmage <luyunxi...@gmail.com>
AuthorDate: Thu Jun 18 21:38:09 2020 +0800
doc: add Chinese translation of authz-keycloak plugin (#1729)
---
doc/README.md | 1 +
doc/README_CN.md | 1 +
doc/plugins/authz-keycloak-cn.md | 124 +++++++++++++++++++++++++++++++++++++++
doc/plugins/authz-keycloak.md | 14 ++---
4 files changed, 133 insertions(+), 7 deletions(-)
diff --git a/doc/README.md b/doc/README.md
index 7a3c5a5..2f6c617 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -65,6 +65,7 @@ Plugins
* [kafka-logger](plugins/kafka-logger.md): Log requests to External Kafka
servers.
* [cors](plugins/cors.md): Enable CORS(Cross-origin resource sharing) for your
API.
* [batch-requests](plugins/batch-requests.md): Allow you send mutiple http api
via **http pipeline**.
+* [authz-keycloak](plugins/authz-keycloak.md): Authorization with Keycloak
Identity Server
Deploy to the Cloud
=======
diff --git a/doc/README_CN.md b/doc/README_CN.md
index 5c61f1c..93c39b4 100644
--- a/doc/README_CN.md
+++ b/doc/README_CN.md
@@ -66,3 +66,4 @@ Reference document
* [kafka-logger](plugins/kafka-logger-cn.md): 将请求记录到外部Kafka服务器。
* [cors](plugins/cors-cn.md): 为你的API启用CORS.
* [batch-requests](plugins/batch-requests-cn.md): 以 **http pipeline**
的方式在网关一次性发起多个 `http` 请求。
+* [authz-keycloak](plugins/authz-keycloak-cn.md): 支持 Keycloak 身份认证服务器
diff --git a/doc/plugins/authz-keycloak-cn.md b/doc/plugins/authz-keycloak-cn.md
new file mode 100644
index 0000000..7a8e881
--- /dev/null
+++ b/doc/plugins/authz-keycloak-cn.md
@@ -0,0 +1,124 @@
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+[English](authz-keycloak.md)
+
+# 目录
+- [**名字**](#名字)
+- [**属性**](#属性)
+- [**如何启用**](#如何启用)
+- [**测试插件**](#测试插件)
+- [**禁用插件**](#禁用插件)
+- [**示例**](#示例)
+
+## 名字
+
+`authz-keycloak` 是和 Keycloak Identity Server 配合使用的鉴权插件。Keycloak 是一种兼容
OAuth/OIDC 和 UMA 协议的身份认证服务器。尽管本插件是和 Keycloak 服务器配合开发的，但也应该能够适配任意兼容 OAuth/OIDC 和
UMA 协议的身份认证服务器。
+
+有关 Keycloak 的更多信息，可参考 [Keycloak Authorization
Docs](https://www.keycloak.org/docs/latest/authorization_services) 查看更多信息。
+
+## 属性
+
+|名称 |选项 |描述|
+|--------- |-------- |-----------|
+| token_endpoint|必填 |接受 OAuth2 兼容 token 的接口，需要支持
`urn:ietf:params:oauth:grant-type:uma-ticket` 授权类型|
+| grant_type |选填 |默认值为 `urn:ietf:params:oauth:grant-type:uma-ticket`|
+| audience |选填 |客户端应用访问相应的资源服务器时所需提供的身份信息。当 permissions
参数有值时这个参数是必填的。|
+| permissions |选填
|描述客户端应用所需访问的资源和权限范围的字符串。格式必须为：`RESOURCE_ID#SCOPE_ID`|
+| timeout |选填 |与身份认证服务器的 http 连接的超时时间。默认值为 3 秒。|
+| policy_enforcement_mode|必填 |只能是 ENFORCING 或 PERMISSIVE。|
+
+### 策略执行模式
+
+定义了在处理身份认证请求时如何应用策略
+
+**Enforcing**
+
+- （默认）如果资源没有绑定任何访问策略，请求默认会被拒绝。
+
+**Permissive**
+
+- 如果资源没有绑定任何访问策略，请求会被允许。
+
+## 如何启用
+
+创建一个 `route` 对象，并在该 `route` 对象上启用 `authz-keycloak` 插件：
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "uri": "/get",
+ "plugins": {
+ "authz-keycloak": {
+ "token_endpoint":
"http://127.0.0.1:8090/auth/realms/{client_id}/protocol/openid-connect/token";,
+ "permissions": ["resource name#scope name"],
+ "audience": "Client ID"
+ }
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:8080": 1
+ }
+ }
+}
+```
+
+## 测试插件
+
+```shell
+curl http://127.0.0.1:9080/get -H 'Authorization: Bearer {JWT Token}'
+```
+
+## 禁用插件
+
+在插件设置页面中删除相应的 json 配置即可禁用 `authz-keycloak` 插件。APISIX 的插件是热加载的，因此无需重启 APISIX 服务。
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "uri": "/get",
+ "plugins": {
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:8080": 1
+ }
+ }
+}
+```
+
+## 示例
+
+请查看 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 服务器上配置访问策略：
+
+
+
+## 后续开发
+
+- 目前 `authz-plugin` 仅支持通过定义资源名和访问权限范畴来应用 `route` 的访问策略。但是 Keycloak
官方适配的其他语言的客户端 (Java, JS) 还可以通过动态查询 Keycloak 路径以及懒加载身份资源的路径来支持路径匹配。未来版本的
`authz-plugin` 将会支持这项功能。
+
+- 支持从 Keycloak JSON 文件中读取权限范畴和其他配置项。
diff --git a/doc/plugins/authz-keycloak.md b/doc/plugins/authz-keycloak.md
index 47b19ae..41dbc27 100644
--- a/doc/plugins/authz-keycloak.md
+++ b/doc/plugins/authz-keycloak.md
@@ -17,7 +17,7 @@
#
-->
-[Chinese](authz-keycloak-cn.md)
+[中文](authz-keycloak-cn.md)
# Summary
- [**Name**](#name)
@@ -34,16 +34,16 @@
UMA compliant Ideneity Server. Although, its developed to working in
conjunction with Keycloak it should work with any
OAuth/OIDC and UMA compliant identity providers as well.
-For more information on JWT, refer to [Keycloak Authorization
Docs](https://www.keycloak.org/docs/latest/authorization_services) for more
information.
+For more information on Keycloak, refer to [Keycloak Authorization
Docs](https://www.keycloak.org/docs/latest/authorization_services) for more
information.
## Attributes
|Name |Requirement |Description|
|--------- |-------- |-----------|
-| token_endpoint|required |A OAuth2-compliant Token Endpoint that
supports the urn:ietf:params:oauth:grant-type:uma-ticket grant type.|
+| token_endpoint|required |A OAuth2-compliant Token Endpoint that
supports the `urn:ietf:params:oauth:grant-type:uma-ticket` grant type.|
| grant_type |optional |Default value is
`urn:ietf:params:oauth:grant-type:uma-ticket`.|
| audience |optional |The client identifier of the resource server
to which the client is seeking access. This parameter is mandatory in case the
permission parameter is defined.|
-| permissions |optional |This parameter is optional. A string
representing a set of one or more resources and scopes the client is seeking
access. The format of the string must be: RESOURCE_ID#SCOPE_ID.|
+| permissions |optional |This parameter is optional. A string
representing a set of one or more resources and scopes the client is seeking
access. The format of the string must be: `RESOURCE_ID#SCOPE_ID`.|
| timeout |optional |Timeout for the http connection with the
Identity Server. Default is 3 seconds|
| policy_enforcement_mode|required |Enforcing or Permissive.|
@@ -63,7 +63,7 @@ Specifies how policies are enforced when processing
authorization requests sent
## How To Enable
-Create a route and enable the authz-keycloak plugin on the route:
+Create a `route` and enable the `authz-keycloak` plugin on the route:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -128,8 +128,8 @@ The following image shows how the policies are configures
in the Keycloak server
## Future Development
-- Currently the authz-plugin requires to define the resource name and required
scopes inorder to enforce policies for the routes.
+- Currently the `authz-plugin` requires to define the resource name and
required scopes in order to enforce policies for the routes.
However, Keycloak's official adapters (Java, JS) also provides path matching
by querying Keycloak paths dynamically, and
-lazy loading the paths to identify resources. Future version on authz-plugin
will support this functionality.
+lazy loading the paths to identity resources. Future version on authz-plugin
will support this functionality.
- Support to read scope and configurations from the Keycloak JSON File
