Version: 3.10

consumer-restriction

Description#

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

Attributes#

Name	Type	Required	Default	Valid values	Description
type	string	False	consumer_name	["consumer_name", "consumer_group_id", "service_id", "route_id"]	Type of object to base the restriction on.
whitelist	array[string]	True			List of objects to whitelist. Has a higher priority than `allowed_by_methods`.
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.
allowed_by_methods	array[object]	False			List of allowed configurations for Consumer settings, including a username of the Consumer and a list of allowed HTTP methods.
allowed_by_methods.user	string	False			A username for a Consumer.
allowed_by_methods.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.
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": {}
    }
}'

Description#

Attributes#

note

Example usage#

Restricting by consumer_name#

note

Restricting by allowed_by_methods#

Restricting by service_id#

Delete Plugin#

Restricting by `consumer_name`#

Restricting by `allowed_by_methods`#

Restricting by `service_id`#