When Apache APISIX IP restriction stops unwanted clients before authentication
The ip-restriction, ua-restriction and referer-restriction plugins let an APISIX gateway reject requests by client address, user agent or referring site before any authentication or upstream call takes place. Teams need them when a gateway is reachable from the internet and receives traffic from sources that should never call its APIs, such as known abusive networks, automated scrapers using default client libraries, or embedded pages hotlinking an API. The plugins run early in the request path, so a denied request costs the gateway little and never reaches a backend. That is their value, and also their limit: a client address, a user agent string and a Referer header are all supplied by the caller and can be forged, so these controls are a coarse filter, not a replacement for identity. Authentication and authorization still have to decide who may call each route.
Before you configure these plugins, confirm which plugin versions your gateway runs, because the ua-restriction behavior changed in release 3.5.0, and check the plugin reference for each field you plan to use. Decide in advance whether a route should default to allow or deny, and who owns the lists, since an allow list that nobody maintains becomes an outage waiting to happen. Teams that need to deny by client address must first confirm how the gateway identifies the real client behind load balancers, which is covered in the section on trusted proxies and real client IPs. Other members of the same security plugin family, including cors, uri-blocker, consumer-restriction and acl, cover browser policy, path blocking and consumer-level access, and each has its own role alongside these filters.
How the ip, user agent, referer and URI blocking plugins differ
Apache APISIX offers four plugins that refuse requests based on what the client sends before any authentication runs. Each one reads a different part of the request, so each suits a different kind of unwanted traffic. Knowing which field a plugin trusts is the basis for choosing between them.
ip-restriction for network sources
The ip-restriction plugin matches the client address against allow and deny lists of single addresses or CIDR ranges. It is the only one of the four that rests on a network-level fact, so it is the natural choice for limiting access to partner networks, office ranges or known bad sources. The address it sees depends on the real-ip configuration in front of the gateway, so confirm that before writing any list. Check how the list behaves for IPv6 clients as well.
ua-restriction for User-Agent values
The ua-restriction plugin allows or denies requests by matching the User-Agent header against a list. Since APISIX 3.5.0 an instance cannot enable the allowlist and the denylist together, so pick one mode per route. Use it to screen out known scraping tools and automated clients that announce themselves. A client that wants to pass can send any User-Agent it likes.
referer-restriction for Referer values
The referer-restriction plugin accepts or rejects requests based on the Referer header, which names the page that linked to the resource. It suits browser-facing endpoints that should only be called from your own web pages, such as embedded widgets. Browsers may omit the header, and clients can set it freely, so this filters casual misuse rather than stopping a determined caller. Test the behavior with privacy settings that strip referrers.
uri-blocker for path patterns
The uri-blocker plugin rejects requests whose URI matches a configured list of patterns. It is useful for hiding administrative paths, configuration files or known probe targets that should never reach an upstream service. Patterns are written in the plugin's own syntax, so test each one against real route paths to avoid blocking legitimate calls. Pair it with route-level scoping so it does not affect APIs that legitimately use similar paths.
Which signal to trust
Only the IP address reflects a network path the client cannot simply rewrite, while the User-Agent, Referer and URI are all supplied by the client. Treat the header and URI plugins as noise reduction and place identity or authorization checks behind them. For any control that must hold against a deliberate attacker, plan authentication, rate limits and upstream controls as well. Document this split in the design so reviewers know what each filter is meant to stop.
Choosing allow lists or deny lists for each traffic situation
When only known partner networks should reach an API, an allow list looks like the natural control. The risk is that an allow list is closed by default: any client outside the list receives a denial, including legitimate users who route through networks you did not anticipate, such as a mobile carrier's shared egress, a new office, or a partner's cloud NAT that changes after a migration. On a public API this failure is usually silent to the business until a partner reports errors. Use an allow list here only with a documented fallback, such as a second authentication factor (key-auth, jwt-auth or openid-connect) for clients outside the list, or a lower rate limit instead of a hard denial.
- False positives: partner traffic arriving through a proxy, CDN or NAT gateway whose address is not on the list.
- Fallback design: route out-of-list clients to a stricter authentication path rather than returning a flat denial.
- Ownership: agree with each partner who updates the range and how fast changes are applied.
- Testing: verify from each partner's actual egress path, not from a lab address.
- Illustrative example: a list containing a placeholder range such as 203.0.113.0/24 is only a format reminder, not a real partner.
Before go-live, confirm with each partner the exact source addresses their requests carry, and confirm how your load balancers pass them to the gateway.
When you already know a range that produces abuse, a deny list fits because the default remains open for the wider customer base. Deny lists are cheap to change and easy to explain, but they only stop the addresses you have named. Attackers rotate addresses across providers, so a deny list tends to become a maintenance task tied to incident response rather than a durable control. Broad ranges are the main source of false positives: a single entry can block a shared cloud provider, a university or a carrier, and those blocks often hit customers who never sent abusive traffic.
- False positives: a broad CIDR block that covers shared hosting or carrier-grade NAT used by legitimate users.
- Scope: prefer narrow entries tied to a specific incident, with an owner and a review date.
- Complement: pair the deny list with rate limiting and authentication, which work on behavior rather than address.
- Logging: record denied requests so the team can see whether a block is still in use.
- Illustrative example: a placeholder such as 198.51.100.0/24 shows the notation, not a recommendation.
Confirm with your security team how long each entry should remain, and who removes entries once the source has stopped.
Internal and administrative routes usually have a small, known set of clients, such as an operations network, a VPN pool or a bastion host. An allow list fits well here because the expected population is small and changes are controlled. The main risk is not false positives from the public, but lockouts during network changes: a VPN pool renumbered, a bastion moved, or a load balancer that stops passing the true client address can cut off the team that needs the route most. Keep an alternate access path documented and tested before tightening the list.
- Scope: restrict administrative paths and management endpoints, not only the public listener.
- Dependency: the allow list is only as good as the client address the gateway sees, so confirm the proxy chain first.
- Break-glass: keep a tested, separately controlled access method for recovery.
- Change control: route list edits through the same approval process as other access changes.
- Layering: combine the list with authentication, since an address alone does not identify a person.
Ask the platform team to confirm which networks reach the Admin API and to document the access path used during an outage.
Webhook and callback endpoints receive requests from third-party services that call back into your system. Allow lists are attractive because providers often publish source ranges, but those published ranges can change, and some providers send from addresses that are not stable across regions or services. A deny list is usually a poor fit here because you rarely know the abusive sources in advance, and blocking a provider's range can break payment, notification or identity flows without a clear error for the business. For these routes, signature verification of the request body is often the stronger control, with the address check as a secondary layer.
- False positives: provider ranges that change without notice, or retries from addresses outside the published list.
- Signatures: verify the provider's signature or shared secret in the gateway or the service before processing.
- Monitoring: alert on rejected callbacks so a range change does not silently stop events.
- Ownership: record which provider owns each route and where its published address list is maintained.
- Retries: confirm how the provider retries failed deliveries and how long it keeps them.
Before enabling any address restriction, confirm with each provider whether it publishes a supported source list and how it notifies changes.
Plugin options and when each one fits
This table lists the main configuration keys for the four restriction plugins and a fit-or-avoid note for each. Use it to choose which plugin matches the client rule you need, then confirm exact key names and defaults in the plugin documentation for your APISIX version before you write configuration. The main takeaway is that ua-restriction cannot combine allow and deny lists from 3.5.0 onward, so design the rule set around one list style per route.
| Plugin and keys | What the keys do | Fits when | Avoid when |
|---|---|---|---|
| ip-restriction: whitelist, blacklist, message | Whitelist and blacklist take IP addresses or CIDR ranges such as a private subnet written in CIDR notation. Message sets the response body for rejected clients. | You hold a fixed set of trusted source networks or known abusive ranges that change rarely. | Clients sit behind a shared load balancer and the real address is not yet restored, since every request then looks like one source. |
| ua-restriction: allowlist, denylist, message | Allowlist and denylist match User-Agent strings. Since 3.5.0 the plugin rejects configurations that enable both lists together. | You block known scanner or bot signatures, or admit only specific approved client software on a route. | You rely on User-Agent as a security control, because clients can set any value in this header. |
| referer-restriction: whitelist, bypass_missing, message | Whitelist lists permitted Referer hostnames. Bypass_missing controls whether requests without a Referer header are allowed through. | Browser-facing routes should only be called from your own web pages and you accept some header-less traffic. | Server-to-server or mobile clients send no Referer, or you need a strong control, since the header is easily forged. |
| uri-blocker: block_rules, case_sensitive, rejected_code | Block_rules is a list of URI patterns to reject. Case sensitivity changes whether pattern matching ignores letter case. Rejected_code sets the HTTP status returned. | You want to refuse known sensitive paths such as admin consoles or probe patterns across many routes. | Your protection depends on blocking paths alone, because encoding tricks and alternate routes can bypass literal patterns. |
| Key naming and defaults | Key names, defaults and accepted value formats can change between releases, so they are not repeated here. | Before any rollout, check the schema for your exact version in the plugin documentation. | Copying examples from older blog posts or other versions into production. |
| Evaluation order | Plugin execution order determines whether a restriction runs before authentication plugins. Confirm the order for your version. | You want rejected clients to be turned away before any credential check or upstream call. | Plugin priorities are unverified, since a restriction placed after authentication still exposes the auth path. |
Why the real client IP decides whether IP restrictions work behind load balancers
An ip-restriction rule only sees the address of the connection that reaches APISIX. When a cloud load balancer, CDN or other reverse proxy sits in front of the gateway, that address belongs to the proxy, not the client. An allow list then admits everyone or no one, and a deny list blocks the proxy itself, which can take down every client behind it. Before you write any allow or deny entry, confirm which address APISIX actually sees on a test request from outside your network, and treat a single shared proxy address appearing in the logs as a sign that the client address has not been restored.
The real-ip general plugin restores the client address from a forwarded header, typically X-Forwarded-For or a header your load balancer sets, so that later plugins evaluate the true source. The plugin is only safe when it trusts a defined set of proxy addresses. Plan that list with your network team: include the load balancer or CDN ranges you control or have documented by the provider, and confirm the exact header name and the rules for reading it against your provider's documentation and your own topology. Ask the provider whether the addresses they publish can change, because a stale list breaks restrictions silently.
Accepting X-Forwarded-For from any source is the most common mistake. A client that reaches the gateway directly can send its own header with any address, and if APISIX trusts that value, the client chooses the address that your allow list and rate limits will see. Deny rules become easy to bypass and allow rules can be forged. Test this deliberately by sending a request with a spoofed header from outside your proxy tier and confirming the gateway ignores it. The full treatment of trusted proxy configuration, header sanitization and the order of plugin execution belongs to the sibling topic on trusting X-Forwarded headers and real client IPs.
Setting up and testing restriction rules in APISIX
This sequence adds IP, user agent and referer restrictions to APISIX in a controlled order, from confirming where client traffic enters to logging rejected requests. The result is a set of restriction rules that have been tested with allowed and denied requests on a non-production route before they reach production traffic.
Confirm the deployment mode and entry point
The platform engineer records which APISIX deployment mode is in use: traditional, decoupled or standalone. Client traffic in traditional mode normally arrives on port 9080, while the Admin API listens on port 9180. Identify every load balancer, CDN or proxy that sits in front of the gateway, since each one changes which address APISIX sees. Done when the team has a written diagram of the path from client to gateway and knows which nodes enforce the rules.
Verify the client address the gateway sees
Send a test request through the full path from a known source address and log the client address APISIX records for it. Compare that value with the address you expect, and check whether forwarded headers from the proxy in front of APISIX are present and trusted. If the address is the load balancer's own address, do not write restriction rules yet, because every client would appear to come from the same place. Done when a test request shows the expected client address in the gateway logs.
Add restrictions to one non-production route
Choose a single non-production route and attach the ip-restriction plugin with an allow list or deny list, then add ua-restriction or referer-restriction only if the traffic pattern needs them. Since APISIX 3.5.0, ua-restriction cannot enable an allow list and a deny list at the same time, so pick one mode per route. Confirm the exact plugin configuration and Admin API call against the APISIX version you run, using the plugin documentation. Done when the route's stored configuration shows the restriction plugins and the gateway reloads it without errors.
Test allowed and denied requests
Send controlled requests from an address on the allow list, an address outside it, a blocked user agent, and a referer that is not permitted. Include requests with the User-Agent or Referer header removed, and confirm how the configured behavior treats a missing header, since it can differ by plugin and setting. Record the status code returned for each case in a test table. Done when every case returns the outcome the rule design predicts, and any surprise is either fixed or written down as an accepted behavior.
Test the restriction from behind the proxy path
Repeat the allow and deny cases through the production proxy path, not directly against a gateway node, so the rules are tested against the address APISIX will actually see. If a denied address still gets through, check whether the real-ip plugin or forwarded header handling is restoring a different client address than intended. Done when the allow and deny results match the earlier direct tests and the client address in the logs is the one the rules are written for.
Roll out to production routes in stages
Apply the tested configuration to production routes one group at a time, starting with the lowest-risk route, and keep the previous configuration available for rollback. Watch error rates and rejected-request counts after each change, and confirm legitimate clients, including internal monitoring and partner systems, still reach the service. Done when each production route has the restriction applied, the rollout record lists the route names and times, and no unexpected rejections appear in the logs.
Set up logging of rejected requests
Configure the gateway's access logs or a logging plugin to capture rejected requests with the client address, route, status code and matched rule, while avoiding storage of sensitive request content. Confirm which logging plugin and fields your version supports by checking the plugin documentation, and send a deliberate denied request to verify that it appears in the destination system. Done when a test denial is visible in the log platform with enough fields to support an investigation, and an alert or review routine has an owner.
Security and operational risks of client-side restrictions
Restrictions based on client IP, user agent and referer are cheap to configure and easy to get wrong. The cards below cover the failure modes we see most often, the control to apply to each, and who in your organization should own it.
Spoofed or missing headers
User agent and referer values are set by the client, so an attacker can send any string or omit the header entirely. A ua-restriction or referer-restriction rule that trusts these values stops casual scrapers but not a deliberate caller. Treat these plugins as noise reduction, and keep authentication and authorization as the real gate. Owner: the API platform team, with the security architect reviewing the rule set.
Self-inflicted lockouts
An allow list built from the addresses of a load balancer or NAT gateway can block every legitimate caller the day that address changes. Before enabling ip-restriction, confirm which address APISIX actually sees for each client path, and document the source ranges that must stay on the list. Rehearse changes in a non-production environment. Owner: the platform operations team, with the network team confirming address ranges.
Drift from firewall and WAF policy
When APISIX, cloud security groups, host firewalls and a WAF each keep their own IP lists, the lists diverge and nobody knows which layer is enforcing a given block. Pick one source of truth for each network boundary, and state which layer owns which rule. Review the lists together on a fixed schedule. Owner: the security engineering team, with the network and WAF owners signing off on changes.
No rate limits on blocked traffic
A blocked request still costs the gateway parsing work and, in some setups, a log entry. A client that keeps retrying a denied address can generate large volumes of rejected traffic that hides real incidents and fills log storage. Confirm how denied requests are logged and whether a rate limit or upstream firewall rule throttles repeated denials. Owner: the platform operations team, with the SOC consuming the logs.
Rule changes without audit trails
Editing a deny list through the Admin API or a dashboard without a record makes incidents hard to reconstruct. Store restriction rules as version-controlled configuration, require a reviewed change for each edit, and forward gateway access logs to your central log platform. Confirm how your deployment mode stores and reloads configuration, since that determines where the change history lives. Owner: the platform engineering lead, with compliance reviewing evidence.
Questions teams ask before configuring APISIX client restrictions
How much effort does a client restriction rule set take to build?
The effort depends mostly on how many routes need rules, how many partner or internal address ranges must be listed, and how the traffic reaches the gateway. A single route with one office range is a small task. Many routes, each with different partner lists, behind several layers of load balancers takes much longer, because every rule has to be mapped to an owner and tested against the real client path. Change control adds time too, since each allow or deny change usually needs review and a rollback plan. Ask any provider to break the quote down by route count, address list count, and the number of change cycles included.
Can our internal team configure APISIX restrictions without outside help?
Yes, a team that already operates APISIX can write these rules, since ip-restriction, ua-restriction, and referer-restriction are configured as plugin fields on routes or services. The harder part is usually knowing which addresses and headers are real. Teams new to APISIX benefit from a review of the deployment and of how the real-ip plugin is set up, because a wrong client address makes allow lists fail in quiet ways. Whether to build in house or bring in a partner depends on available engineering time and on how many routes are involved.
What inputs does the team need to provide before the work starts?
The work goes faster when the team gathers its inputs first. Typically this includes:
- A network diagram showing where the load balancers, proxies, and gateway nodes sit
- Lists of permitted source addresses, with the owner and purpose of each partner or internal range
- The list of routes and services to protect, with a named owner for each
- The user agents and referers that legitimate clients send, based on current access logs
- Change approval contacts and the maintenance windows that apply to gateway changes
What steps does a basic restriction setup and test cycle include?
A basic cycle follows a sequence rather than a fixed duration. First, confirm the client address that the gateway sees, including behind any load balancer. Second, apply the rules to a non-production route and check allowed and denied requests with test clients. Third, run the rules in a staging environment against recorded traffic from access logs. Fourth, roll out to production one route at a time and watch error and denial rates. Finally, document each rule with its owner and review date. Ask a provider to name the steps and the environments they will test in, and whether rollback is part of the plan.
Do IP and user agent restrictions replace authentication?
No. IP, user agent, and referer checks are simple filters that run before authentication, and they can be bypassed by anyone who can spoof headers or reach an allowed network. Each of these values can be forged or shared, so they reduce noise and narrow exposure but do not prove who is calling. Protected APIs still need an authentication plugin such as key-auth, jwt-auth, or openid-connect, and authorization decisions should be made on verified identity. Treat restrictions as one layer in a defense-in-depth design.
How should we handle a version upgrade that changes plugin behavior?
Read the APISIX changelog for every version between your current release and the target before planning the upgrade. For example, since APISIX 3.5.0 the ua-restriction plugin cannot enable allowlist and denylist at the same time, so any configuration that set both needs to be changed before or during the upgrade. Test the existing rules against recorded traffic on the new version in staging, compare denial counts with the old version, and keep the previous configuration ready for rollback. Ask any provider to include a changelog review and a staging comparison in the upgrade scope.
What drives the cost of a restriction project and what is recurring?
Costs come from the setup work, which is one-time, and from ongoing rule maintenance, which recurs. The setup cost rises with route count, address list complexity, and the number of environments to test. Recurring cost comes from partner address changes, new user agents that legitimate clients adopt, and reviews after each APISIX upgrade. Subscription terms for any enterprise distribution of APISIX are a separate cost and should be confirmed with its vendor. DeployOpen does not publish prices, so ask for a quote that separates one-time setup from any retainer for ongoing rule changes and testing.
Limits to confirm in your environment
The restriction plugins are simple in concept, but their exact behavior depends on the APISIX version, the plugin fields you use and the proxy chain in front of the gateway. The cards below list the questions to settle with the vendor or with your own test results before a deny rule goes into production.
Field names and matching rules by version
Confirm the exact field names, default values and matching order for ip-restriction, ua-restriction, referer-restriction and uri-blocker in the APISIX version you deploy. Plugin schemas change between releases, so a field that worked in an older configuration may be rejected or ignored after an upgrade. Ask the vendor for the schema of your version and run each rule against a test route that proves both an allowed and a denied request.
CIDR and IPv6 entry handling
Ask how each restriction plugin parses CIDR ranges, single addresses and IPv6 entries, and whether a mixed IPv4 and IPv6 list is evaluated as you expect. Check how an IPv4-mapped IPv6 address is matched against an IPv4 range. A mistake here can silently leave a range open, so test an address from every range you intend to block.
Absent Referer and User-Agent headers
Confirm what happens when a request arrives with no Referer or User-Agent header at all, and whether the plugin allows, denies or skips the check in that case. Many legitimate API clients, health checks and server-to-server calls send neither header. Decide the behavior deliberately and test it with a request that omits each header, because an empty value and a missing header may be handled differently.
WebSocket and gRPC route behavior
Verify whether ip-restriction, ua-restriction and referer-restriction run on the upgrade request for WebSocket routes and on the initial request for gRPC routes. Confirm that a denied client is rejected before any stream opens, and check the response code and body the client receives. Protocol-specific routes are often assumed to be covered when the plugin only runs on the HTTP phase.
Interaction with real-ip under your proxy chain
Restrictions that match on the client address depend on what the gateway believes that address is. Confirm how the real-ip plugin is configured for your load balancers, which proxy addresses are trusted, and whether a client-supplied forwarding header can change the address the restriction sees. Test from outside your proxy tier, since a test from inside the same network can hide the problem.
Distribution and vendor differences
If you run API7 Enterprise or another distribution, ask the vendor whether any restriction plugin behaves differently from upstream Apache APISIX, including default values, supported fields and error responses. Ask which plugin versions the vendor tests and how it reports changes. Record the answers in your change records, because an upgrade of the distribution can change behavior even when your route configuration stays the same.
What DeployOpen needs from your team to scope these restrictions
The scope of an IP, user agent and referer restriction project depends on inputs that only your team can provide, so the first request is an inventory of traffic entry points. List every listener that reaches APISIX, including the load balancers, CDN edges and partner gateways that sit in front of it, and state which ones terminate TLS and which pass the connection through. This determines where the client address is first visible and which proxy hops must be trusted when the ip-restriction plugin evaluates a request. Ask for the route list too, with the routes to protect ranked by business impact, because allow and deny rules belong on specific routes rather than on the whole gateway.
Next, collect the partner and internal address ranges with a named owner for each range. Each allow list entry should trace to a contract, a team or a system, and the owner should confirm whether the address is a fixed egress IP, a shared NAT pool or a range that changes. Ask for the expected user agent strings of approved clients and the referring domains that legitimate browsers send from. Confirm the change process as well: who approves a new entry, how quickly a blocked partner can be unblocked during an incident, and whether changes go through your existing ticketing or configuration review. These answers decide how rules are versioned and tested before they reach production.
Finally, settle where the evidence goes. Name the logging destination that will receive blocked and allowed request records, and confirm who reads those logs and how long they are kept under your retention policy. The agreed deliverables are tested rules and documentation covering the rule design, test cases, rollback steps and operating procedure, and they are fixed in writing before work starts. Ongoing support for rule changes, reviews and periodic testing is available as a retainer, which suits teams whose partner list changes often. Ask for a written scope that names each input above, its owner and the date it is due.
How DeployOpen scopes, delivers and supports APISIX restrictions
DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside the client's own infrastructure. For Apache APISIX IP, user agent and referer restrictions, we start from a written list of which clients must reach which routes, then build and test the restriction rules in your environment before anything is handed over.
How we scope
- Engagements are fixed-scope, with the restriction rules, routes and environments agreed in writing before work starts.
- We inventory the routes that need ip-restriction, ua-restriction and referer-restriction, and note which ones sit behind a load balancer.
- The scope confirms how the real client IP reaches APISIX, including the trusted proxy path and the real-ip settings.
How we build
- We configure allow and deny lists in ip-restriction and check them against the proxy chain your traffic actually uses.
- We set ua-restriction to one list type per route, since APISIX 3.5.0 does not allow allowlist and denylist together.
- We test blocked and permitted requests for each route, including spoofed forwarding headers, before rollout.
How we hand over
- You receive the route and plugin configuration as code, with the list ownership and change process documented.
- The handover includes a test script covering allowed clients, blocked clients and header-spoofing attempts.
- Runbooks explain how to add or remove an address, how to review blocked requests and how to roll back a rule.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers, scoped separately from the build.
- Upgrade reviews check restriction behavior against the APISIX changelog for each version you adopt.
- Retesting after load balancer, DNS or network changes confirms that the real client IP still reaches the gateway correctly.
