Apply List-Based Access Control

Sometimes, you will require more precise access control than what authentication plugins offer. For example, you might want to keep a whitelist of consumers who can access your API. Now, a consumer must send an authenticated request and be on the whitelist (and not on the blacklist) to access the API.

note

Consider if the API Portal is a better solution before implementing consumer-based access control.

This tutorial guides you in configuring precise access control by creating a consumer whitelist through the consumer-restriction plugin.

Prerequisites

1. Install API7 Enterprise.
2. Have a route with key-auth enabled.
3. Have a consumer alice with credentials.

Apply Consumer Whitelist

When a consumer makes an authenticated request, API7 Gateway passes on the consumer's name to the routes. So, the routes do not need to access the consumer's credentials directly, which is more user-friendly.

Dashboard

1. Select Published Services of your gateway group from the side navigation bar, then select the service you want to configure, for example, httpbin with version 1.0.0.
2. Select Plugins from the side navigation bar, then click Add Plugin.
3. Search for the Consumer Restriction Plugin, then click Add.
4. In the dialog box, do the following:

• Add the following configuration to the JSON Editor:

  {
    "whitelist": [
      "Alice"
    ]
  }

  If you had followed the prerequisite tutorial, you would already have a consumer Alice with key authentication credentials.

• Click Add.

5. Create a new consumer Lisa with key authentication credentials where Key is lisa-key.

ADC

Update your ADC configuration as such:

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

Synchronize the configuration to API7 Enterprise:

adc sync -f adc.yaml

Ingress Controller

Gateway API

Create a Kubernetes manifest file for a route (that also creates a service) and enable consumer-restriction and key-auth plugins on the service:

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

❶ The actual consumer name created by the Ingress Controller is prefixed with your namespace. Make sure to update the whitelist consumer name accordingly.

Create another Kubernetes manifest file to configure a consumer 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

Apply the configuration to your cluster:

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

APISIX CRD

Create a Kubernetes manifest file for a route (that also creates a service) and enable consumer-restriction and key-auth plugins on the route:

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

❶ The actual consumer name created by the Ingress Controller is prefixed with your namespace. Make sure to update the whitelist consumer name accordingly.

Create another Kubernetes manifest file to configure a consumer 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

Apply the configuration to your cluster:

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

Validate

Make a request to the service as the consumer Alice:

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

You will see that the request is successful with a 200 OK response because the consumer Alice is in the whitelist.

Now, make a request to the service as the newly created consumer Lisa:

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

You will receive a 403 Forbidden response with the following response body as the consumer Lisa was not added to the whitelist:

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

Apply Consumer Blacklist

The consumer-restriction plugin prioritizes the blacklist over the whitelist when determining access.

Dashboard

1. Select Published Services of your gateway group from the side navigation bar, then select the service you want to configure, for example, httpbin with version 1.0.0.
2. Select Plugins from the side navigation bar, then click Add Plugin.
3. Search for the consumer-restriction plugin, then click Add.
4. In the dialog box, do the following:

• Add the following configuration to the JSON Editor:

  {
    "blacklist": [
      "Lisa"
    ]
  }

  If you had followed the prerequisite tutorial, you would already have a consumer Alice with key authentication credentials.

• Click Add.

5. Create a new consumer Lisa with key authentication credentials where Key is lisa-key.

ADC

Update your ADC configuration as such:

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

Synchronize the configuration to API7 Enterprise:

adc sync -f adc.yaml

Ingress Controller

Create a Kubernetes manifest file for a route (that also creates a service) and enable consumer-restriction and key-auth plugins:

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

❶ The actual consumer name created by the Ingress Controller is prefixed with your namespace. Make sure to update the blacklist consumer name accordingly.

Create another Kubernetes manifest file for a consumer lisa:

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

Apply the configuration to your cluster:

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

APISIX CRD

Create a Kubernetes manifest file for a route (that also creates a service) and enable consumer-restriction and key-auth plugins on the route:

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

❶ The actual consumer name created by the Ingress Controller is prefixed with your namespace. Make sure to update the blacklist consumer name accordingly.

Create another Kubernetes manifest file to configure a consumer 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

Apply the configuration to your cluster:

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

Validate

Make a request to the service as the consumer Alice:

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

You will see that the request is successful with a 200 OK response because the consumer Alice is not in the blacklist.

Now, make a request to the service as the newly created consumer Lisa:

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

You will receive a 403 Forbidden response with the following response body as the consumer Lisa was added to the blacklist:

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

Additional Resources

• Key Concepts
  • Services
  • Routes
  • Plugins
  • Consumers
• API Security
  • Set up API authentication
• API Consumption
  • Manage consumer credentials
• Plugin Hub
  • Consumer Restriction