Copy page

IP Address Restriction Policy

Restrict which clients can reach a route based on their IP address. Configure an allow list to expose an endpoint only to a set of known networks, a deny list to shut out abusive traffic, or both. Entries can be individual IP addresses or CIDR ranges, in IPv4 or IPv6.

With this policy, you'll benefit from:

• Private APIs on a Public Gateway: Limit admin, partner, or internal endpoints to your office, VPN, or data center ranges
• Immediate Blocking: Drop traffic from a bad actor's address or subnet without a deploy of your backend
• Per-Route Control: Apply different lists to different routes, so a public endpoint and a restricted one can live in the same API
• IPv4 and IPv6: Single addresses and CIDR ranges in both families, with IPv4-mapped IPv6 addresses handled automatically
• Fail-Closed Defaults: Requests whose address cannot be determined are rejected when an allow list is set

Configuration

The configuration shows how to configure the policy in the 'policies.json' document.

Code
{
  "name": "my-ip-address-restriction-inbound-policy",
  "policyType": "ip-address-restriction-inbound",
  "handler": {
    "export": "IpAddressRestrictionInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "allow": ["203.0.113.42", "198.51.100.0/24"],
      "deny": ["203.0.113.99", "192.0.2.0/24"]
    }
  }
}

Policy Configuration

• name <string> - The name of your policy instance. This is used as a reference in your routes.
• policyType <string> - The identifier of the policy. This is used by the Zuplo UI. Value should be ip-address-restriction-inbound.
• handler.export <string> - The name of the exported type. Value should be IpAddressRestrictionInboundPolicy.
• handler.module <string> - The module containing the policy. Value should be $import(@zuplo/runtime).
• handler.options <object> - The options for this policy. See Policy Options below.

Policy Options

The options for this policy are specified below. All properties are optional unless specifically marked as required.

• allow <string[]> - The IP addresses and CIDR ranges that are allowed to call the route. When set, requests from every other address are rejected with a 403 Forbidden.
• deny <string[]> - The IP addresses and CIDR ranges that are rejected with a 403 Forbidden. Evaluated before allow, so an address matching both lists is rejected.
• clientIpHeader <string> - Read the client IP address from this header instead of the standard forwarding headers (x-real-ip, true-client-ip, cf-connecting-ip, then the first entry of x-forwarded-for). Only set this when a proxy in front of the gateway reports the client address in a non-standard header.
• allowUnknownIpAddress <boolean> - Allow requests whose client IP address cannot be determined. By default these requests are rejected when an allow list is set, because an unknown address cannot be on it. Defaults to false.

Using the Policy

This policy compares the client's IP address against an allow list, a deny list, or both, and rejects non-matching requests with a 403 Forbidden. Entries are individual IP addresses or CIDR ranges, in IPv4 or IPv6.

How It Works

For each request the policy:

1. Determines the client IP address — the same one reported to your code as context.incomingRequestProperties.ip — or reads it from clientIpHeader when that option is set
2. Rejects the request if the address matches any deny entry
3. Rejects the request if an allow list is set and the address matches none of its entries
4. Otherwise passes the request to the next policy or the handler

deny is evaluated first, so an address covered by both lists is rejected.

At least one of allow or deny must be set — a policy with neither would let every request through, which is never what was intended.

Policy Configuration

Allow only two networks and a single address:

Code
{
  "name": "ip-address-restriction",
  "policyType": "ip-address-restriction-inbound",
  "handler": {
    "export": "IpAddressRestrictionInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "allow": ["198.51.100.0/24", "2001:db8:1234::/48", "203.0.113.42"]
    }
  }
}

Block a single abusive network while leaving the route otherwise public:

Code
{
  "name": "ip-address-restriction",
  "policyType": "ip-address-restriction-inbound",
  "handler": {
    "export": "IpAddressRestrictionInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "deny": ["192.0.2.0/24"]
    }
  }
}

Writing Entries

• An entry without a prefix is a single address: 203.0.113.42 is the same as 203.0.113.42/32, and 2001:db8::1 the same as 2001:db8::1/128.
• Host bits beyond the prefix are ignored, so 10.1.2.3/8 and 10.0.0.0/8 mean the same range.
• IPv4-mapped IPv6 addresses are matched as the IPv4 address they map to. A client that a dual-stack proxy reports as ::ffff:198.51.100.7 matches an 198.51.100.0/24 entry.
• An IPv4 address never matches an IPv6 range, and vice versa. To cover a client reachable over both, list a range for each family.
• Addresses with leading zeros in an octet (010.0.0.1) are rejected, because different tools read them as different addresses.

Entries are validated when the policy is created, so a malformed address or prefix fails your deployment rather than rejecting live traffic. Each list can also be sourced from environment variables per entry:

Code
{
  "options": {
    "allow": ["$env(OFFICE_CIDR)", "$env(VPN_CIDR)"]
  }
}

Usage Example

Restrict an admin route while leaving the rest of the API public:

Code
{
  "paths": {
    "/v1/admin/users": {
      "get": {
        "x-zuplo-route": {
          "policies": {
            "inbound": ["ip-address-restriction", "api-key-auth"]
          },
          "handler": {
            "export": "urlForwardHandler",
            "module": "$import(@zuplo/runtime)",
            "options": {
              "baseUrl": "https://api.internal.example.com"
            }
          }
        }
      }
    }
  }
}

Put this policy first in the inbound list so restricted addresses are rejected before any work — authentication, rate limiting, upstream token fetches — is done on their behalf.

Where the Default Address Comes From

By default the policy uses the address the gateway itself resolved — the same value your code sees as context.incomingRequestProperties.ip. That comes from exactly one header, chosen by the platform running the gateway (true-client-ip on Cloudflare, x-real-ip elsewhere), and it is resolved from the request as it originally arrived.

Two consequences worth knowing:

• There is no fallback to a second header. If the trusted header is absent, the address is reported as unknown rather than being guessed from x-forwarded-for or another header. Every available fallback is one a caller can write, so a fallback would let anyone satisfy an allow list by sending a header.
• Header stripping does not affect it. The gateway removes x-real-ip and the cf-* headers from the request before policies run (from compatibility date 2024-01-15), but the default path reads the original request, so this makes no difference to it. It does affect clientIpHeader — see below.

During local development there is no edge to set the header and the caller really is the loopback interface, so the address is reported as 127.0.0.1. An allow list that does not cover 127.0.0.1 will reject your local requests — add it to the list to test locally:

Code
{
  "options": {
    "allow": ["198.51.100.0/24", "127.0.0.1", "::1"]
  }
}

Note that allowUnknownIpAddress does not help here. Locally the address is known — it is 127.0.0.1 — and that option only applies when no address could be determined at all.

Requests With No Client IP Address

When no client IP address can be determined, the request is rejected if an allow list is set, since an unknown address cannot be on it. With only a deny list the request continues, because there is nothing for it to match.

Set allowUnknownIpAddress to true to let these requests through even with an allow list. This is most useful when you run your own proxy and cannot guarantee it sets the trusted header on every request.

Custom Client IP Header

If a proxy in front of the gateway reports the client address in a header other than the standard ones, name it with clientIpHeader:

Code
{
  "options": {
    "allow": ["198.51.100.0/24"],
    "clientIpHeader": "x-client-ip"
  }
}

Only the named header is read when this is set. Prefer a header your proxy sets to a single address.

Unlike the default path, this option reads the request as policies see it, after the gateway has stripped x-real-ip and the cf-* headers (from compatibility date 2024-01-15). Naming one of those here resolves nothing, and with an allow list that rejects every request. Use a dedicated header your proxy sets, such as x-client-ip.

If the header holds a comma-separated list, the last entry is used, because proxies append and so the nearest proxy's entry is the rightmost one — everything to its left is whatever the caller sent. For a single-value header this makes no difference. This assumes one appending proxy in front of the gateway; if you have more than one, use a dedicated single-value header, since the trustworthy entry is then further left and its position depends on how many hops you control.

Security Considerations

• Rejected requests get a 403 Forbidden with no detail about the address seen or the rule matched. The address and the matching entry are written to the request log at debug level instead, so an unauthorized caller is not told what the gateway sees or that it is filtering by address at all.
• An IP address identifies a network path, not a caller. Combine this policy with an authentication policy rather than using it as your only control — addresses within an allowed range can be shared, reassigned, or spoofed upstream of your gateway.
• Prefer the narrowest ranges that work. A /8 allow entry covers 16 million addresses.

Read more about how policies work