应用基于列表的访问控制

有时，相比认证插件提供的功能，你可能需要更精确的访问控制。例如，你可能希望维护一个可以访问你的 API 的消费者（Consumers）白名单。这样，消费者必须发送经过身份验证的请求，并且在白名单中（且不在黑名单中）才能访问该 API。

备注

在实施基于消费者的访问控制之前，请考虑 API 开发者门户（API Portal） 是否是更好的解决方案。

本教程将指导你如何通过 consumer-restriction 插件创建消费者白名单，从而配置精确的访问控制。

前置条件

1. 安装 API7 企业版。
2. 拥有一个已启用 key-auth 的路由。
3. 拥有一个带有凭证的消费者 alice。

应用消费者白名单

当消费者发起认证请求时，API7 网关会将消费者名称传递给路由。因此，路由不需要直接访问消费者的凭据，这更加用户友好。

Dashboard

1. 从侧边导航栏选择你的网关组的 已发布服务（Published Services），然后选择你想要配置的服务，例如，版本为 1.0.0 的 httpbin。
2. 从侧边导航栏选择 插件（Plugins），然后点击 添加插件（Add Plugin）。
3. 搜索 Consumer Restriction 插件，然后点击 添加（Add）。
4. 在对话框中，执行以下操作：

• 将以下配置添加到 JSON 编辑器（JSON Editor）：

  {
    "whitelist": [
      "Alice"
    ]
  }

  如果你遵循了前置条件的教程，你应该已经有了一个拥有密钥认证凭证的消费者 Alice。

• 点击 添加（Add）。

5. 创建一个拥有密钥认证凭证的新消费者 Lisa，其 Key 为 lisa-key。

ADC

按如下方式更新你的 ADC 配置：

adc.yaml

services:
  - name: httpbin
    upstream:
      name: default
      scheme: http
      nodes:
        - host: httpbin.org
          port: 80
          weight: 100
    plugins:
      key-auth:
        _meta:
          disable: false
      consumer-restriction:
        whitelist:
          - Alice
consumers:
  - username: Alice
    credentials:
      - name: primary-key
        type: key-auth
        config:
          key: alice-primary-key
  - username: Lisa
    credentials:
      - name: lisa-key
        type: key-auth
        config:
          key: lisa-key

同步配置到 API7 企业版：

adc sync -f adc.yaml

Ingress Controller

Gateway API

为路由创建一个 Kubernetes 清单文件（这也将创建一个服务），并在服务上启用 consumer-restriction 和 key-auth 插件：

consumer-restriction-route.yaml

apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
  namespace: api7
  name: consumer-restriction-key-auth-plugin-config
spec:
  plugins:
    - name: key-auth
    - name: consumer-restriction
      config:
        whitelist:
        - api7_alice
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  namespace: api7
  name: httpbin
spec:
  parentRefs:
  - name: apisix
  rules:
  - matches: 
    - path:
        type: Exact
        value: /ip
    filters:
    - type: ExtensionRef
      extensionRef:
        group: apisix.apache.org
        kind: PluginConfig
        name: consumer-restriction-key-auth-plugin-config
    backendRefs:
    - name: httpbin
      port: 80

❶ 由 Ingress Controller 创建的实际消费者名称会以你的命名空间作为前缀。请确保相应地更新白名单中的消费者名称。

创建另一个 Kubernetes 清单文件以配置消费者 lisa：

consumer-lisa-key-auth.yaml

apiVersion: apisix.apache.org/v1alpha1
kind: Consumer
metadata:
  namespace: api7
  name: lisa
spec:
  gatewayRef:
  name: apisix
  credentials:
    - type: key-auth
      name: lisa-key
      config:
        key: lisa-key

将配置应用到你的集群：

kubectl apply -f consumer-restriction-route.yaml -f consumer-lisa-key-auth.yaml

APISIX CRD

为路由创建一个 Kubernetes 清单文件（这也将创建一个服务），并在路由上启用 consumer-restriction 和 key-auth 插件：

consumer-restriction-route.yaml

apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
  namespace: api7
  name: httpbin
spec:
  ingressClassName: apisix
  http:
    - name: get-ip
      match:
        paths:
          - /ip
      backends:
        - serviceName: httpbin
          servicePort: 80
      plugins:
        - name: key-auth
          enable: true
        - name: consumer-restriction
          enable: true
          config:
            whitelist:
              - api7_alice

❶ 由 Ingress Controller 创建的实际消费者名称会以你的命名空间作为前缀。请确保相应地更新白名单中的消费者名称。

创建另一个 Kubernetes 清单文件以配置消费者 lisa：

consumer-lisa-key-auth.yaml

apiVersion: apisix.apache.org/v2
kind: ApisixConsumer
metadata:
  namespace: api7
  name: lisa
spec:
  ingressClassName: apisix
  authParameter:
    keyAuth:
      value:
        key: lisa-key

将配置应用到你的集群：

kubectl apply -f consumer-restriction-route.yaml -f consumer-lisa-key-auth.yaml

验证

作为消费者 Alice 向服务发起请求：

curl -i "http://127.0.0.1:9080/ip" -H "apikey: alice-primary-key" 

你会看到请求成功并返回 200 OK 响应，因为消费者 Alice 在白名单中。

现在，作为新创建的消费者 Lisa 向服务发起请求：

curl -i "http://127.0.0.1:9080/ip" -H "apikey: lisa-key" 

因为消费者 Lisa 没有被添加到白名单中，你将收到一个 403 Forbidden 响应以及以下响应体：

{"message":"The consumer_name is forbidden."}

应用消费者黑名单

consumer-restriction 插件在决定访问权限时，黑名单的优先级高于白名单。

Dashboard

1. 从侧边导航栏选择你的网关组的 已发布服务（Published Services），然后选择你想要配置的服务，例如，版本为 1.0.0 的 httpbin。
2. 从侧边导航栏选择 插件（Plugins），然后点击 添加插件（Add Plugin）。
3. 搜索 consumer-restriction 插件，然后点击 添加（Add）。
4. 在对话框中，执行以下操作：

• 将以下配置添加到 JSON 编辑器（JSON Editor）：

  {
    "blacklist": [
      "Lisa"
    ]
  }

  如果你遵循了前置条件的教程，你应该已经有了一个拥有密钥认证凭证的消费者 Alice。

• 点击 添加（Add）。

5. 创建一个拥有密钥认证凭证的新消费者 Lisa，其 Key 为 lisa-key。

ADC

按如下方式更新你的 ADC 配置：

adc.yaml

services:
  - name: httpbin
    upstream:
      name: default
      scheme: http
      nodes:
        - host: httpbin.org
          port: 80
          weight: 100
    plugins:
      key-auth:
        _meta:
          disable: false
      consumer-restriction:
        blacklist:
          - Lisa
consumers:
  - username: Alice
    credentials:
      - name: alice-primary-key
        type: key-auth
        config:
          key: alice-primary-key
  - username: Lisa
    credentials:
      - name: lisa-key
        type: key-auth
        config:
          key: lisa-key

同步配置到 API7 企业版：

adc sync -f adc.yaml

Ingress Controller

为路由创建一个 Kubernetes 清单文件（这也将创建一个服务），并启用 consumer-restriction 和 key-auth 插件：

Gateway API

consumer-restriction-route.yaml

apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
  namespace: api7
  name: consumer-restriction-key-auth-plugin-config
spec:
  plugins:
    - name: key-auth
    - name: consumer-restriction
      config:
        blacklist:
        - api7_lisa
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  namespace: api7
  name: httpbin
spec:
  parentRefs:
  - name: apisix
  rules:
  - matches: 
    - path:
        type: Exact
        value: /ip
    filters:
    - type: ExtensionRef
      extensionRef:
        group: apisix.apache.org
        kind: PluginConfig
        name: consumer-restriction-key-auth-plugin-config
    backendRefs:
    - name: httpbin
      port: 80

❶ 由 Ingress Controller 创建的实际消费者名称会以你的命名空间作为前缀。请确保相应地更新黑名单中的消费者名称。

为消费者 lisa 创建另一个 Kubernetes 清单文件：

consumer.yaml

apiVersion: apisix.apache.org/v1alpha1
kind: Consumer
metadata:
  namespace: api7
  name: lisa
spec:
  gatewayRef:
    name: apisix
  credentials:
    - type: key-auth
      name: lisa-key
      config:
        key: lisa-key

将配置应用到你的集群：

kubectl apply -f consumer-restriction-route.yaml -f consumer.yaml

APISIX CRD

为路由创建一个 Kubernetes 清单文件（这也将创建一个服务），并在路由上启用 consumer-restriction 和 key-auth 插件：

consumer-restriction-route.yaml

apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
  namespace: api7
  name: httpbin
spec:
  ingressClassName: apisix
  http:
    - name: get-ip
      match:
        paths:
          - /ip
      backends:
        - serviceName: httpbin
          servicePort: 80
      plugins:
        - name: key-auth
          enable: true
        - name: consumer-restriction
          enable: true
          config:
            blacklist:
              - api7_lisa

❶ 由 Ingress Controller 创建的实际消费者名称会以你的命名空间作为前缀。请确保相应地更新黑名单中的消费者名称。

创建另一个 Kubernetes 清单文件以配置消费者 lisa：

consumer-lisa-key-auth.yaml

apiVersion: apisix.apache.org/v2
kind: ApisixConsumer
metadata:
  namespace: api7
  name: lisa
spec:
  ingressClassName: apisix
  authParameter:
    keyAuth:
      value:
        key: lisa-key

将配置应用到你的集群：

kubectl apply -f consumer-restriction-route.yaml -f consumer-lisa-key-auth.yaml

验证

作为消费者 Alice 向服务发起请求：

curl -i "http://127.0.0.1:9080/ip" -H "apikey: alice-primary-key" 

你会看到请求成功并返回 200 OK 响应，因为消费者 Alice 不在黑名单中。

现在，作为新创建的消费者 Lisa 向服务发起请求：

curl -i "http://127.0.0.1:9080/ip" -H "apikey: lisa-key" 

因为消费者 Lisa 被添加到了黑名单中，你将收到一个 403 Forbidden 响应以及以下响应体：

{"message":"The consumer_name is forbidden."}

更多资源

• 核心概念
  • 服务（Services）
  • 路由（Routes）
  • 插件（Plugins）
  • 消费者（Consumers）
• API 安全
  • 设置 API 认证
• API 消费
  • 管理消费者凭证
• 插件中心
  • Consumer Restriction