consumer-restriction

Description

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

Attributes

Name	Type	Required	Default	Valid values	Description
type	string	False	consumer_name	["consumer_name", "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		["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.
• 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:

curl http://127.0.0.1:9180/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -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: edd1c9f034335f136f87ad84b625c8f1' -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: edd1c9f034335f136f87ad84b625c8f1' -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: edd1c9f034335f136f87ad84b625c8f1' -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: edd1c9f034335f136f87ad84b625c8f1' -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: edd1c9f034335f136f87ad84b625c8f1' -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: edd1c9f034335f136f87ad84b625c8f1' -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: edd1c9f034335f136f87ad84b625c8f1' -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: edd1c9f034335f136f87ad84b625c8f1' -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: edd1c9f034335f136f87ad84b625c8f1' -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."}

Disable Plugin

To disable 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: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "uri": "/index.html",
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:1980": 1
        }
    },
    "plugins": {
        "basic-auth": {}
    }
}'