Skip to main content
Version: 3.11

consumer-restriction

Description#

The consumer-restriction Plugin allows users to configure access restrictions on Consumer, Route, Service, or Consumer Group.

Attributes#

NameTypeRequiredDefaultValid valuesDescription
typestringFalseconsumer_name["consumer_name", "consumer_group_id", "service_id", "route_id"]Type of object to base the restriction on.
whitelistarray[string]TrueList of objects to whitelist. Has a higher priority than allowed_by_methods.
blacklistarray[string]TrueList of objects to blacklist. Has a higher priority than whitelist.
rejected_codeintegerFalse403[200,...]HTTP status code returned when the request is rejected.
rejected_msgstringFalseMessage returned when the request is rejected.
allowed_by_methodsarray[object]FalseList of allowed configurations for Consumer settings, including a username of the Consumer and a list of allowed HTTP methods.
allowed_by_methods.userstringFalseA username for a Consumer.
allowed_by_methods.methodsarray[string]False["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "CONNECT", "TRACE", "PURGE"]List of allowed HTTP methods for a Consumer.
note

The different values in the type attribute have these meanings:

  • consumer_name: Username of the Consumer to restrict access to a Route or a Service.
  • consumer_group_id: ID of the Consumer Group to restrict access to a Route or a Service.
  • service_id: ID of the Service to restrict access from a Consumer. Need to be used with an Authentication Plugin.
  • route_id: ID of the Route to restrict access from a Consumer.

Example usage#

Restricting by consumer_name#

The example below shows how you can use the consumer-restriction Plugin on a Route to restrict specific consumers.

You can first create two consumers jack1 and jack2:

note

You can fetch the admin_key from config.yaml and save to an environment variable with the following command:

admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
curl http://127.0.0.1:9180/apisix/admin/consumers -H "X-API-KEY: $admin_key" -X PUT -i -d '
{
"username": "jack1",
"plugins": {
"basic-auth": {
"username":"jack2019",
"password": "123456"
}
}
}'

curl http://127.0.0.1:9180/apisix/admin/consumers -H "X-API-KEY: $admin_key" -X PUT -i -d '
{
"username": "jack2",
"plugins": {
"basic-auth": {
"username":"jack2020",
"password": "123456"
}
}
}'

Next, you can configure the Plugin to the Route:

curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
{
"uri": "/index.html",
"upstream": {
"type": "roundrobin",
"nodes": {
"127.0.0.1:1980": 1
}
},
"plugins": {
"basic-auth": {},
"consumer-restriction": {
"whitelist": [
"jack1"
]
}
}
}'

Now, this configuration will only allow jack1 to access your Route:

curl -u jack2019:123456 http://127.0.0.1:9080/index.html
HTTP/1.1 200 OK

And requests from jack2 are blocked:

curl -u jack2020:123456 http://127.0.0.1:9080/index.html -i
HTTP/1.1 403 Forbidden
...
{"message":"The consumer_name is forbidden."}

Restricting by allowed_by_methods#

The example below configures the Plugin to a Route to restrict jack1 to only make POST requests:

curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
{
"uri": "/index.html",
"upstream": {
"type": "roundrobin",
"nodes": {
"127.0.0.1:1980": 1
}
},
"plugins": {
"basic-auth": {},
"consumer-restriction": {
"allowed_by_methods":[{
"user": "jack1",
"methods": ["POST"]
}]
}
}
}'

Now if jack1 makes a GET request, the access is restricted:

curl -u jack2019:123456 http://127.0.0.1:9080/index.html
HTTP/1.1 403 Forbidden
...
{"message":"The consumer_name is forbidden."}

To also allow GET requests, you can update the Plugin configuration and it would be reloaded automatically:

curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
{
"uri": "/index.html",
"upstream": {
"type": "roundrobin",
"nodes": {
"127.0.0.1:1980": 1
}
},
"plugins": {
"basic-auth": {},
"consumer-restriction": {
"allowed_by_methods":[{
"user": "jack1",
"methods": ["POST","GET"]
}]
}
}
}'

Now, if a GET request is made:

curl -u jack2019:123456 http://127.0.0.1:9080/index.html
HTTP/1.1 200 OK

Restricting by service_id#

To restrict a Consumer from accessing a Service, you also need to use an Authentication Plugin. The example below uses the key-auth Plugin.

First, you can create two services:

curl http://127.0.0.1:9180/apisix/admin/services/1 -H "X-API-KEY: $admin_key" -X PUT -d '
{
"upstream": {
"nodes": {
"127.0.0.1:1980": 1
},
"type": "roundrobin"
},
"desc": "new service 001"
}'

curl http://127.0.0.1:9180/apisix/admin/services/2 -H "X-API-KEY: $admin_key" -X PUT -d '
{
"upstream": {
"nodes": {
"127.0.0.1:1980": 1
},
"type": "roundrobin"
},
"desc": "new service 002"
}'

Then configure the consumer-restriction Plugin on the Consumer with the key-auth Plugin and the service_id to whitelist.

curl http://127.0.0.1:9180/apisix/admin/consumers -H "X-API-KEY: $admin_key" -X PUT -d '
{
"username": "new_consumer",
"plugins": {
"key-auth": {
"key": "auth-jack"
},
"consumer-restriction": {
"type": "service_id",
"whitelist": [
"1"
],
"rejected_code": 403
}
}
}'

Finally, you can configure the key-auth Plugin and bind the service to the Route:

curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
{
"uri": "/index.html",
"upstream": {
"type": "roundrobin",
"nodes": {
"127.0.0.1:1980": 1
}
},
"service_id": 1,
"plugins": {
"key-auth": {
}
}
}'

Now, if you test the Route, you should be able to access the Service:

curl http://127.0.0.1:9080/index.html -H 'apikey: auth-jack' -i
HTTP/1.1 200 OK
...

Now, if the Route is configured to the Service with service_id 2:

curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
{
"uri": "/index.html",
"upstream": {
"type": "roundrobin",
"nodes": {
"127.0.0.1:1980": 1
}
},
"service_id": 2,
"plugins": {
"key-auth": {
}
}
}'

Since the Service is not in the whitelist, it cannot be accessed:

curl http://127.0.0.1:9080/index.html -H 'apikey: auth-jack' -i
HTTP/1.1 403 Forbidden
...
{"message":"The service_id is forbidden."}

Delete Plugin#

To remove the consumer-restriction Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.

curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
{
"uri": "/index.html",
"upstream": {
"type": "roundrobin",
"nodes": {
"127.0.0.1:1980": 1
}
},
"plugins": {
"basic-auth": {}
}
}'