ua-restriction

Allows or denies clients by their User-Agent.

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

What it does

ua-restriction lets a request go on to the route's backend or refuses it by its User-Agent header. With Allow these clients every client that no entry of Allowlist matches is refused, with Deny these clients every client that an entry of Denylist matches. A refused client is answered 403 with Not allowed unless you set Message.

The User-Agent header is whatever the client chooses to send. A client that copies your app's header passes, so the plugin keeps out clients that announce themselves, not clients that pretend. Where access matters, add key-auth to the same route.

When to use it

• A route meant only for your mobile app, whose header starts with MobileApp/, with a message that tells every other client so.
• Scripted clients, curl and python-requests for example, kept off a route that browsers use.
• Crawlers that name themselves as bots in their header, refused with Deny these clients while every other client passes.
• A second check beside key-auth: a client needs a valid key and the header your app sends.

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

Set it up

Serve only your own mobile app and refuse every other client

The User-Agent is whatever the client chooses to send, so this keeps other clients out by accident, not by force; where access matters, pair it with a plugin that signs callers in.

Choose Allow these clients, fill Allowlist as in the JSON below and set Message to This API is served to the mobile app only..

ua-restriction · as the console saves it

{
  "allowlist": [
    "^MobileApp/"
  ],
  "message": "This API is served to the mobile app only."
}

More scenarios

Refuse scripted clients while letting browsers through

Choose Deny these clients and fill Denylist as in the JSON below.

ua-restriction · as the console saves it

{
  "denylist": [
    "^curl/",
    "^python-requests/",
    "^Go-http-client/"
  ]
}

Things to know

• Allowlist — With ^MobileApp/ in the list, your app passes, and a Firefox browser is answered 403 with your Message.
• Allowlist — Each entry is an expression matched anywhere in the header, so Chrome also takes zzChromezz; one that does not compile is refused at the write.
• Denylist — With ^curl/ in the list, a curl client is answered 403 with Not allowed, and a browser passes.
• Denylist — Each entry is an expression matched anywhere in the header, so Chrome also takes zzChromezz; one that does not compile is refused at the write.
• One copy of the plugin holds one list: Allowlist and Denylist together are refused when you save.
• Bypass missing — Off, a request that carries no User-Agent header at all is refused, whichever list is set.
• Message — An empty message is refused when you save; leave the field unset to answer Not allowed.
• AdviceTreat the header as a hint about the client, not as proof of who it is. Where a route must stay closed, sign callers in with key-auth and keep ua-restriction for clients that announce themselves.

Settings

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

Choose one:

• Allow these clientsA client the list does not match is refused.
• Deny these clientsA client the list matches is refused.

Allow these clients

Allowlistallowlistarray of stringsRequired

at least 1 item; each at least 1 character

Deny these clients

Denylistdenylistarray of stringsRequired

at least 1 item; each at least 1 character

Bypass missingbypass_missingbooleandefault false

Messagemessagestringdefault Not allowed

1 to 1024 characters

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