Skip to content

Latest commit

 

History

History
124 lines (98 loc) · 4.28 KB

ua-restriction.md

File metadata and controls

124 lines (98 loc) · 4.28 KB
Raw
title keywords description
ua-restriction
Apache APISIX
API Gateway
UA restriction
This document contains information about the Apache APISIX ua-restriction Plugin, which allows you to restrict access to a Route or Service based on the User-Agent header with an allowlist and a denylist.

Description

The ua-restriction Plugin allows you to restrict access to a Route or Service based on the User-Agent header with an allowlist and a denylist.

A common scenario is to set crawler rules. User-Agent is the identity of the client when sending requests to the server, and the user can allow or deny some crawler request headers in the ua-restriction Plugin.

Attributes

Name Type Required Default Valid values Description
bypass_missing boolean False false When set to true, bypasses the check when the User-Agent header is missing.
allowlist array[string] False List of allowed User-Agent headers.
denylist array[string] False List of denied User-Agent headers.
message string False "Not allowed" Message with the reason for denial to be added to the response.

:::note

allowlist and denylist can't be configured at the same time.

:::

Enable Plugin

You can enable the Plugin on a Route or a Service as shown below:

:::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/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": {
        "ua-restriction": {
             "bypass_missing": true,
             "denylist": [
                 "my-bot2",
                 "(Twitterspider)/(\\d+)\\.(\\d+)"
             ],
             "message": "Do you want to do something bad?"
        }
    }
}'

Example usage

Send a request to the route:

curl http://127.0.0.1:9080/index.html -i

You should receive an HTTP/1.1 200 OK response.

Now if the User-Agent header is in the denylist i.e the bot User-Agent:

curl http://127.0.0.1:9080/index.html --header 'User-Agent: Twitterspider/2.0'

You should receive an HTTP/1.1 403 Forbidden response with the following message:

{"message":"Do you want to do something bad?"}

Delete Plugin

To remove the ua-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",
    "plugins": {},
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:1980": 1
        }
    }
}'