geoip-filtering.md

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

GeoIP Filtering

{% hint style="warning" %} This feature requires Gravitee's Enterprise Edition. {% endhint %}

Overview

{% hint style="warning" %} To use this policy, you must first install the plugin gravitee-service-geoip. This plugin loads the geoip databases in memory, so you need to adjust the JVM Heap settings of your APIM Gateways accordingly. {% endhint %}

You can use the geoip-filtering policy to control access to your API by filtering IP addresses. You can allow IPs by country or distance.

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

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

• Examples
• Configuration
• Compatibility Matrix
• Errors

Examples

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

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

"geoip-filtering": {
  "failOnUnknown": true,
  "whitelistRules": [
    {
        "type": "COUNTRY",
        "country": "FR"
    },
   {
       "type": "DISTANCE",
       "distance": "50000"
   }
  ],
}

{% endtab %} {% endtabs %}

Configuration

Sample policy configuration:

{% code title="Sample Configuration" %}

{
  "name": "Custom name",
  "description": "Filters IP addresses",
  "policy": "geoip-filtering",
  "configuration": {
    "failOnUnknown": true,
    "whitelistRules": [
      {
          "type": "COUNTRY",
          "country": "FR"
      },
     {
         "type": "DISTANCE",
         "distance": "50000"
     }
    ],
  }
}

{% endcode %}

Phases

The phases checked below are supported by the geoip-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 geoip-filtering policy can be configured with the following options:

Property	Required	Description	Type	Default
failOnUnknown	true	If set to true, each unknown IP is rejected	boolean	true
whitelistRules	false	A list of allowed rules	Whitelist Rule	empty

Whitelist rule

The geoip-filtering policy has the following whitelist rules:

Property	Required	Description	Type	Default
Type	true	Type of rule COUNTRY or DISTANCE	enum	COUNTRY
Country	false	Country (must be defined in case type is set to COUNTRY)	enum	A1
Latitude	false	Latitude (must be defined in case type is set to DISTANCE)	number	0.0
Longitude	false	Longitude (must be defined in case type is set to DISTANCE)	number	0.0
Distance	false	Max distance, in meters (must be defined in case type is set to DISTANCE)	integer	10000

Compatibility matrix

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

Plugin Version	Supported APIM versions
1.x	Up to 3.20.x
2.x+	4.0.x+

Errors

HTTP status code	Error template key
403	You’re not allowed to access this resource