You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by ju...@apache.org on 2020/11/02 06:06:07 UTC
[apisix] branch master updated: docs: add the
`consumer-restriction` plugin to support `consumer` to subscribe to the
documents of `service` (#2265)
This is an automated email from the ASF dual-hosted git repository.
juzhiyuan pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new 3356b51 docs: add the `consumer-restriction` plugin to support `consumer` to subscribe to the documents of `service` (#2265)
3356b51 is described below
commit 3356b5199220ef32e0294a12eafaf906843aea29
Author: Firstsawyou <52...@users.noreply.github.com>
AuthorDate: Mon Nov 2 14:06:00 2020 +0800
docs: add the `consumer-restriction` plugin to support `consumer` to subscribe to the documents of `service` (#2265)
* doc: Chinese document changes
* doc: zh-cn document changes.
* doc: zh-cn document changes.
* doc: document changes.
* doc: document changes.
* fix: CI scan detected error.
* change: change document styles.
* fix: document styles.
* fix: CI scan detected error.
* fix: document styles.
* fix: docs style.
* fix: docs style.
* fix: docs conflict.
* fix: docs content `Route Test`.
* add: a brief description of what is expected.
* fix: delete extra blank lines.
Co-authored-by: YuanSheng Wang <me...@gmail.com>
---
doc/plugins/consumer-restriction.md | 158 ++++++++++++++++++++++++++----
doc/zh-cn/plugins/consumer-restriction.md | 156 +++++++++++++++++++++++++----
2 files changed, 273 insertions(+), 41 deletions(-)
diff --git a/doc/plugins/consumer-restriction.md b/doc/plugins/consumer-restriction.md
index 8590801..590917d 100644
--- a/doc/plugins/consumer-restriction.md
+++ b/doc/plugins/consumer-restriction.md
@@ -20,31 +20,36 @@
- [中文](../zh-cn/plugins/consumer-restriction.md)
# Summary
-- [**Name**](#name)
-- [**Attributes**](#attributes)
-- [**How To Enable**](#how-to-enable)
-- [**Test Plugin**](#test-plugin)
-- [**Disable Plugin**](#disable-plugin)
+ - [Introduction](#introduction)
+ - [Attributes](#attributes)
+ - [Example](#example)
+ - [How to restrict consumer_name](#how-to-restrict-consumer_name)
+ - [How to restrict service_id](#how-to-restrict-service_id)
+ - [Disable Plugin](#disable-plugin)
-## Name
+## Introduction
-The `consumer-restriction` can restrict access to a Service or a Route by either
-whitelisting or blacklisting consumers. Support single or multiple consumers.
+The `consumer-restriction` makes corresponding access restrictions based on different objects selected.
## Attributes
-| Name | Type | Requirement | Default | Valid | Description |
-| --------- | ------------- | ----------- | ------- | ----- | ------------------------------- |
-| whitelist | array[string] | optional | | | List of consumers to whitelist. |
-| blacklist | array[string] | optional | | | List of consumers to blacklist. |
+|Name | Type | Requirement | Default | Valid | Description |
+|-----------|-------------|--------------|---------------|---------------------------------|-------------------------------------------------------------------------------------------------------------------- |
+| type | string | optional | consumer_name | ["consumer_name", "service_id"] | According to different objects, corresponding restrictions, support `consumer_name`, `service_id`. |
+| whitelist | array[string] | required | | | Choose one of the two with `blacklist`, only whitelist or blacklist can be enabled separately, and the two cannot be used together. |
+| blacklist | array[string] | required | | | Choose one of the two with `whitelist`, only whitelist or blacklist can be enabled separately, and the two cannot be used together. |
+| rejected_code | integer | optional | 403 | [200,...] | The HTTP status code returned when the request is rejected. |
-One of `whitelist` or `blacklist` must be specified, and they can not work
-together.
+For the `type` field is an enumerated type, it can be `consumer_name` or `service_id`. They stand for the following meanings:
+* **consumer_name**: Add the `username` of `consumer` to a whitelist or blacklist (supporting single or multiple consumers) to restrict access to services or routes.
+* **service_id**: Add the `id` of the `service` to a whitelist or blacklist (supporting one or more services) to restrict access to the service. It needs to be used in conjunction with authorized plugins.
-## How To Enable
+## Example
-Creates a route or service object, and enable plugin `consumer-restriction`.
+### How to restrict `consumer_name`
+
+The following is an example. The `consumer-restriction` plugin is enabled on the specified route to restrict consumer access.
```shell
curl http://127.0.0.1:9080/apisix/admin/consumers/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
@@ -89,12 +94,12 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-## Test Plugin
+**Test Plugin**
Requests from jack1:
```shell
-$ curl -u jack2019:123456 http://127.0.0.1:9080/index.html
+curl -u jack2019:123456 http://127.0.0.1:9080/index.html
HTTP/1.1 200 OK
...
```
@@ -102,12 +107,123 @@ HTTP/1.1 200 OK
Requests from jack2:
```shell
-$ curl -u jack2020:123456 http://127.0.0.1:9080/index.html -i
+curl -u jack2020:123456 http://127.0.0.1:9080/index.html -i
HTTP/1.1 403 Forbidden
...
-{"message":"You are not allowed"}
+{"message":"The consumer_name is forbidden."}
+```
+
+## How to restrict `service_id`
+
+The `service_id` method needs to be used together with the authorization plug-in. Here, the key-auth authorization plug-in is taken as an example.
+
+1. Create two services.
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/services/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "upstream": {
+ "nodes": {
+ "127.0.0.1:1980": 1
+ },
+ "type": "roundrobin"
+ },
+ "desc": "new service 001"
+}'
+
+curl http://127.0.0.1:9080/apisix/admin/services/2 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "upstream": {
+ "nodes": {
+ "127.0.0.1:1980": 1
+ },
+ "type": "roundrobin"
+ },
+ "desc": "new service 002"
+}'
```
+2. Bind the `consumer-restriction` plugin on the `consumer` (need to cooperate with an authorized plugin to bind), and add the `service_id` whitelist list.
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "username": "new_consumer",
+ "plugins": {
+ "key-auth": {
+ "key": "auth-jack"
+ },
+ "consumer-restriction": {
+ "type": "service_id",
+ "whitelist": [
+ "1"
+ ],
+ "rejected_code": 403
+ }
+ }
+}'
+```
+
+3. Open the `key-auth` plugin on the route and bind the `service_id` to `1`.
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "uri": "/index.html",
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:1980": 1
+ }
+ },
+ "service_id": 1,
+ "plugins": {
+ "key-auth": {
+ }
+ }
+}'
+```
+
+**Test Plugin**
+
+```shell
+curl http://127.0.0.1:9080/index.html -H 'apikey: auth-jack' -i
+HTTP/1.1 200 OK
+...
+```
+
+The `service_id` in the whitelist column allows access, and the plug-in configuration takes effect.
+
+4. Open the `key-auth` plugin on the route and bind the `service_id` to `2`.
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "uri": "/index.html",
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:1980": 1
+ }
+ },
+ "service_id": 2,
+ "plugins": {
+ "key-auth": {
+ }
+ }
+}'
+```
+
+**Test Plugin**
+
+```shell
+curl http://127.0.0.1:9080/index.html -H 'apikey: auth-jack' -i
+HTTP/1.1 403 Forbidden
+...
+{"message":"The service_id is forbidden."}
+```
+
+It means that the `service_id` that is not in the whitelist is denied access, and the plug-in configuration takes effect.
## Disable Plugin
@@ -116,7 +232,7 @@ you can delete the corresponding json configuration in the plugin configuration,
no need to restart the service, it will take effect immediately:
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/index.html",
"upstream": {
diff --git a/doc/zh-cn/plugins/consumer-restriction.md b/doc/zh-cn/plugins/consumer-restriction.md
index b2b1d77..5283de1 100644
--- a/doc/zh-cn/plugins/consumer-restriction.md
+++ b/doc/zh-cn/plugins/consumer-restriction.md
@@ -20,29 +20,35 @@
- [English](../../plugins/consumer-restriction.md)
# 目录
-- [**名字**](#名字)
-- [**属性**](#属性)
-- [**如何启用**](#如何启用)
-- [**测试插件**](#测试插件)
-- [**禁用插件**](#禁用插件)
+ - [简介](#简介)
+ - [属性](#属性)
+ - [示例](#示例)
+ - [如何限制 consumer_name](#如何限制-consumer_name)
+ - [如何限制 service_id](#如何限制-service_id)
+ - [禁用插件](#禁用插件)
-## 名字
+## 简介
-`consumer-restriction` 可以通过以下方式限制对服务或路线的访问，将 consumer 列入白名单或黑名单。 支持单个或多个 consumer。
+`consumer-restriction` 根据选择的不同对象做相应的访问限制。
## 属性
-| 参数名 | 类型 | 可选项 | 默认值 | 有效值 | 描述 |
-| --------- | ------------- | ------ | ------ | ------ | -------------------- |
-| whitelist | array[string] | 可选 | | | 加入白名单的consumer |
-| blacklist | array[string] | 可选 | | | 加入黑名单的consumer |
+| 参数名 | 类型 | 可选项 | 默认值 | 有效值 | 描述 |
+| --------- | ------------- | ------ | -----------------| --------------------------------| ----------------------------------------------------------|
+| type | string | 可选 | consumer_name | ["consumer_name", "service_id"] | 根据不同的对象做相应的限制,支持 `consumer_name`、`service_id`。 |
+| whitelist | array[string] | 必选 | | | 与`blacklist`二选一，只能单独启用白名单或黑名单，两个不能一起使用。 |
+| blacklist | array[string] | 必选 | | | 与`whitelist`二选一，只能单独启用白名单或黑名单，两个不能一起使用。 |
+| rejected_code | integer | 可选 | 403 | [200,...] | 当请求被拒绝时，返回的 HTTP 状态码。|
-只能单独启用白名单或黑名单，两个不能一起使用。
+对于 `type` 字段是个枚举类型，它可以是 `consumer_name` 或 `service_id` 。分别代表以下含义：
+* **consumer_name**：把 `consumer` 的 `username` 列入白名单或黑名单（支持单个或多个 consumer）来限制对服务或路线的访问。
+* **service_id**：把 `service` 的 `id` 列入白名单或黑名单（支持一个或多个 service）来限制service的访问，需要结合授权插件一起使用。
-## 如何启用
+## 示例
-下面是一个示例，在指定的 route 上开启了 `consumer-restriction` 插件，限制consumer访问:
+### 如何限制 `consumer_name`
+下面是一个示例，在指定的 route 上开启了 `consumer-restriction` 插件，限制 consumer 访问:
```shell
curl http://127.0.0.1:9080/apisix/admin/consumers/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
@@ -87,12 +93,12 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-## 测试插件
+**测试插件**
jack1 访问:
```shell
-$ curl -u jack2019:123456 http://127.0.0.1:9080/index.html
+curl -u jack2019:123456 http://127.0.0.1:9080/index.html -i
HTTP/1.1 200 OK
...
```
@@ -100,18 +106,129 @@ HTTP/1.1 200 OK
jack2 访问:
```shell
-$ curl -u jack2020:123456 http://127.0.0.1:9080/index.html -i
+curl -u jack2020:123456 http://127.0.0.1:9080/index.html -i
HTTP/1.1 403 Forbidden
...
-{"message":"You are not allowed"}
+{"message":"The consumer_name is forbidden."}
```
+### 如何限制 `service_id`
+`service_id`方式需要与授权插件一起配合使用，这里以key-auth授权插件为例。
+
+1、创建两个 service
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/services/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "upstream": {
+ "nodes": {
+ "127.0.0.1:1980": 1
+ },
+ "type": "roundrobin"
+ },
+ "desc": "new service 001"
+}'
+
+curl http://127.0.0.1:9080/apisix/admin/services/2 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "upstream": {
+ "nodes": {
+ "127.0.0.1:1980": 1
+ },
+ "type": "roundrobin"
+ },
+ "desc": "new service 002"
+}'
+```
+
+2、在 `consumer` 上绑定 `consumer-restriction` 插件(需要与一个授权插件配合才能绑定),并添加 `service_id` 白名单列表
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "username": "new_consumer",
+ "plugins": {
+ "key-auth": {
+ "key": "auth-jack"
+ },
+ "consumer-restriction": {
+ "type": "service_id",
+ "whitelist": [
+ "1"
+ ],
+ "rejected_code": 403
+ }
+ }
+}'
+```
+
+3、在 route 上开启 `key-auth` 插件并绑定 `service_id` 为`1`
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "uri": "/index.html",
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:1980": 1
+ }
+ },
+ "service_id": 1,
+ "plugins": {
+ "key-auth": {
+ }
+ }
+}'
+```
+
+**测试插件**
+
+```shell
+curl http://127.0.0.1:9080/index.html -H 'apikey: auth-jack' -i
+HTTP/1.1 200 OK
+...
+```
+
+说明在白名单列中的 `service_id` 允许访问，插件配置生效。
+
+4、在 route 上开启 `key-auth` 插件并绑定 `service_id` 为`2`
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "uri": "/index.html",
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:1980": 1
+ }
+ },
+ "service_id": 2,
+ "plugins": {
+ "key-auth": {
+ }
+ }
+}'
+```
+
+**测试插件**
+
+```shell
+curl http://127.0.0.1:9080/index.html -H 'apikey: auth-jack' -i
+HTTP/1.1 403 Forbidden
+...
+{"message":"The service_id is forbidden."}
+```
+
+说明不在白名单列表的 `service_id` 被拒绝访问，插件配置生效。
+
## 禁用插件
当你想去掉 `consumer-restriction` 插件的时候，很简单，在插件的配置中把对应的 json 配置删除即可，无须重启服务，即刻生效：
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/index.html",
"upstream": {
@@ -127,4 +244,3 @@ $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f
```
现在就已移除 `consumer-restriction` 插件，其它插件的开启和移除也类似。
-