referer-restriction

Allows or denies requests by their Referer header.

Category SecurityAdd it to Route, Service, Consumer, Consumer group, Global rule, Plugin configEngine plugin referer-restrictionPriority 2990

What it does

referer-restriction lets a request go on to the route's backend or refuses it by the host in its Referer header, the page that sent the client. With Allow these referers every host outside Whitelist is refused, with Deny these referers every host on Blacklist. A refused request is answered 403 with Your referer host is not allowed unless you set Message.

A request that carries no Referer at all, a direct visit or a link opened from an app, is refused unless Bypass missing is on. The header is whatever the client chooses to send, so the plugin keeps other sites from linking to you, not callers who write the header themselves.

When to use it

• Images or files your own sites show, which other sites should not link to directly.
• A route your pages on example.com and its subdomains call, with direct visits still let through.
• One site that links to your content without leave, scraper.example.com for example, refused with a message of your own while everyone else passes.

Not for judging the address a request arrives from — see ip-restriction (Allows or denies clients by IP address or CIDR range), judging the client software by its User-Agent header — see ua-restriction (Allows or denies clients by their User-Agent) or refusing requests by their path — see uri-blocker (Blocks requests whose URI matches a rule).

Set it up

Allow requests linked from your own sites and direct visits

Choose Allow these referers, fill Whitelist as in the JSON below and turn on Bypass missing.

referer-restriction · as the console saves it

{
  "whitelist": [
    "example.com",
    "*.example.com"
  ],
  "bypass_missing": true
}

More scenarios

Refuse requests linked from a named site

Choose Deny these referers, fill Blacklist as in the JSON below, turn on Bypass missing and set Message to This content cannot be linked from that site..

referer-restriction · as the console saves it

{
  "blacklist": [
    "scraper.example.com"
  ],
  "bypass_missing": true,
  "message": "This content cannot be linked from that site."
}

Things to know

• Whitelist — With example.com and *.example.com in the list, links from https://example.com/start and https://shop.example.com/cart pass, and a link from https://other.example/page is answered 403.
• Whitelist — A leading star matches only longer names: *.example.com takes deep.example.com but not example.com itself. A bare star takes every host.
• Whitelist — An entry is a host name alone. One that carries a scheme, https://app.example.com for example, is refused when you save.
• Whitelist — An entry that carries a path, app.example.com/orders for example, is refused when you save.
• Whitelist — An entry that carries a port, app.example.com:8443 for example, is refused when you save: the host is compared without its port.
• Blacklist — With scraper.example.com in the list, a link from https://scraper.example.com/page is answered 403 with your Message, and a link from https://www.example.com/page passes.
• Blacklist — A leading star matches only longer names: *.example.com takes deep.example.com but not example.com itself. A bare star takes every host.
• Bypass missing — On, a request with no Referer passes with either list.
• Bypass missing — On, a request with no Referer, or one that is not a URL, is let through. Off, it is refused with either list.
• One copy of the plugin holds one list: Whitelist and Blacklist together are refused when you save.
• AdviceKeep referer-restriction for links between sites. Where a route must stay closed to anyone who can write a header, sign callers in with key-auth on the same route.

Settings

The fields as the console shows them, section by section.

Choose one:

• Allow these referersA request whose referer is outside the list is refused.
• Deny these referersA request whose referer the list matches is refused.

Allow these referers

Whitelistwhitelistarray of stringsRequired

at least 1 item

Deny these referers

Blacklistblacklistarray of stringsRequired

at least 1 item

Bypass missingbypass_missingbooleandefault false

Messagemessagestringdefault Your referer host is not allowed

1 to 1024 characters

Every plugin also has Enabled, Priority, Filter, Error response and Pre-function: see Plugin execution settings.