Skip to content

Latest commit

 

History

History
126 lines (102 loc) · 4.29 KB

referer-restriction.md

File metadata and controls

126 lines (102 loc) · 4.29 KB
title keywords description
referer-restriction
Apache APISIX
API Gateway
Referer restriction
This document contains information about the Apache APISIX referer-restriction Plugin, which can be used to restrict access to a Service or a Route by whitelisting/blacklisting the Referer request header.

Description

The referer-restriction Plugin can be used to restrict access to a Service or a Route by whitelisting/blacklisting the Referer request header.

Attributes

Name Type Required Default Valid values Description
whitelist array[string] False List of hostnames to whitelist. A hostname can start with * for wildcard.
blacklist array[string] False List of hostnames to blacklist. A hostname can start with * for wildcard.
message string False "Your referer host is not allowed" [1, 1024] Message returned when access is not allowed.
bypass_missing boolean False false When set to true, bypasses the check when the Referer request header is missing or malformed.

:::info IMPORTANT

Only one of whitelist or blacklist attribute must be specified. They cannot work together.

:::

Enable Plugin

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

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": {
        "referer-restriction": {
            "bypass_missing": true,
            "whitelist": [
                "xx.com",
                "*.xx.com"
            ]
        }
    }
}'

Example usage

Once you have configured the Plugin as shown above, you can test it by setting Referer: http://xx.com/x:

curl http://127.0.0.1:9080/index.html -H 'Referer: http://xx.com/x'
HTTP/1.1 200 OK
...

Now, if you make a request with Referer: http://yy.com/x, the request will be blocked:

curl http://127.0.0.1:9080/index.html -H 'Referer: http://yy.com/x'
HTTP/1.1 403 Forbidden
...
{"message":"Your referer host is not allowed"}

Since we have set bypass_missing to true, a request without the Referer header will be successful as the check is skipped:

curl http://127.0.0.1:9080/index.html
HTTP/1.1 200 OK
...

Delete Plugin

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