ip-restriction

Allows or denies clients by IP address or CIDR range.

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

What it does

ip-restriction lets a request go on to the route's backend or refuses it by the client's address. With Allow these addresses every address outside Whitelist is refused, with Deny these addresses every address on Blacklist. A refused client is answered 403 with {"message":"Your IP address is not allowed"} unless you change Response code and Message.

It judges the address the request arrives from. Behind a load balancer that is the load balancer's own address, for every client. Add real-ip to the same route first: ip-restriction then judges each client's own address, the one real-ip takes from the header your load balancer writes.

When to use it

• A route only your partners call, from networks they give you, for example 203.0.113.0/24.
• An internal route, an administration API for example, that only your own offices or VPN may reach.
• A few addresses that misuse a route, kept out with Deny these addresses while everyone else passes.
• A second lock beside key-auth: a client needs a valid key and an address in the list.

Not for slowing down an address that calls too often instead of shutting it out — see limit-count (Limits the number of requests in a time window, per key).

Guides

Pages that walk through a job with ip-restriction, step by step.

• Allow a networkLet only requests from the networks you list reach a route.

Set it up

Let only the partner network call a route behind your load balancer

ip-restriction judges the address real-ip took from your load balancer's header. Add real-ip to the route first, with the addresses your load balancer connects from, 10.0.0.21 and 10.0.0.22 here, or every request is judged by the load balancer's own address.

Choose Allow these addresses and fill Whitelist as in the JSON below.

The console's Add plugin panel, filled with this example.

ip-restriction · as the console saves it

{
  "whitelist": [
    "203.0.113.0/24"
  ]
}

What you will see

• A client inside the partner network passes: a request your load balancer forwards for 203.0.113.7 reaches your backend, which receives X-Real-IP: 203.0.113.7.
• A client outside the partner network is answered 403 with {"message":"Your IP address is not allowed"}.
• Without real-ip on the route, a request your load balancer forwards for 203.0.113.7 is answered 403 as well: ip-restriction judges the load balancer's own address, which is not in the list.
• On a route that also carries key-auth, key-auth answers first: a client outside the partner network that sends no key is answered 401 with {"message":"Missing API key in request"}, and one that sends a valid key is answered 403.
• A client inside the partner network that sends a valid key passes and is answered 200.

More scenarios

Without real-ip, an allow list that holds the load balancer's network lets every client in

Shown as a warning: behind a load balancer add real-ip to the route first and list only your clients' networks under ip-restriction, as the first example does.

Choose Allow these addresses and fill Whitelist as in the JSON below.

ip-restriction · as the console saves it

{
  "whitelist": [
    "10.0.0.0/8",
    "203.0.113.0/24"
  ]
}

What you will see

• Without real-ip a request your load balancer forwards for a client outside both networks passes and is answered 200: ip-restriction sees the load balancer's address, and the list holds it.
• With real-ip on the route the list sees each client's own address: a client outside both networks is answered 403 with {"message":"Your IP address is not allowed"}.

Deny a few abusive addresses and answer them with a 404

Behind a load balancer this list too needs real-ip on the route first, or it is checked against the load balancer's own address.

Choose Deny these addresses, fill Blacklist as in the JSON below, set Message to This path is not served here. and set Response code to 404.

ip-restriction · as the console saves it

{
  "blacklist": [
    "198.51.100.23",
    "198.51.100.128/25"
  ],
  "response_code": 404,
  "message": "This path is not served here."
}

What you will see

• A client on the list is answered 404 with {"message":"This path is not served here."}.
• Every address outside the list passes and is answered 200.

Things to know

• Whitelist — Checked against the address the request arrives from: behind a load balancer that is the load balancer's, for every client, so add real-ip to the route first.
• Blacklist — Checked against the address the request arrives from: behind a load balancer that is the load balancer's, for every client, so add real-ip to the route first.
• Whitelist — An entry is one address, 203.0.113.7 for example, or a network written with its prefix length, 203.0.113.0/24. An entry that is neither, 10.0.0.0/33 for example, is refused when you save.
• Response code — Only 403 and 404 can be set; 405 is refused when you save.
• AdviceFor a client whose address is not fixed, a mobile app on the internet for example, a list of networks is no lock. Give it a key with key-auth instead.

Settings

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

Choose one:

• Allow these addressesEvery address outside the list is refused.
• Deny these addressesEvery address on the list is refused.

Allow these addresses

Whitelistwhitelistarray of stringsRequired

at least 1 item

Deny these addresses

Blacklistblacklistarray of stringsRequired

at least 1 item

Messagemessagestringdefault Your IP address is not allowed

1 to 1024 characters

Response coderesponse_codeintegerdefault 403

The status sent to a refused address.

403 to 404

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