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.
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
- Install API7 Enterprise.
- Have a route with
key-auth
enabled. - 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
- ADC
- Ingress Controller
- Select Published Services of your gateway group from the side navigation bar, then select the service you want to configure, for example,
httpbin
with version1.0.0
. - Select Plugins from the side navigation bar, then click Add Plugin.
- Search for the Consumer Restriction Plugin, then click Add.
- 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.
- Create a new consumer
Lisa
with key authentication credentials where Key islisa-key
.
Update your ADC configuration as such:
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
- Gateway API
- 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 service:
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
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:
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
:
apiVersion: apisix.apache.org/v1alpha1
kind: Consumer
metadata:
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
Create a Kubernetes manifest file for a route (that also creates a service) and enable consumer-restriction
and key-auth
plugins on the route:
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
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
:
apiVersion: apisix.apache.org/v2
kind: ApisixConsumer
metadata:
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
- ADC
- Ingress Controller
- Select Published Services of your gateway group from the side navigation bar, then select the service you want to configure, for example,
httpbin
with version1.0.0
. - Select Plugins from the side navigation bar, then click Add Plugin.
- Search for the
consumer-restriction
plugin, then click Add. - 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.
- Create a new consumer
Lisa
with key authentication credentials where Key islisa-key
.
Update your ADC configuration as such:
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
Create a Kubernetes manifest file for a route (that also creates a service) and enable consumer-restriction
and key-auth
plugins:
- Gateway API
- APISIX CRD
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
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:
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
:
apiVersion: apisix.apache.org/v1alpha1
kind: Consumer
metadata:
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
Create a Kubernetes manifest file for a route (that also creates a service) and enable consumer-restriction
and key-auth
plugins on the route:
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
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
:
apiVersion: apisix.apache.org/v2
kind: ApisixConsumer
metadata:
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
- API Security
- API Consumption
- Plugin Hub