# 访问控制列表

访问控制列表使用 `consumer-restriction` 插件限制 API 访问。该插件可以匹配消费者名称、服务 ID 或路由 ID，并同时支持允许列表和拒绝列表。以下示例使用默认且最常见的消费者名称匹配方式。

继承的网关 schema 接受 `consumer_group_id`，但 API7 网关未提供客户可管理的消费者组资源，也不会为消费者分配组 ID。请勿使用此标识符类型：该值不存在，插件会以 `HTTP 401` 拒绝请求。

## 功能[​](#功能 "功能的直接链接")

* **多种标识符类型**：通过插件的 `type` 字段匹配消费者名称（默认）、服务 ID 或路由 ID。
* **允许列表和拒绝列表**：明确允许或拒绝来自所配置标识符的流量。
* **插件集成**：与身份认证插件（如 `key-auth`、`jwt-auth`）结合，使网关能够识别请求所属的消费者。
* **细粒度控制**：将 ACL 挂载到路由、服务或消费者。

## 前置条件[​](#前置条件 "前置条件的直接链接")

1. 创建消费者（参阅[教程：通过插件代理和管理 API 请求](https://docs.apiseven.com/api7-gateway/getting-started/tutorial-proxying-api-requests.md#step-4-create-a-consumer)）。
2. 通过凭证为消费者添加身份认证方式（如 `key-auth`）。
3. 准备用于挂载路由的服务。以下示例假设已有名为 `acl-service` 的服务，请将其替换为你自己的服务。
4. 按照[从控制台获取 Token](https://docs.apiseven.com/api7-gateway/reference/obtain-dashboard-token.md)中的步骤获取 Token。

## 配置 ACL[​](#配置-acl "配置 ACL的直接链接")

要限制对路由的访问，请在路由上同时配置 `consumer-restriction` 插件和身份认证插件。

* Admin API
* ADC

```
curl -k "https://localhost:7443/apisix/admin/routes/acl-restricted-route?gateway_group_id={gateway_group_id}" -X PUT \

  -H "X-API-KEY: ${API_KEY}" \

  -H "Content-Type: application/json" \

  -d '{

    "name": "acl-restricted-route",

    "service_id": "acl-service",

    "paths": ["/restricted-api/*"],

    "plugins": {

      "key-auth": {},

      "consumer-restriction": {

        "whitelist": [

          "authorized-consumer"

        ]

      }

    }

  }'
```

将 `{gateway_group_id}` 替换为控制台的 **网关组** 页面中显示的网关组 ID（快速入门创建的网关组使用 `default`）。将 `acl-service` 替换为你的服务名称，并将 `authorized-consumer` 替换为要允许的消费者用户名。

adc.yaml

```
services:

  - name: acl-service

    upstream:

      scheme: http

      nodes:

        - host: your-upstream.example.com

          port: 80

          weight: 100

    routes:

      - name: acl-restricted-route

        uris:

          - /restricted-api/*

        plugins:

          key-auth: {}

          consumer-restriction:

            whitelist:

              - authorized-consumer

    labels:

      docs-example: acl-service
```

预览本示例管理的资源变更，确认没有非预期的更新或删除：

```
adc diff -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=acl-service
```

审查变更后同步配置：

```
adc sync -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=acl-service
```

## 关键配置参数[​](#关键配置参数 "关键配置参数的直接链接")

| 字段            | 类型            | 说明                                                                                                                                                                                              |
| --------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`          | `string`        | `whitelist`/`blacklist` 条目所表示的对象。使用 `consumer_name`（默认）、`service_id` 或 `route_id`。不要使用继承的 `consumer_group_id` 选项；API7 网关不会分配组 ID，并会以 `HTTP 401` 拒绝请求。 |
| `whitelist`     | `array[string]` | 允许访问的标识符。接受的标识符类型由 `type` 决定。                                                                                                                                                |
| `blacklist`     | `array[string]` | 拒绝访问的标识符。接受的标识符类型由 `type` 决定。                                                                                                                                                |
| `rejected_code` | `integer`       | 请求被拒绝时返回的 HTTP 状态码（默认为 `403`）。                                                                                                                                                  |
| `rejected_msg`  | `string`        | 请求被拒绝时返回的错误消息。                                                                                                                                                                      |

有关消费者名称匹配以外的配置模式，例如限制哪些消费者可以访问指定服务或路由，或限制每个消费者允许使用的 HTTP 方法，请参阅[`consumer-restriction` 插件参考](https://docs.apiseven.com/hub/consumer-restriction.md)。

## 实施模式[​](#实施模式 "实施模式的直接链接")

### 模式 1：为私有服务配置允许列表[​](#模式-1为私有服务配置允许列表 "模式 1：为私有服务配置允许列表的直接链接")

使用 `whitelist` 只允许特定内部消费者或合作伙伴访问私有 API。其他所有已认证消费者都将被拒绝。

### 模式 2：将恶意消费者加入拒绝列表[​](#模式-2将恶意消费者加入拒绝列表 "模式 2：将恶意消费者加入拒绝列表的直接链接")

使用 `blacklist` 阻止已被识别为可能恶意或违反使用条款的特定消费者，同时允许其他所有已认证消费者。

## 后续步骤[​](#后续步骤 "后续步骤的直接链接")

* [基于角色的访问控制（RBAC）](https://docs.apiseven.com/api7-gateway/security-and-compliance/role-based-access-control.md)，以使用更复杂的权限模型。
* [控制面 IP 限制](https://docs.apiseven.com/api7-gateway/security-and-compliance/ip-restrictions-control-plane.md)，在网络层增加另一层安全保护。
