juzhiyuan commented on code in PR #6974: URL: https://github.com/apache/apisix/pull/6974#discussion_r867305843
########## docs/zh/latest/plugins/authz-casdoor.md: ########## @@ -0,0 +1,102 @@ +--- +title: authz-casdoor +keywords: + - APISIX + - Plugin + - Authz Casdoor + - authz-casdoor +description: 本篇文档介绍了 Apache APISIX auth-casdoor 插件的相关信息。 +--- + +<!-- +# +# 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. +# +--> + +## 描述 + +使用 `authz-casdoor` 插件可添加 [Casdoor](https://casdoor.org/) 集中认证方式。 + +## 属性 + +| 名称 | 类型 | 必选项 | 描述 | +|---------------|--------|----------|----------------------------------------------| +| endpoint_addr | string | 是 | Casdoor 的 URL。 | +| client_id | string | 是 | Casdoor 的客户端 id。 | +| client_secret | string | 是 | Casdoor 的客户端密码。 | +| callback_url | string | 是 | 用于接收状态和代码的回调 URL。 | Review Comment: ```suggestion | callback_url | string | 是 | 用于接收 code 与 state 的回调地址。 | ``` ########## docs/zh/latest/plugins/authz-casdoor.md: ########## @@ -0,0 +1,102 @@ +--- +title: authz-casdoor +keywords: + - APISIX + - Plugin + - Authz Casdoor + - authz-casdoor +description: 本篇文档介绍了 Apache APISIX auth-casdoor 插件的相关信息。 +--- + +<!-- +# +# 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. +# +--> + +## 描述 + +使用 `authz-casdoor` 插件可添加 [Casdoor](https://casdoor.org/) 集中认证方式。 + +## 属性 + +| 名称 | 类型 | 必选项 | 描述 | +|---------------|--------|----------|----------------------------------------------| +| endpoint_addr | string | 是 | Casdoor 的 URL。 | +| client_id | string | 是 | Casdoor 的客户端 id。 | +| client_secret | string | 是 | Casdoor 的客户端密码。 | Review Comment: ```suggestion | client_secret | string | 是 | Casdoor 的客户端密钥。 | ``` ########## docs/zh/latest/plugins/authz-casdoor.md: ########## @@ -0,0 +1,102 @@ +--- +title: authz-casdoor +keywords: + - APISIX + - Plugin + - Authz Casdoor + - authz-casdoor +description: 本篇文档介绍了 Apache APISIX auth-casdoor 插件的相关信息。 +--- + +<!-- +# +# 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. +# +--> + +## 描述 + +使用 `authz-casdoor` 插件可添加 [Casdoor](https://casdoor.org/) 集中认证方式。 + +## 属性 + +| 名称 | 类型 | 必选项 | 描述 | +|---------------|--------|----------|----------------------------------------------| +| endpoint_addr | string | 是 | Casdoor 的 URL。 | +| client_id | string | 是 | Casdoor 的客户端 id。 | +| client_secret | string | 是 | Casdoor 的客户端密码。 | +| callback_url | string | 是 | 用于接收状态和代码的回调 URL。 | + +:::info IMPORTANT + +指定 `endpoint_addr` 和 `callback_url` 属性时不要以 “/” 来结尾。 + +`callback_url` 必须是路由的 URI。具体细节可查看下方示例内容，了解相关配置。 + +::: + +## 启用插件 + +以下示例展示了如何在指定路由上启用 `auth-casdoor` 插件： + +```shell +curl "http://127.0.0.1:9080/apisix/admin/routes/1"; -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d ' +{ + "methods": ["GET"], + "uri": "/anything/*", + "plugins": { + "authz-casdoor": { + "endpoint_addr":"http://localhost:8000";, + "callback_url":"http://localhost:9080/anything/callback";, + "client_id":"7ceb9b7fda4a9061ec1c", + "client_secret":"3416238e1edf915eac08b8fe345b2b95cdba7e04" + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } +}' +``` + +## 测试插件 + +一旦启用了该插件，访问该路由的新用户首先会经过 `authz-casdoor` 插件的处理，然后被重定向到 Casdoor 登录页面。 + +成功登录后，Casdoor 会将该用户重定向到 `callback_url`，并指定 GET 参数的 `code` 和 `state`。该插件还会向 Casdoor 请求一个访问 Token，并确认用户是否真正登录了。该过程只运行一次，后续请求将不会被此打断。 + +上述操作完成后，用户就会被重定向到他们本想访问的原始 URL 页面。 Review Comment: ```suggestion 上述操作完成后，用户会被重定向到目标 URL。 ``` ########## docs/en/latest/plugins/authz-casdoor.md: ########## @@ -85,3 +85,22 @@ Once you have enabled the Plugin, a new user visiting this Route would first be After successfully logging in, Casdoor will redirect this user to the `callback_url` with GET parameters `code` and `state` specified. The Plugin will also request for an access token and confirm whether the user is really logged in. This process is only done once and subsequent requests are left uninterrupted. Once this is done, the user is redirected to the original URL they wanted to visit. + +## Disable Plugin + +To disable the `authz-casdoor` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect. + +```shell +curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' +{ + "methods": ["GET"], + "uri": "/anything/*", Review Comment: One suggestion: we'd better use a more straightforward URI instead of `/anything`, for people would get confused if they don't know this is from `httpbin.org/anything`. (No need to do this in this PR) ########## docs/zh/latest/plugins/ldap-auth.md: ########## @@ -0,0 +1,155 @@ +--- +title: ldap-auth +keywords: + - APISIX + - Plugin + - LDAP Authentication + - ldap-auth +description: 本篇文档介绍了 Apache APISIX ldap-auth 插件的相关信息。 +--- + +<!-- +# +# 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. +# +--> + +## 描述 + +`ldap-auth` 插件可用于给路由或服务添加 LDAP 身份认证，该插件使用 [lualdap](https://lualdap.github.io/lualdap/) 连接 LDAP 服务器。 Review Comment: ```suggestion `ldap-auth` 插件可用于给路由（Route）或服务（Service）添加 LDAP 身份认证，该插件使用 [lualdap](https://lualdap.github.io/lualdap/) 连接 LDAP 服务器。 ``` ########## docs/zh/latest/plugins/ldap-auth.md: ########## @@ -0,0 +1,155 @@ +--- +title: ldap-auth +keywords: + - APISIX + - Plugin + - LDAP Authentication + - ldap-auth +description: 本篇文档介绍了 Apache APISIX ldap-auth 插件的相关信息。 +--- + +<!-- +# +# 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. +# +--> + +## 描述 + +`ldap-auth` 插件可用于给路由或服务添加 LDAP 身份认证，该插件使用 [lualdap](https://lualdap.github.io/lualdap/) 连接 LDAP 服务器。 + +该插件需要与 Consumer 一起配合使用，API 的调用方可以使用 [basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) 与 LDAP 服务器进行认证。 + +## 属性 + +Consumer 端： + +| 名称 | 类型 | 必选项 | 描述 | +| ------- | ------ | -------- | -------------------------------------------------------------------------------- | +| user_dn | string | 是 | LDAP 客户端的 dn，例如：`cn=user01,ou=users,dc=example,dc=org`。 | + +Route 端： + +| 名称 | 类型 | 必选项 | 默认值 | 描述 | +|----------|---------|----------|---------|------------------------------------------------------------------------| +| base_dn | string | 是 | | LDAP 服务器的 dn，例如：`ou=users,dc=example,dc=org`。| +| ldap_uri | string | 是 | | LDAP 服务器的 URI。 | +| use_tls | boolean | 否 | true | 如果设置为 `true` 则表示启用 TLS。 | +| uid | string | 否 | cn | UID 属性。 | + +## 启用插件 + +首先，你需要创建一个 Consumer 并在其中配置该插件，具体代码如下： + +```shell +curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' +{ + "username": "foo", + "plugins": { + "ldap-auth": { + "user_dn": "cn=user01,ou=users,dc=example,dc=org" + } + } +}' +``` + +然后就可以在指定 Route 或 Service 中启用该插件，具体代码如下： Review Comment: We should have a unified style: use Route/Service or `路由/服务` or `Route（路由）` ########## docs/zh/latest/plugins/ldap-auth.md: ########## @@ -0,0 +1,155 @@ +--- +title: ldap-auth +keywords: + - APISIX + - Plugin + - LDAP Authentication + - ldap-auth +description: 本篇文档介绍了 Apache APISIX ldap-auth 插件的相关信息。 +--- + +<!-- +# +# 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. +# +--> + +## 描述 + +`ldap-auth` 插件可用于给路由或服务添加 LDAP 身份认证，该插件使用 [lualdap](https://lualdap.github.io/lualdap/) 连接 LDAP 服务器。 + +该插件需要与 Consumer 一起配合使用，API 的调用方可以使用 [basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) 与 LDAP 服务器进行认证。 Review Comment: Could we use Docusaurus's mark like Info or Warn? ########## docs/zh/latest/plugins/opa.md: ########## @@ -0,0 +1,318 @@ +--- +title: opa +keywords: + - APISIX + - Plugin + - Open Policy Agent + - opa +description: 本篇文档介绍了 Apache APISIX opa 插件的相关信息。 +--- + +<!-- +# +# 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. +# +--> + +## 描述 + +`opa` 插件可用于与 [Open Policy Agent](https://www.openpolicyagent.org) 进行集成，实现后端服务的认证授权与访问服务等功能解耦，减少系统复杂性。 + +## 属性 + +| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | +|-------------------|---------|----------|---------|---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| host | string | 是 | | | OPA 服务的主机地址，例如 `https://localhost:8181`。 | +| ssl_verify | boolean | 否 | true | | 当设置为 `true` 时，将验证 SSL 证书。 | +| policy | string | 是 | | | OPA 策略路径，是 `package` 和 `decision` 配置的组合。当使用高级功能（如自定义响应）时，你可以省略 `decision` 配置。 | +| timeout | integer | 否 | 3000ms | [1, 60000]ms | 设置 HTTP 调用超时时间。 | +| keepalive | boolean | 否 | true | | 当设置为 `true` 时，将为多个请求保持连接并处于活动状态。 | +| keepalive_timeout | integer | 否 | 60000ms | [1000, ...]ms | 连接断开后的闲置时间。 | +| keepalive_pool | integer | 否 | 5 | [1, ...]ms | 连接池限制。 | +| with_route | boolean | 否 | false | | 当设置为 `true` 时，发送关于当前 Route 的信息。 | +| with_service | boolean | 否 | false | | 当设置为 `true` 时，发送关于当前 Service 的信息。 | +| with_consumer | boolean | 否 | false | | 当设置为 `true` 时，发送关于当前 Consumer 的信息。注意，这可能会发送敏感信息，如 API key。请确保在安全的情况下才打开它。 | + +## 数据定义 + +### APISIX 向 OPA 发送信息 + +下述示例代码展示了如何通过 APISIX 向 OPA 服务发送数据： + +```json +{ + "type": "http", + "request": { + "scheme": "http", + "path": "\/get", + "headers": { + "user-agent": "curl\/7.68.0", + "accept": "*\/*", + "host": "127.0.0.1:9080" + }, + "query": {}, + "port": 9080, + "method": "GET", + "host": "127.0.0.1" + }, + "var": { + "timestamp": 1701234567, + "server_addr": "127.0.0.1", + "server_port": "9080", + "remote_port": "port", + "remote_addr": "ip address" + }, + "route": {}, + "service": {}, + "consumer": {} +} +``` + +上述代码具体释义如下： + +- `type` 代表请求类型（如 `http` 或 `stream`）； +- `request` 则需要在 `type` 为 `http` 时使用，包含基本的请求信息（如 URL、头信息等）； +- `var` 包含关于请求连接的基本信息（如 IP、端口、请求时间戳等）； +- `route`、`service` 和 `consumer` 包含的数据与 APISIX 中存储的数据相同，只有当这些对象上配置了 `opa` 插件时才会发送。 + +### OPA 向 APISIX 返回数据 + +下述示例代码展示了 OPA 服务对 APISIX 发送请求后的响应数据： + +```json +{ + "result": { Review Comment: 2 spaces ########## docs/zh/latest/plugins/opa.md: ########## @@ -0,0 +1,318 @@ +--- +title: opa Review Comment: ```suggestion title: Open Policy Agent (OPA) ``` ########## docs/zh/latest/plugins/authz-casdoor.md: ########## @@ -0,0 +1,102 @@ +--- +title: authz-casdoor +keywords: + - APISIX + - Plugin + - Authz Casdoor + - authz-casdoor +description: 本篇文档介绍了 Apache APISIX auth-casdoor 插件的相关信息。 +--- + +<!-- +# +# 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. +# +--> + +## 描述 + +使用 `authz-casdoor` 插件可添加 [Casdoor](https://casdoor.org/) 集中认证方式。 + +## 属性 + +| 名称 | 类型 | 必选项 | 描述 | +|---------------|--------|----------|----------------------------------------------| +| endpoint_addr | string | 是 | Casdoor 的 URL。 | +| client_id | string | 是 | Casdoor 的客户端 id。 | +| client_secret | string | 是 | Casdoor 的客户端密码。 | +| callback_url | string | 是 | 用于接收状态和代码的回调 URL。 | + +:::info IMPORTANT + +指定 `endpoint_addr` 和 `callback_url` 属性时不要以 “/” 来结尾。 + +`callback_url` 必须是路由的 URI。具体细节可查看下方示例内容，了解相关配置。 + +::: + +## 启用插件 + +以下示例展示了如何在指定路由上启用 `auth-casdoor` 插件： + +```shell +curl "http://127.0.0.1:9080/apisix/admin/routes/1"; -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d ' +{ + "methods": ["GET"], + "uri": "/anything/*", + "plugins": { + "authz-casdoor": { + "endpoint_addr":"http://localhost:8000";, + "callback_url":"http://localhost:9080/anything/callback";, + "client_id":"7ceb9b7fda4a9061ec1c", + "client_secret":"3416238e1edf915eac08b8fe345b2b95cdba7e04" + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } +}' +``` + +## 测试插件 + +一旦启用了该插件，访问该路由的新用户首先会经过 `authz-casdoor` 插件的处理，然后被重定向到 Casdoor 登录页面。 + +成功登录后，Casdoor 会将该用户重定向到 `callback_url`，并指定 GET 参数的 `code` 和 `state`。该插件还会向 Casdoor 请求一个访问 Token，并确认用户是否真正登录了。该过程只运行一次，后续请求将不会被此打断。 Review Comment: ```suggestion 成功登录后，Casdoor 会将该用户重定向到 `callback_url`，并指定 GET 参数的 `code` 和 `state`。该插件还会向 Casdoor 请求一个访问 Token，并确认用户是否已登录。在成功认证后该流程只出现一次，后续请求不会被打断。 ``` ########## docs/zh/latest/plugins/opa.md: ########## @@ -0,0 +1,318 @@ +--- +title: opa +keywords: + - APISIX + - Plugin + - Open Policy Agent + - opa +description: 本篇文档介绍了 Apache APISIX opa 插件的相关信息。 Review Comment: ```suggestion description: 本篇文档介绍了 Apache APISIX 通过 OPA 插件与 Open Policy Agent 对接的相关信息。 ``` ########## docs/zh/latest/plugins/opa.md: ########## @@ -0,0 +1,318 @@ +--- +title: opa +keywords: + - APISIX + - Plugin + - Open Policy Agent + - opa +description: 本篇文档介绍了 Apache APISIX opa 插件的相关信息。 +--- + +<!-- +# +# 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. +# +--> + +## 描述 + +`opa` 插件可用于与 [Open Policy Agent](https://www.openpolicyagent.org) 进行集成，实现后端服务的认证授权与访问服务等功能解耦，减少系统复杂性。 + +## 属性 + +| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | +|-------------------|---------|----------|---------|---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| host | string | 是 | | | OPA 服务的主机地址，例如 `https://localhost:8181`。 | +| ssl_verify | boolean | 否 | true | | 当设置为 `true` 时，将验证 SSL 证书。 | +| policy | string | 是 | | | OPA 策略路径，是 `package` 和 `decision` 配置的组合。当使用高级功能（如自定义响应）时，你可以省略 `decision` 配置。 | +| timeout | integer | 否 | 3000ms | [1, 60000]ms | 设置 HTTP 调用超时时间。 | +| keepalive | boolean | 否 | true | | 当设置为 `true` 时，将为多个请求保持连接并处于活动状态。 | +| keepalive_timeout | integer | 否 | 60000ms | [1000, ...]ms | 连接断开后的闲置时间。 | +| keepalive_pool | integer | 否 | 5 | [1, ...]ms | 连接池限制。 | +| with_route | boolean | 否 | false | | 当设置为 `true` 时，发送关于当前 Route 的信息。 | +| with_service | boolean | 否 | false | | 当设置为 `true` 时，发送关于当前 Service 的信息。 | +| with_consumer | boolean | 否 | false | | 当设置为 `true` 时，发送关于当前 Consumer 的信息。注意，这可能会发送敏感信息，如 API key。请确保在安全的情况下才打开它。 | + +## 数据定义 + +### APISIX 向 OPA 发送信息 + +下述示例代码展示了如何通过 APISIX 向 OPA 服务发送数据： + +```json +{ + "type": "http", Review Comment: We'd better keep 2 spaces for JSON (Could do this in a separate PR) -- 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: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
