IP Restriction
IP restriction is a commonly used technique for access control. By limiting resources to specific IP addresses, organizations can adhere to the principle of least privilege, prevent unauthorized access, and stay compliant with security requirements.
APISIX supports IP restrictions in the following ways:
- Restricting access to upstream resources by IPs
- Restricting access to Admin API by IPs
This guide will show you how to configure APISIX for these practices.
Restrict Access to Upstream Resource by IP
In this section, you will learn how to control client access to upstream resources by IPs, using the ip-restriction plugin. You will also learn how to expose the real client IP to APISIX when APISIX is behind a reverse proxy, such that the ip-restriction plugin can evaluate access based on the real client IP.
Restrict by the Original Remote Address
Create a route with the ip-restriction plugin and configure the IP whitelist:
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"id": "ip-restriction-route",
"uri": "/anything",
"plugins": {
"ip-restriction": {
"whitelist": [
"192.168.0.1/24"
]
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"httpbin.org:80": 1
}
}
}'
❶ Configure a list of IP addresses that are allowed to access the upstream resource. The configuration supports both IPv4 and IPv6 formats.
Send a request to the route:
curl -i "http://127.0.0.1:9080/anything"
If your IP is allowed, you should receive an HTTP/1.1 200 OK response. If not, you should receive an HTTP/1.1 403 Forbidden response with the following error message:
{"message":"Your IP address is not allowed"}
You can also configure the ip-restriction plugin with a list of IP addresses to blacklist. However, note that the whitelist and the blacklist cannot be configured simultaneously. See the plugin doc for more information.
Restrict Behind a Trusted Reverse Proxy
When APISIX is behind a reverse proxy, the connection address is the proxy address rather than the original client address. Use the real-ip plugin to accept a client address only from known proxy addresses, then apply ip-restriction to the resulting address. Configure the proxy to overwrite the forwarding header, and prevent clients from bypassing the proxy to reach the gateway listener.
The following example assumes that the trusted proxy uses 192.0.2.10 and overwrites X-Forwarded-For with the original client address. Replace the documentation addresses with your proxy and allowed client addresses:
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"id": "ip-restriction-route",
"uri": "/anything",
"plugins": {
"ip-restriction": {
"whitelist": [
"198.51.100.20"
]
},
"real-ip": {
"source": "http_x_forwarded_for",
"trusted_addresses": ["192.0.2.10"]
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"httpbin.org:80": 1
}
}
}'
❶ Allow the original client address that should access the upstream resource.
❷ Read the original client address from the X-Forwarded-For header that the proxy overwrites.
❸ Trust replacement addresses only when the connection to APISIX comes from the configured proxy address.
Send requests from an allowed client and a disallowed client through the proxy. The allowed client should receive HTTP/1.1 200 OK, while the disallowed client should receive HTTP/1.1 403 Forbidden.
If direct access to the gateway listener is available during validation, verify that an untrusted client cannot grant itself access by forging the forwarding header:
APISIX_DIRECT_ADDRESS="<gateway-direct-address>"
curl -i "http://${APISIX_DIRECT_ADDRESS}:9080/anything" \
-H "X-Forwarded-For: 198.51.100.20"
The request should receive HTTP/1.1 403 Forbidden because its connection address is not in trusted_addresses. In production, enforce the same boundary with network policy or firewall rules so clients cannot connect directly.
Restrict Admin API Access by IP
By restricting Admin API access to authorized personnel, organizations minimize the attack surface and ensure that only individuals with the necessary expertise and responsibilities can make critical changes. This helps maintain a higher level of control and overall security across the infrastructure.
To restrict IP addresses that should have administrative view and write access to APISIX Admin API, update the configuration file config.yaml with the following:
deployment:
admin:
admin_key_required: true
allow_admin:
- 127.0.0.0/24
# - "::/64"
❶ Configure a list of IP addresses that are allowed to access Admin API. The configuration supports both IPv4 and IPv6 formats.
If allow_admin is not configured, APISIX uses the default allowlist 127.0.0.0/24. Requests from other addresses are rejected. Configure an explicit allowlist when trusted administrators connect from another network, and do not use 0.0.0.0/0 in production.
Reload APISIX for configuration file changes to take effect.