ip-filtering.md

description
This page provides the technical details of the IP Filtering policy

IP filtering

Overview

You can use the ip-filtering policy to control access to your API by filtering IP addresses. You can allow or deny a specific IP address or range of IP addresses with CIDR.

Whitelist mode excludes all IP addresses except the addresses included in the whitelist. Blacklist mode allows all IP addresses except the addresses included in the blacklist.

The blacklist takes precedence, so if an IP address is included in both lists, the policy rejects the request.

You can specify a host to be resolved and checked against the remote IP.

Functional and implementation information for the ip-filtering policy is organized into the following sections:

• Examples
• Configuration
• Compatibility Matrix
• Errors
• Changelogs

Examples

{% hint style="warning" %} This policy can be applied to v2 APIs and v4 proxy APIs. It cannot be applied to v4 message APIs. {% endhint %}

{% tabs %} {% tab title="Proxy API example" %} Sample policy configuration:

"ip-filtering": {
  "matchAllFromXForwardedFor": true,
  "whitelistIps": [
    "10.0.0.1",
    "10.0.0.2/10",
    "gravitee.io"
  ],
  "blacklistIps": [
    null
  ]
}

{% endtab %} {% endtabs %}

Configuration

Phases

The phases checked below are supported by the ip-filtering policy:

v2 Phases	Compatible?	v4 Phases	Compatible?
onRequest	true	onRequest	true
onResponse	false	onResponse	false
onRequestContent	false	onMessageRequest	false
onResponseContent	false	onMessageResponse	false

Options

The ip-filtering policy can be configured with the following options:

Property	Required	Description	Type	Default
matchAllFromXForwardedFor	false	If set to true, each IP from the X-Forwarded-For header parameter is parsed	boolean	false
whitelistIps	false	A list of allowed IPs with or without CIDR notation (host is allowed)	string list	empty
blacklistIps	false	A list of denied IPs with or without CIDR notation (host is allowed)	string list	empty

Compatibility matrix

The following is the compatibility matrix for APIM and the ip-filtering policy:

Plugin Version	Supported APIM versions
1.x	All

Errors

HTTP status code	Message
403	Your IP (0.0.0.0) or one of the proxies your request passed through is not allowed to reach this resource

Changelogs

{% @github-files/github-code-block url="https://github.com/gravitee-io/gravitee-policy-ipfiltering/blob/master/CHANGELOG.md" %}