Project: APISIX (Orchestration & Management / API Gateway)
File: consumer-restriction.md

title: consumer-restriction keywords: Apache APISIX API Gateway Consumer restriction description: The Consumer Restriction Plugin allows users to configure access restrictions on Consumer, Route, Service, or Consumer Group. <!-- --> The `consumer-restriction` Plugin allows users to configure access restrictions on Consumer, Route, Service, or Consumer Group. | Name | Type | Required | Default | Valid values | Description | | -- | - | -- | - | | | | type | string | False | consumername | ["consumername", "consumergroupid", "serviceid", "routeid"] | Type of object to base the restriction on. | | whitelist | array[string] | True | | | List of objects to whitelist. Has a higher priority than `allowedbymethods`. | | blacklist | array[string] | True | | | List of objects to blacklist. Has a higher priority than `whitelist`. | | rejected_code | integer | False | 403 | [200,...] | HTTP status code returned when the request is rejected. | | rejected_msg | string | False | | | Message returned when the request is rejected. | | allowedbymethods | array[object] | False | | | List of allowed configurations for Consumer settings, including a username of the Consumer and a list of allowed HTTP methods. | | allowedbymethods.user | string | False | | | A username for a Consumer. | | allowedbymethods.methods | array[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. `consumergroupid`: 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. ::: 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: ```bash adminkey=$(yq '.deployment.admin.adminkey[0].key' conf/config.yaml | sed 's/"//g') ``` ::: ```shell 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: ```shell 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: ```shell curl -u jack2019:123456 http://127.0.0.1:9080/index.html ``` ```shell HTTP/1.1 200 OK ``` And requests from `jack2` are blocked: ```shell curl -u jack2020:123456 http://127.0.0.1:9080/index.html -i ``` ```shell HTTP/1.1 403 Forbidden

{"message":"The consumer_name is forbidden."} ``` The example below configures the Plugin to a Route to restrict `jack1` to only make `POST` requests: ```shell 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": { "allowedbymethods":[{ "user": "jack1", "methods": ["POST"] }] } } }' ``` Now if `jack1` makes a `GET` request, the access is restricted: ```shell curl -u jack2019:123456 http://127.0.0.1:9080/index.html ``` ```shell 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: ```shell 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": { "allowedbymethods":[{ "user": "jack1", "methods": ["POST","GET"] }] } } }' ``` Now, if a `GET` request is made: ```shell curl -u jack2019:123456 http://127.0.0.1:9080/index.html ``` ```shell HTTP/1.1 200 OK ``` To restrict a Consumer from accessing a Service, you also need to use an Authentication Plugin. The example below uses the Plugin. First, you can create two services: ```shell 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. ```shell 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: ```shell 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: ```shell curl http://127.0.0.1:9080/index.html -H 'apikey: auth-jack' -i ``` ```shell HTTP/1.1 200 OK ... ``` Now, if the Route is configured to the Service with `service_id` `2`: ```shell 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: ```shell curl http://127.0.0.1:9080/index.html -H 'apikey: auth-jack' -i ``` ```shell HTTP/1.1 403 Forbidden ... {"message":"The service_id is forbidden."} ``` 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. ```shell 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": {} } }' ```