Skip to main content

Allow a network

Some routes should answer only a known network: a partner's, your offices, a VPN. ip-restriction lets a request through or refuses it by the address it comes from. This guide opens orders-api to the partner network 203.0.113.0/24 and nobody else. At the end, a request from outside the network is refused even with a valid key.

Before you start​

  • This guide starts from orders-api as Route requests to a backend leaves it, with key-auth from Require an API key. A plugin from another guide that this page does not name can change the answers below; remove it first or work on a copy of the route.
  • With key-auth on the route, a request from inside the network needs the key too. The address list is a second lock, not a replacement for the key.
  • Whether a load balancer sits in front of the gateway. If one does, every request arrives from the load balancer's address, and the list would judge that address for every client. Put real-ip on the route first, as See each client's own address shows, and ip-restriction then judges each client's own address.
  • Every network that calls the route. Once the plugin is on, every address outside the list is refused, so leave none out.
  • The host name of your gateway. In the console it is the first part of the Address line on a route's Overview tab, api.example.com in this page's examples; replace it in every request below.
  • The requests below call /orders/3101.
  • The Editor or Environment administrator role in this environment.

Steps​

1. Add ip-restriction to the route​

Open orders-api under Routes, select its Plugins tab, then Add plugin at the top right of the tab. Open the Security category, or type ip-restriction in the search box. Select ip-restriction, then Configure.

2. List the partner network​

Keep Allow these addresses chosen. In Whitelist, type a value and press Enter for each, here 203.0.113.0/24 and every other network that calls the route. Leave Message and Response code as they are. Select Add plugin at the bottom of the panel. The plugin is saved like this:

The Add ip-restriction panel with the partner network in the allow list.
ip-restriction · as the console saves it
{
  "whitelist": [
    "203.0.113.0/24"
  ]
}

Check it​

Send a request from your own machine, outside the partner network, first without a key and then with the key of mobile-app in the x-api-key header. Then ask the partner to send one from inside it, with a valid key.

curl
curl -i -L 'https://<gateway host>/orders/3101'
From outside the network, on a route with key-auth
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.
Inside the network, with a valid key
A client inside the partner network that sends a valid key passes and is answered 200.

The answer from inside the network holds when no other restriction plugin is on the route. consumer-restriction from Allow only named clients or acl from Allow a team by label can still refuse the key.

On a route without key-auth, and behind a load balancer, the answers are these. They assume a load balancer that writes each client's address into X-Forwarded-For, with real-ip on the route as See each client's own address shows. Your backend then receives the client's address in X-Real-IP.

From outside the network
A client outside the partner network is answered 403 with {"message":"Your IP address is not allowed"}.
From inside the network
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.
Behind a load balancer, without real-ip
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.

What to know​

  • Behind a load balancer, a list without real-ip judges the load balancer's own address. A list that leaves it out refuses every client. A list that holds the load balancer's network lets every client in, because every request arrives from inside it.
  • The route's own Client addresses field cannot do this job behind a load balancer. The route is matched before its plugins run, so that field sees only the load balancer's address.
  • An entry is one address, 203.0.113.7, or a network with its prefix length, 203.0.113.0/24. Anything else is refused when you save.
  • To keep a few addresses out while everyone else passes, choose Deny these addresses and list them under Blacklist. The Response code can be 403 or 404 only.
  • For a client whose address is not fixed, a mobile client on the internet for example, a list of networks is no lock. Give it a key instead.
G8 dev