Geofence Match

The geofence-match controller matches the client location (latitude/longitude from GeoIP) against geographic polygons defined in a GeoJSON file.

Prerequisites

This controller requires the maxmind-geoip analysis controller to provide location data:

analysisControllers:
  - name: geoip
    type: maxmind-geoip
    settings:
      databasePath: GeoLite2-City.mmdb

Configuration

matchControllers:
  - name: europe
    type: geofence-match
    settings:
      featuresFile: config/europe.geojson

Settings

• featuresFile (required): Path to a GeoJSON file containing features definitions.

Features Files Validation

To validate that your features files are compliant with validation rules you can use the validate-geojson CLI command.

GeoJSON Format

The controller uses GeoJSON (RFC 7946), the industry standard for geospatial data. Each feature must have:

• A name property (string) for identification
• A geometry of type Polygon or MultiPolygon with valid GPS coordinates

Example GeoJSON File

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": { "name": "europe-region" },
      "geometry": {
        "type": "Polygon",
        "coordinates": [[
          [-10.0, 35.0],
          [40.0, 35.0],
          [40.0, 70.0],
          [-10.0, 70.0],
          [-10.0, 35.0]
        ]]
      }
    },
    {
      "type": "Feature",
      "properties": { "name": "us-east-coast" },
      "geometry": {
        "type": "Polygon",
        "coordinates": [[
          [-85.0, 25.0],
          [-65.0, 25.0],
          [-65.0, 45.0],
          [-85.0, 45.0],
          [-85.0, 25.0]
        ]]
      }
    }
  ]
}

Creating GeoJSON Files

You can create GeoJSON files using:

• geojson.io - Free online tool for drawing polygons on a map and exporting
• Google Earth - Export shapes as GeoJSON
• QGIS - Professional GIS software with GeoJSON export
• Mapbox, Leaflet - Web mapping libraries with GeoJSON support

Validation Rules

The controller validates that:

• Polygons are closed (first and last coordinates match)
• Coordinates are within valid GPS bounds (latitude: -90 to 90, longitude: -180 to 180)
• Each polygon has at least 4 points (including closing point)
• Feature names are unique

Upstream Headers

When a request is processed, the controller adds headers to upstream requests:

• X-Geofence-{controller-name}: true or false indicating if the location matched any feature
• X-Geofence-{controller-name}-Features: Comma-separated list of matched feature names in ascending order (only when matched)

Policy Patterns

• Allow only from specific regions: authorizationPolicy: "europe"
• Block specific regions: authorizationPolicy: "!blocked-regions"
• Combine with other controllers: authorizationPolicy: "europe && !blocked-asn"
• Require region AND IP allowlist: authorizationPolicy: "europe && corporate-network"

Use Cases

• Geographic restrictions: Restrict access to users from specific countries or regions
• Compliance: Enforce data residency requirements
• Fraud prevention: Block or flag requests from unexpected locations