ip-restriction

Description

The ip-restriction Plugin supports restricting access to upstream resources by IP addresses, through either configuring a whitelist or blacklist of IP addresses. Restricting IP to resources helps prevent unauthorized access and harden API security.

Attributes

Name	Type	Required	Default	Valid values	Description
whitelist	array[string]	False			List of IPs or CIDR ranges to whitelist.
blacklist	array[string]	False			List of IPs or CIDR ranges to blacklist.
message	string	False	"Your IP address is not allowed"	[1, 1024]	Message returned when the IP address is not allowed access.
response_code	integer	False	403	[403, 404]	HTTP response code returned when the IP address is not allowed access.

note

At least one of the whitelist or blacklist should be configured, but they cannot be configured at the same time.

Examples

The examples below demonstrate how you can configure the ip-restriction Plugin for different scenarios.

note

You can fetch the admin_key from config.yaml and save to an environment variable with the following command:

admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')

Restrict Access by Whitelisting

The following example demonstrates how you can whitelist a list of IP addresses that should have access to the upstream resource and customize the error message for access denial.

Create a Route with the ip-restriction Plugin to whitelist a range of IPs and customize the error message when the access is denied:

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${admin_key}" \
  -d '{
    "id": "ip-restriction-route",
    "uri": "/anything",
    "plugins": {
      "ip-restriction": {
        "whitelist": [
          "192.168.0.1/24"
        ],
        "message": "Access denied"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

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":"Access denied"}

Restrict Access Using Modified IP

The following example demonstrates how you can modify the IP used for IP restriction, using the real-ip Plugin. This is particularly useful if APISIX is behind a reverse proxy and the real client IP is not available to APISIX.

Create a Route with the ip-restriction Plugin to whitelist a specific IP address and obtain client IP address from the URL parameter realip:

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${admin_key}" \
  -d '{
    "id": "ip-restriction-route",
    "uri": "/anything",
    "plugins": {
      "ip-restriction": {
        "whitelist": [
          "192.168.1.241"
        ]
      },
      "real-ip": {
        "source": "arg_realip"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
      "httpbin.org:80": 1
      }
    }
  }'

Send a request to the Route:

curl -i "http://127.0.0.1:9080/anything?realip=192.168.1.241"

You should receive an HTTP/1.1 200 OK response.

Send another request with a different IP address:

curl -i "http://127.0.0.1:9080/anything?realip=192.168.10.24"

You should receive an HTTP/1.1 403 Forbidden response.