API Gateway + IP Geolocation Integration: Architecture Patterns for 2026

// Kong Gateway Plugin: IP Geolocation Integration
-- kong/plugins/ip-geolocation/handler.lua

local kong = kong
local http = require("resty.http")
local cjson = require("cjson")

-- Cache configuration with TTL
local cache_ttl = 3600 -- 1 hour for geolocation data
local ip_info_api_base = "https://api.ip-info.app"
local api_key = os.getenv("IP_INFO_API_KEY")

-- Initialize plugin
local IPGeolocationHandler = {
  VERSION = "1.0.0",
  PRIORITY = 1000,
}

-- Extract client IP with proxy support
function get_client_ip()
  -- Check for X-Forwarded-For header (proxy/CDN)
  local xff = kong.request.get_header("X-Forwarded-For")
  if xff then
    -- Take the first IP (original client)
    return ngx.re.match(xff, [[^([0-9.]+)]])[1]
  end

  -- Check for X-Real-IP header
  local xri = kong.request.get_header("X-Real-IP")
  if xri then
    return xri
  end

  -- Fall back to direct connection IP
  return kong.client.get_ip()
end

-- Cache key generator
function cache_key(ip_address)
  return "ip-geo:" .. ip_address
end

-- Fetch geolocation data with caching
function fetch_geolocation(ip)
  local cache = kong.cache
  local key = cache_key(ip)

  -- Try cache first
  local cached_data, err = cache:get(key)
  if cached_data then
    kong.log.debug("Cache hit for IP: " .. ip)
    return cached_data
  end

  -- Cache miss - fetch from API
  kong.log.debug("Cache miss for IP: " .. ip .. ", fetching from API")

  local httpc = http.new()
  httpc:set_timeout(5000) -- 5 second timeout

  local res, err = httpc:request_uri(ip_info_api_base .. "/v1/geolocate", {
    method = "GET",
    query = {
      ip = ip,
      fields = "country,region,city,postcode,latitude,longitude,is_proxy,is_vpn,is_tor,fraud_score"
    },
    headers = {
      ["X-API-Key"] = api_key,
      ["Accept"] = "application/json",
    },
    ssl_verify = true
  })

  if not res then
    kong.log.err("IP geolocation API request failed: " .. tostring(err))
    return nil, "API request failed"
  end

  if res.status ~= 200 then
    kong.log.warn("IP geolocation API returned status: " .. res.status)
    return nil, "API error: " .. res.status
  end

  local geo_data = cjson.decode(res.body)

  -- Cache the result
  cache:set(key, geo_data, cache_ttl)

  return geo_data
end

-- Evaluate security rules
function evaluate_security_rules(geo_data, config)
  local violations = {}

  -- Check proxy/VPN usage
  if config.block_proxy and geo_data.is_proxy then
    table.insert(violations, "proxy_detected")
  end

  if config.block_vpn and geo_data.is_vpn then
    table.insert(violations, "vpn_detected")
  end

  if config.block_tor and geo_data.is_tor then
    table.insert(violations, "tor_detected")
  end

  -- Check fraud score threshold
  if config.fraud_score_threshold and
     geo_data.fraud_score and
     geo_data.fraud_score >= config.fraud_score_threshold then
    table.insert(violations, "high_fraud_score")
  end

  -- Check country restrictions
  if config.allowed_countries then
    local country_allowed = false
    for _, country in ipairs(config.allowed_countries) do
      if country == geo_data.country then
        country_allowed = true
        break
      end
    end
    if not country_allowed then
      table.insert(violations, "country_not_allowed")
    end
  end

  if config.blocked_countries then
    for _, country in ipairs(config.blocked_countries) do
      if country == geo_data.country then
        table.insert(violations, "country_blocked")
        break
      end
    end
  end

  return violations
end

-- Main request handler
function IPGeolocationHandler:access(config)
  -- Skip geolocation for health checks and internal paths
  if config.skip_paths then
    local path = kong.request.get_path()
    for _, skip_path in ipairs(config.skip_paths) do
      if string.match(path, skip_path) then
        kong.log.debug("Skipping geolocation for path: " .. path)
        return
      end
    end
  end

  -- Extract client IP
  local client_ip = get_client_ip()
  kong.log.debug("Processing geolocation for IP: " .. client_ip)

  -- Fetch geolocation data
  local geo_data, err = fetch_geolocation(client_ip)
  if not geo_data then
    kong.log.warn("Failed to fetch geolocation for IP: " .. client_ip .. ", error: " .. tostring(err))

    -- Fail-open or fail-closed based on configuration
    if config.fail_open then
      kong.log.info("Fail-open mode: allowing request")
      return
    else
      return kong.response.exit(503, {
        message = "Location verification temporarily unavailable",
      })
    end
  end

  -- Evaluate security rules
  local violations = evaluate_security_rules(geo_data, config)

  if #violations > 0 then
    kong.log.warn("Security violations detected for IP " .. client_ip .. ": " .. table.concat(violations, ", "))

    -- Set headers for debugging/logging
    kong.response.set_header("X-Geo-Blocked", "true")
    kong.response.set_header("X-Geo-Violations", table.concat(violations, ", "))

    -- Return appropriate error response
    return kong.response.exit(403, {
      error = "Access denied",
      reason = "Geolocation security check failed",
      violations = violations,
    })
  end

  -- Request passed security checks
  -- Add geolocation headers to upstream request
  kong.service.request.set_header("X-Geo-Country", geo_data.country or "unknown")
  kong.service.request.set_header("X-Geo-Region", geo_data.region or "unknown")
  kong.service.request.set_header("X-Geo-City", geo_data.city or "unknown")
  kong.service.request.set_header("X-Geo-Lat", tostring(geo_data.latitude or "0"))
  kong.service.request.set_header("X-Geo-Lon", tostring(geo_data.longitude or "0"))
  kong.service.request.set_header("X-Geo-FraudScore", tostring(geo_data.fraud_score or "0"))

  kong.log.debug("Geolocation check passed for IP: " .. client_ip)
end

-- Plugin schema for Kong configuration
return IPGeolocationHandler