consumer-restriction
The consumer-restriction plugin enables access controls based on consumer name, route ID, service ID, or consumer group ID.
The plugin needs to work with authentication plugins, such as key-auth and jwt-auth, which means you should always create at least one consumer in your use case. See examples below for more details.
Examples
The examples below demonstrate how you can configure consumer-restriction plugin for different scenarios.
While the examples use key-auth as the authentication method, you can easily adjust to other authentication plugins based on your needs.
Restrict Access by Consumers
The example below demonstrates how you can use the consumer-restriction plugin on a route to restrict consumer access by consumer names, where consumers are authenticated with key-auth.
Create a consumer JohnDoe:
curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"username": "JohnDoe"
}'
Create key-auth credential for the consumer:
curl "http://127.0.0.1:9180/apisix/admin/consumers/JohnDoe/credentials" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"id": "cred-john-key-auth",
"plugins": {
"key-auth": {
"key": "john-key"
}
}
}'
Create a second consumer JaneDoe:
curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"username": "JaneDoe"
}'
Create key-auth credential for the consumer:
curl "http://127.0.0.1:9180/apisix/admin/consumers/JaneDoe/credentials" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"id": "cred-jane-key-auth",
"plugins": {
"key-auth": {
"key": "jane-key"
}
}
}'
Next, create a route with key authentication enabled, and configure consumer-restriction to allow only consumer JaneDoe:
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"id": "consumer-restricted-route",
"uri": "/get",
"plugins": {
"key-auth": {},
"consumer-restriction": {
"whitelist": ["JaneDoe"]
}
},
"upstream" : {
"nodes": {
"httpbin.org":1
}
}
}'
Send a request to the route as consumer JohnDoe:
curl -i "http://127.0.0.1:9080/get" -H 'apikey: john-key'
You should receive an HTTP/1.1 403 Forbidden response with the following message:
{"message":"The consumer_name is forbidden."}
Send another request to the route as consumer JaneDoe:
curl -i "http://127.0.0.1:9080/get" -H 'apikey: jane-key'
You should receive an HTTP/1.1 200 OK response, showing the consumer access is permitted.
Restrict Access by Consumers and HTTP Methods
The example below demonstrates how you can use the consumer-restriction plugin on a route to restrict consumer access by consumer name and HTTP methods, where consumers are authenticated with key-auth.
Create a consumer JohnDoe:
curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"username": "JohnDoe"
}'
Create key-auth credential for the consumer:
curl "http://127.0.0.1:9180/apisix/admin/consumers/JohnDoe/credentials" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"id": "cred-john-key-auth",
"plugins": {
"key-auth": {
"key": "john-key"
}
}
}'
Create a second consumer JaneDoe:
curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"username": "JaneDoe"
}'
Create key-auth credential for the consumer:
curl "http://127.0.0.1:9180/apisix/admin/consumers/JaneDoe/credentials" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"id": "cred-jane-key-auth",
"plugins": {
"key-auth": {
"key": "jane-key"
}
}
}'
Next, create a route with key authentication enabled, and use consumer-restriction to allow only the configured HTTP methods by consumers:
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"id": "consumer-restricted-route",
"uri": "/anything",
"plugins": {
"key-auth": {},
"consumer-restriction": {
"allowed_by_methods":[
{
"user": "JohnDoe",
"methods": ["GET"]
},
{
"user": "JaneDoe",
"methods": ["POST"]
}
]
}
},
"upstream" : {
"nodes": {
"httpbin.org":1
}
}
}'
Send a POST request to the route as consumer JohnDoe:
curl -i "http://127.0.0.1:9080/anything" -X POST -H 'apikey: john-key'
You should receive an HTTP/1.1 403 Forbidden response with the following message:
{"message":"The consumer_name is forbidden."}
Now, send a GET request to the route as consumer JohnDoe:
curl -i "http://127.0.0.1:9080/anything" -X GET -H 'apikey: john-key'
You should receive an HTTP/1.1 200 OK response, showing the consumer access is permitted.
You can also verify the configurations by sending requests as consumer JaneDoe and observe the behaviours match up to what was configured in the consumer-restriction plugin on the route.
Restricting by Service ID
The example below demonstrates how you can use the consumer-restriction plugin to restrict consumer access by service ID, where the consumer is authenticated with key-auth.
Create two sample services:
curl "http://127.0.0.1:9180/apisix/admin/services" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"id": "srv-1",
"upstream": {
"type": "roundrobin",
"nodes": {
"httpbin.org":1
}
}
}'
curl "http://127.0.0.1:9180/apisix/admin/services" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"id": "srv-2",
"upstream": {
"type": "roundrobin",
"nodes": {
"mock.api7.ai":1
}
}
}'
Next, create a consumer with key-auth and configure consumer-restriction to allow only srv-1 service:
curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"username": "JohnDoe",
"plugins": {
"key-auth": {
"key": "john-key"
},
"consumer-restriction": {
"type": "service_id",
"whitelist": ["srv-1"]
}
}
}'
Finally, create two routes, with each belonging to one of the services created earlier:
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"id": "srv-1-route",
"uri": "/anything",
"service_id": "srv-1"
}'
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"id": "srv-2-route",
"uri": "/srv-2",
"service_id": "srv-2"
}'
Send a request to the route in the srv-1 service:
curl -i "http://127.0.0.1:9080/anything" -H 'apikey: john-key'
You should receive an HTTP/1.1 200 OK response, showing the consumer access is permitted.
Send a request to the route in the srv-2 service:
curl -i "http://127.0.0.1:9080/srv-2" -H 'apikey: john-key'
You should receive an HTTP/1.1 401 Unauthorized response with the following message:
{"message":"The request is rejected, please check the service_id for this request"}