hf400159 commented on code in PR #6974: URL: https://github.com/apache/apisix/pull/6974#discussion_r866434091
########## 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` 插件可用于给路由或服务添加 LDAP 身份认证，该插件使用 [lualdap](https://lualdap.github.io/lualdap/) 连接 LDAP 服务器。 ``` ########## docs/zh/latest/plugins/authz-casdoor.md: ########## @@ -0,0 +1,107 @@ +--- +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` 属性时不要以 “/” 来结尾。 + +::: + +:::info IMPORTANT + +`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`。该插件还将请求一个访问 Token，并确认用户是否真正登录了。该过程只运行一次，后续请求将不会被此打断。 + +上述操作完成后，用户就会被重定向到他们本想访问的原始 URL 页面。 + +## 禁用插件 + +当需要禁用 `authz-casdoor` 插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务： + +```shell +curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' +{ + "methods": ["GET"], + "uri": "/*", + "plugins": { + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } +}' Review Comment: ```suggestion curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' { "methods": ["GET"], "uri": "/anything/*", "plugins": {}, "upstream": { "type": "roundrobin", "nodes": { "httpbin.org:80": 1 } } }' ``` ########## docs/en/latest/plugins/authz-casdoor.md: ########## @@ -85,3 +85,23 @@ 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": "/*", + "plugins": { + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } +}' Review Comment: ```suggestion curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' { "methods": ["GET"], "uri": "/anything/*", "plugins": {}, "upstream": { "type": "roundrobin", "nodes": { "httpbin.org:80": 1 } } }' ``` ########## docs/zh/latest/plugins/authz-casdoor.md: ########## @@ -0,0 +1,107 @@ +--- +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` 属性时不要以 “/” 来结尾。 + +::: + +:::info IMPORTANT + +`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 登录页面。 Review Comment: ```suggestion 一旦启用了该插件，访问该路由的新用户首先会经过 `authz-casdoor` 插件的处理，然后被重定向到 Casdoor 登录页面。 ``` ########## 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 客户端的用户可分辨名称，例如：`cn=user01,ou=users,dc=example,dc=org`。 | Review Comment: ```suggestion | user_dn | string | 是 | LDAP 客户端的 dn，例如：`cn=user01,ou=users,dc=example,dc=org`。 | ``` ########## docs/zh/latest/plugins/opa.md: ########## @@ -0,0 +1,315 @@ +--- +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 调用延迟设置。 | Review Comment: ```suggestion | timeout | integer | 否 | 3000ms | [1, 60000]ms | 设置 HTTP 调用超时时间。 | ``` ########## docs/zh/latest/plugins/opa.md: ########## @@ -0,0 +1,315 @@ +--- +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` 时，将为多个请求保持连接状态。 | Review Comment: ```suggestion | keepalive | boolean | 否 | true | | 当设置为 `true` 时，将为多个请求保持连接处于活动状态。 | ``` ########## docs/zh/latest/plugins/opa.md: ########## @@ -0,0 +1,315 @@ +--- +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` 配置。 | Review Comment: ```suggestion | policy | string | 是 | | | OPA 策略路径，是 `package` 和 `decision` 配置的组合。当使用高级功能（例如自定义响应）时，你可以省略 `decision` 配置。 | ``` ########## docs/zh/latest/plugins/opa.md: ########## @@ -0,0 +1,315 @@ +--- +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 密钥。确保只有在你确定安全的情况下才打开它。 | + +## 数据定义 + +### 场景一：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": { + "allow": true, + "reason": "test", + "headers": { + "an": "header" + }, + "status_code": 401 + } +} +``` + +上述代码响应中释义如下： + +- `allow` 配置是必不可少的，它表示请求是否允许通过 APISIX 进行转发； +- `reason`、`headers` 和 `status_code` 是可选的，只有当你配置一个自定义响应时才会返回这些选项信息，具体使用方法可查看后续测试用例。 + +## 测试插件 + +首先启动 OPA 环境： + +```shell +docker run -d --name opa -p 8181:8181 openpolicyagent/opa:0.35.0 run -s +``` + +### 基本用法 + +一旦你运行了 OPA 服务，就可以进行基本策略的创建： + +```shell +curl -X PUT '127.0.0.1:8181/v1/policies/example1' \ + -H 'Content-Type: text/plain' \ + -d 'package example1 + +import input.request + +default allow = false + +allow { + # HTTP method must GET + request.method == "GET" +}' +``` + +然后在一个特定的 Route 上配置 `opa` 插件： + +```shell +curl -X PUT 'http://127.0.0.1:9080/apisix/admin/routes/r1' \ + -H 'X-API-KEY: <api-key>' \ + -H 'Content-Type: application/json' \ + -d '{ + "uri": "/*", + "plugins": { + "opa": { + "host": "http://127.0.0.1:8181";, + "policy": "example1" + } + }, + "upstream": { + "nodes": { + "httpbin.org:80": 1 + }, + "type": "roundrobin" + } +}' +``` + +使用如下命令进行测试： + +```shell +curl -i -X GET 127.0.0.1:9080/get +``` + +```shell +HTTP/1.1 200 OK +``` + +如果尝试向不同的端点发出请求，会出现请求失败的状态： + +```shell +curl -i -X POST 127.0.0.1:9080/post +``` + +```shell +HTTP/1.1 403 FORBIDDEN +``` + +### 使用自定义响应 + +除了基础用法外，你还可以为更复杂的使用场景配置自定义响应，参考示例如下： + +```shell +curl -X PUT '127.0.0.1:8181/v1/policies/example2' \ + -H 'Content-Type: text/plain' \ + -d 'package example2 + +import input.request + +default allow = false + +allow { + request.method == "GET" +} + +# custom response body (Accepts a string or an object, the object will respond as JSON format) +reason = "test" { + not allow +} + +# custom response header (The data of the object can be written in this way) +headers = { + "Location": "http://example.com/auth"; +} { + not allow +} + +# custom response status code +status_code = 302 { + not allow +}' +``` + +同时，你可以将 `opa` 插件的策略参数调整为 `example2`，然后发出请求进行测试： + +```shell +curl -i -X GET 127.0.0.1:9080/get +``` + +```shell +HTTP/1.1 200 OK +``` + +这时如果你发出一个失败请求，将会收到来自 OPA 服务的自定义响应反馈，如下所示： + +```shell +curl -i -X POST 127.0.0.1:9080/post +``` + +```shell +HTTP/1.1 302 FOUND +Location: http://example.com/auth + +test +``` + +### 发送 APISIX 数据 + +如果你的 OPA 服务需要根据 APISIX 的某些数据（如 Route 和 Consumer 的详细信息）来进行后续操作时，则可以通过配置插件来实现。 + +下述示例展示了一个简单的 `echo` 策略，它将原样返回 APISIX 发送的数据： + +```shell +curl -X PUT '127.0.0.1:8181/v1/policies/echo' \ + -H 'Content-Type: text/plain' \ + -d 'package echo + +allow = false +reason = input' +``` + +现在就可以在 Route 上配置插件来发送 APISIX 数据： Review Comment: ```suggestion 现在就可以在路由上配置插件来发送 APISIX 数据： ``` ########## docs/zh/latest/plugins/opa.md: ########## @@ -0,0 +1,315 @@ +--- +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 密钥。确保只有在你确定安全的情况下才打开它。 | + +## 数据定义 + +### 场景一：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": { + "allow": true, + "reason": "test", + "headers": { + "an": "header" + }, + "status_code": 401 + } +} +``` + +上述代码响应中释义如下： + +- `allow` 配置是必不可少的，它表示请求是否允许通过 APISIX 进行转发； +- `reason`、`headers` 和 `status_code` 是可选的，只有当你配置一个自定义响应时才会返回这些选项信息，具体使用方法可查看后续测试用例。 + +## 测试插件 + +首先启动 OPA 环境： + +```shell +docker run -d --name opa -p 8181:8181 openpolicyagent/opa:0.35.0 run -s +``` + +### 基本用法 + +一旦你运行了 OPA 服务，就可以进行基本策略的创建： + +```shell +curl -X PUT '127.0.0.1:8181/v1/policies/example1' \ + -H 'Content-Type: text/plain' \ + -d 'package example1 + +import input.request + +default allow = false + +allow { + # HTTP method must GET + request.method == "GET" +}' +``` + +然后在一个特定的 Route 上配置 `opa` 插件： + +```shell +curl -X PUT 'http://127.0.0.1:9080/apisix/admin/routes/r1' \ + -H 'X-API-KEY: <api-key>' \ + -H 'Content-Type: application/json' \ + -d '{ + "uri": "/*", + "plugins": { + "opa": { + "host": "http://127.0.0.1:8181";, + "policy": "example1" + } + }, + "upstream": { + "nodes": { + "httpbin.org:80": 1 + }, + "type": "roundrobin" + } +}' +``` + +使用如下命令进行测试： + +```shell +curl -i -X GET 127.0.0.1:9080/get +``` + +```shell +HTTP/1.1 200 OK +``` + +如果尝试向不同的端点发出请求，会出现请求失败的状态： + +```shell +curl -i -X POST 127.0.0.1:9080/post +``` + +```shell +HTTP/1.1 403 FORBIDDEN +``` + +### 使用自定义响应 + +除了基础用法外，你还可以为更复杂的使用场景配置自定义响应，参考示例如下： + +```shell +curl -X PUT '127.0.0.1:8181/v1/policies/example2' \ + -H 'Content-Type: text/plain' \ + -d 'package example2 + +import input.request + +default allow = false + +allow { + request.method == "GET" +} + +# custom response body (Accepts a string or an object, the object will respond as JSON format) +reason = "test" { + not allow +} + +# custom response header (The data of the object can be written in this way) +headers = { + "Location": "http://example.com/auth"; +} { + not allow +} + +# custom response status code +status_code = 302 { + not allow +}' +``` + +同时，你可以将 `opa` 插件的策略参数调整为 `example2`，然后发出请求进行测试： + +```shell +curl -i -X GET 127.0.0.1:9080/get +``` + +```shell +HTTP/1.1 200 OK +``` + +这时如果你发出一个失败请求，将会收到来自 OPA 服务的自定义响应反馈，如下所示： + +```shell +curl -i -X POST 127.0.0.1:9080/post +``` + +```shell +HTTP/1.1 302 FOUND +Location: http://example.com/auth + +test +``` + +### 发送 APISIX 数据 + +如果你的 OPA 服务需要根据 APISIX 的某些数据（如 Route 和 Consumer 的详细信息）来进行后续操作时，则可以通过配置插件来实现。 + +下述示例展示了一个简单的 `echo` 策略，它将原样返回 APISIX 发送的数据： + +```shell +curl -X PUT '127.0.0.1:8181/v1/policies/echo' \ + -H 'Content-Type: text/plain' \ + -d 'package echo + +allow = false +reason = input' +``` + +现在就可以在 Route 上配置插件来发送 APISIX 数据： + +```shell +curl -X PUT 'http://127.0.0.1:9080/apisix/admin/routes/r1' \ + -H 'X-API-KEY: <api-key>' \ + -H 'Content-Type: application/json' \ + -d '{ + "uri": "/*", + "plugins": { + "opa": { + "host": "http://127.0.0.1:8181";, + "policy": "echo", + "with_route": true + } + }, + "upstream": { + "nodes": { + "httpbin.org:80": 1 + }, + "type": "roundrobin" + } +}' +``` + +此时如果你提出一个请求，则可以通过自定义响应看到来自 Route 的数据： + +```shell +curl -X GET 127.0.0.1:9080/get Review Comment: Please split into two code blocks ########## docs/zh/latest/plugins/authz-casdoor.md: ########## @@ -0,0 +1,107 @@ +--- +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 | endpoint_addr | string | 是 | Casdoor 的URL。 | | client_id | string | 是 | Casdoor 的客户端 id。 | | client_secret | string | 是 | Casdoor 的客户端密码。 | | callback_url | string | 是 | 用于接收状态和代码的回调 URL。 | ``` ########## docs/zh/latest/plugins/authz-casdoor.md: ########## @@ -0,0 +1,107 @@ +--- +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` 属性时不要以 “/” 来结尾。 + +::: + +:::info IMPORTANT + +`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`。该插件还将请求一个访问 Token，并确认用户是否真正登录了。该过程只运行一次，后续请求将不会被此打断。 Review Comment: ```suggestion 成功登录后，Casdoor 会将该用户重定向到 `callback_url`，并指定 GET 参数的 `code` 和 `state`。该插件还会向 Casdoor 请求一个访问 Token，并确认用户是否真正登录了。该过程只运行一次，后续请求将不会被此打断。 ``` ########## docs/zh/latest/plugins/authz-casdoor.md: ########## @@ -0,0 +1,107 @@ +--- +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` 属性时不要以 “/” 来结尾。 + +::: + +:::info IMPORTANT Review Comment: ```suggestion ``` ########## 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 客户端的用户可分辨名称，例如：`cn=user01,ou=users,dc=example,dc=org`。 | + +Route 端： + +| 名称 | 类型 | 必选项 | 默认值 | 描述 | +|----------|---------|----------|---------|------------------------------------------------------------------------| +| base_dn | string | 是 | | LDAP 服务器的基础可分辨名称，例如：`ou=users,dc=example,dc=org`。| Review Comment: ```suggestion | base_dn | string | 是 | | LDAP 服务器的 dn，例如：`ou=users,dc=example,dc=org`。| ``` ########## docs/zh/latest/plugins/opa.md: ########## @@ -0,0 +1,315 @@ +--- +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 密钥。确保只有在你确定安全的情况下才打开它。 | Review Comment: ```suggestion | with_consumer | boolean | 否 | false | | 当设置为 `true` 时，发送关于当前 Consumer 的信息。注意，这可能会发送敏感信息，如 API key。请确保在安全的情况下打开它。 | ``` ########## docs/zh/latest/plugins/opa.md: ########## @@ -0,0 +1,315 @@ +--- +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 密钥。确保只有在你确定安全的情况下才打开它。 | + +## 数据定义 + +### 场景一：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": { + "allow": true, + "reason": "test", + "headers": { + "an": "header" + }, + "status_code": 401 + } +} +``` + +上述代码响应中释义如下： + +- `allow` 配置是必不可少的，它表示请求是否允许通过 APISIX 进行转发； +- `reason`、`headers` 和 `status_code` 是可选的，只有当你配置一个自定义响应时才会返回这些选项信息，具体使用方法可查看后续测试用例。 + +## 测试插件 + +首先启动 OPA 环境： + +```shell +docker run -d --name opa -p 8181:8181 openpolicyagent/opa:0.35.0 run -s +``` + +### 基本用法 + +一旦你运行了 OPA 服务，就可以进行基本策略的创建： + +```shell +curl -X PUT '127.0.0.1:8181/v1/policies/example1' \ + -H 'Content-Type: text/plain' \ + -d 'package example1 + +import input.request + +default allow = false + +allow { + # HTTP method must GET + request.method == "GET" +}' +``` + +然后在一个特定的 Route 上配置 `opa` 插件： Review Comment: ```suggestion 然后在指定路由上配置 `opa` 插件： ``` ########## docs/zh/latest/plugins/opa.md: ########## @@ -0,0 +1,315 @@ +--- +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 密钥。确保只有在你确定安全的情况下才打开它。 | + +## 数据定义 + +### 场景一：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": { + "allow": true, + "reason": "test", + "headers": { + "an": "header" + }, + "status_code": 401 + } +} +``` + +上述代码响应中释义如下： Review Comment: ```suggestion 上述响应中的代码释义如下： ``` ########## docs/zh/latest/plugins/opa.md: ########## @@ -0,0 +1,315 @@ +--- +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 密钥。确保只有在你确定安全的情况下才打开它。 | + +## 数据定义 + +### 场景一：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": { + "allow": true, + "reason": "test", + "headers": { + "an": "header" + }, + "status_code": 401 + } +} +``` + +上述代码响应中释义如下： + +- `allow` 配置是必不可少的，它表示请求是否允许通过 APISIX 进行转发； +- `reason`、`headers` 和 `status_code` 是可选的，只有当你配置一个自定义响应时才会返回这些选项信息，具体使用方法可查看后续测试用例。 + +## 测试插件 + +首先启动 OPA 环境： + +```shell +docker run -d --name opa -p 8181:8181 openpolicyagent/opa:0.35.0 run -s +``` + +### 基本用法 + +一旦你运行了 OPA 服务，就可以进行基本策略的创建： + +```shell +curl -X PUT '127.0.0.1:8181/v1/policies/example1' \ + -H 'Content-Type: text/plain' \ + -d 'package example1 + +import input.request + +default allow = false + +allow { + # HTTP method must GET + request.method == "GET" +}' +``` + +然后在一个特定的 Route 上配置 `opa` 插件： + +```shell +curl -X PUT 'http://127.0.0.1:9080/apisix/admin/routes/r1' \ + -H 'X-API-KEY: <api-key>' \ + -H 'Content-Type: application/json' \ + -d '{ + "uri": "/*", + "plugins": { + "opa": { + "host": "http://127.0.0.1:8181";, + "policy": "example1" + } + }, + "upstream": { + "nodes": { + "httpbin.org:80": 1 + }, + "type": "roundrobin" + } +}' +``` + +使用如下命令进行测试： + +```shell +curl -i -X GET 127.0.0.1:9080/get +``` + +```shell +HTTP/1.1 200 OK +``` + +如果尝试向不同的端点发出请求，会出现请求失败的状态： + +```shell +curl -i -X POST 127.0.0.1:9080/post +``` + +```shell +HTTP/1.1 403 FORBIDDEN +``` + +### 使用自定义响应 + +除了基础用法外，你还可以为更复杂的使用场景配置自定义响应，参考示例如下： + +```shell +curl -X PUT '127.0.0.1:8181/v1/policies/example2' \ + -H 'Content-Type: text/plain' \ + -d 'package example2 + +import input.request + +default allow = false + +allow { + request.method == "GET" +} + +# custom response body (Accepts a string or an object, the object will respond as JSON format) +reason = "test" { + not allow +} + +# custom response header (The data of the object can be written in this way) +headers = { + "Location": "http://example.com/auth"; +} { + not allow +} + +# custom response status code +status_code = 302 { + not allow +}' +``` + +同时，你可以将 `opa` 插件的策略参数调整为 `example2`，然后发出请求进行测试： + +```shell +curl -i -X GET 127.0.0.1:9080/get +``` + +```shell +HTTP/1.1 200 OK +``` + +这时如果你发出一个失败请求，将会收到来自 OPA 服务的自定义响应反馈，如下所示： + +```shell +curl -i -X POST 127.0.0.1:9080/post +``` + +```shell +HTTP/1.1 302 FOUND +Location: http://example.com/auth + +test +``` + +### 发送 APISIX 数据 + +如果你的 OPA 服务需要根据 APISIX 的某些数据（如 Route 和 Consumer 的详细信息）来进行后续操作时，则可以通过配置插件来实现。 + +下述示例展示了一个简单的 `echo` 策略，它将原样返回 APISIX 发送的数据： + +```shell +curl -X PUT '127.0.0.1:8181/v1/policies/echo' \ + -H 'Content-Type: text/plain' \ + -d 'package echo + +allow = false +reason = input' +``` + +现在就可以在 Route 上配置插件来发送 APISIX 数据： + +```shell +curl -X PUT 'http://127.0.0.1:9080/apisix/admin/routes/r1' \ + -H 'X-API-KEY: <api-key>' \ + -H 'Content-Type: application/json' \ + -d '{ + "uri": "/*", + "plugins": { + "opa": { + "host": "http://127.0.0.1:8181";, + "policy": "echo", + "with_route": true + } + }, + "upstream": { + "nodes": { + "httpbin.org:80": 1 + }, + "type": "roundrobin" + } +}' +``` + +此时如果你提出一个请求，则可以通过自定义响应看到来自 Route 的数据： Review Comment: ```suggestion 此时如果你发起一个请求，则可以通过自定义响应看到来自路由的数据： ``` ########## docs/zh/latest/plugins/opa.md: ########## @@ -0,0 +1,315 @@ +--- +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 密钥。确保只有在你确定安全的情况下才打开它。 | + +## 数据定义 + +### 场景一：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": { + "allow": true, + "reason": "test", + "headers": { + "an": "header" + }, + "status_code": 401 + } +} +``` + +上述代码响应中释义如下： + +- `allow` 配置是必不可少的，它表示请求是否允许通过 APISIX 进行转发； +- `reason`、`headers` 和 `status_code` 是可选的，只有当你配置一个自定义响应时才会返回这些选项信息，具体使用方法可查看后续测试用例。 + +## 测试插件 + +首先启动 OPA 环境： + +```shell +docker run -d --name opa -p 8181:8181 openpolicyagent/opa:0.35.0 run -s +``` + +### 基本用法 + +一旦你运行了 OPA 服务，就可以进行基本策略的创建： + +```shell +curl -X PUT '127.0.0.1:8181/v1/policies/example1' \ + -H 'Content-Type: text/plain' \ + -d 'package example1 + +import input.request + +default allow = false + +allow { + # HTTP method must GET + request.method == "GET" +}' +``` + +然后在一个特定的 Route 上配置 `opa` 插件： + +```shell +curl -X PUT 'http://127.0.0.1:9080/apisix/admin/routes/r1' \ + -H 'X-API-KEY: <api-key>' \ + -H 'Content-Type: application/json' \ + -d '{ + "uri": "/*", + "plugins": { + "opa": { + "host": "http://127.0.0.1:8181";, + "policy": "example1" + } + }, + "upstream": { + "nodes": { + "httpbin.org:80": 1 + }, + "type": "roundrobin" + } +}' +``` + +使用如下命令进行测试： + +```shell +curl -i -X GET 127.0.0.1:9080/get +``` + +```shell +HTTP/1.1 200 OK +``` + +如果尝试向不同的端点发出请求，会出现请求失败的状态： + +```shell +curl -i -X POST 127.0.0.1:9080/post +``` + +```shell +HTTP/1.1 403 FORBIDDEN +``` + +### 使用自定义响应 + +除了基础用法外，你还可以为更复杂的使用场景配置自定义响应，参考示例如下： + +```shell +curl -X PUT '127.0.0.1:8181/v1/policies/example2' \ + -H 'Content-Type: text/plain' \ + -d 'package example2 + +import input.request + +default allow = false + +allow { + request.method == "GET" +} + +# custom response body (Accepts a string or an object, the object will respond as JSON format) +reason = "test" { + not allow +} + +# custom response header (The data of the object can be written in this way) +headers = { + "Location": "http://example.com/auth"; +} { + not allow +} + +# custom response status code +status_code = 302 { + not allow +}' +``` + +同时，你可以将 `opa` 插件的策略参数调整为 `example2`，然后发出请求进行测试： + +```shell +curl -i -X GET 127.0.0.1:9080/get +``` + +```shell +HTTP/1.1 200 OK +``` + +这时如果你发出一个失败请求，将会收到来自 OPA 服务的自定义响应反馈，如下所示： Review Comment: ```suggestion 此时如果你发出一个失败请求，将会收到来自 OPA 服务的自定义响应反馈，如下所示： ``` ########## docs/zh/latest/plugins/opa.md: ########## @@ -0,0 +1,315 @@ +--- +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 密钥。确保只有在你确定安全的情况下才打开它。 | + +## 数据定义 + +### 场景一：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` 插件配置在这些对象上时才会发送。 Review Comment: ```suggestion - `route`、`service` 和 `consumer` 包含的数据，与 APISIX 中存储的数据相同，只有当这些对象上配置了 `opa` 插件时才会发送。 ``` ########## docs/zh/latest/plugins/opa.md: ########## @@ -0,0 +1,315 @@ +--- +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 密钥。确保只有在你确定安全的情况下才打开它。 | + +## 数据定义 + +### 场景一：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 发送数据： Review Comment: ```suggestion 下述示例代码展示了 OPA 服务对 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: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
