# 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[​](#restrict-access-to-upstream-resource-by-ip "Direct link to 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[​](#restrict-by-the-original-remote-address "Direct link to 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](https://docs.api7.ai/hub/ip-restriction.md) for more information.

### Restrict Behind a Trusted Reverse Proxy[​](#restrict-behind-a-trusted-reverse-proxy "Direct link to 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`](https://docs.api7.ai/hub/real-ip.md) plugin to accept a client address only from known proxy addresses, then apply [`ip-restriction`](https://docs.api7.ai/hub/ip-restriction.md) 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[​](#restrict-admin-api-access-by-ip "Direct link to Restrict Admin API Access by IP")

By restricting [Admin API](https://docs.api7.ai/apisix/reference/admin-api.md) 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](https://docs.api7.ai/apisix/production/security/admin-api-key.md#key-requirement-and-permissions) 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](https://docs.api7.ai/apisix/reference/apisix-cli.md#apisix-reload) for configuration file changes to take effect.
