Cómo bloquear o permitir países por IP en Cloudflare Workers y Nginx

Armá una allowlist o blocklist de países en el edge y en el origin: request.cf.country en un Worker, o auth_request de Nginx hacia un sidecar chico con caché.

Registrarse Leer la documentación

Free: 1.000 req/mes · HTTPS · uso personal y no comercial

Cuándo tiene sentido una lista de países

Licencias, disponibilidad del producto y algunas reglas de compliance se deciden a nivel país. Un filtro de país es grueso: mira el país de la IP, no a la persona. Detrás de una red VPN conocida, un exit de Tor o un relay de privacidad, el país que ves es el del egress, no el del usuario. location.country_code también puede ser null, así que todos los ejemplos de abajo fallan abiertos cuando el país no se conoce o la consulta falla.

Usá el código ISO 3166-1 alpha-2 (US, CA, …), no la ciudad. La ciudad es una estimación de mejor esfuerzo; accuracy_radius_km y confidence te dicen cuándo no confiar en ella. Una allowlist de países no necesita la ciudad.

Cloudflare Workers: empezá con request.cf.country

Para el visitante actual, Workers ya te da un código de país en request.cf.country, gratis y sin una consulta extra. Si solo necesitás “permitir Estados Unidos y Canadá, si no 403”, usalo. Es el default correcto y no gasta cuota de la API.

request.cf allowlist
// src/index.js — visitor country from request.cf (no API call)
const ALLOW = new Set(["US", "CA"]);

export default {
  async fetch(request) {
    const country = request.cf?.country; // ISO 3166-1 alpha-2, or undefined
    // Fail open when the country is missing.
    if (country && !ALLOW.has(country)) {
      return new Response("This service isn’t available in your country.", {
        status: 403,
      });
    }
    return fetch(request);
  },
};

Usá GET /v0/ip/{ip} cuando Nginx en el origin tiene que aplicar la misma política (ahí no hay request.cf), cuando querés una sola fuente de verdad para Workers y el origin, o cuando clasificás IPs que no son las del visitante actual (logs, webhooks). El país forma parte de la geolocalización, que está incluida en el plan Free (1.000 requests por mes calendario UTC, 1 request/segundo, uso personal y no comercial). Cacheá por IP o te vas a comer la cuota con visitantes repetidos. El uso comercial requiere un plan pago; los tiers pagos son Starter USD 9 / 100 mil / 10 req/s, Growth USD 29 / 500 mil / 25 req/s y Scale USD 79 / 2M / 50 req/s, sin cargos por excedentes.

Guardá la key con npx wrangler secret put NDL_API_KEY, no en wrangler.toml. La IP del visitante viene en CF-Connecting-IP. Cacheá el JSON por IP en la Cache API, usá un timeout corto y volvé a request.cf.country (o permití) si la llamada falla:

Terminal
$ npx wrangler secret put NDL_API_KEY
src/index.js
// src/index.js
const API = "https://api.networkdatalabs.com/v0/ip/";
const TTL = 6 * 60 * 60; // seconds
const ALLOW = new Set(["US", "CA"]);

async function lookup(ip, env, ctx) {
  const cache = caches.default;
  const cacheKey = new Request(`https://ndl-cache.internal/ip/${ip}`);
  const hit = await cache.match(cacheKey);
  if (hit) return hit.json();

  const res = await fetch(API + encodeURIComponent(ip), {
    headers: { Authorization: `Bearer ${env.NDL_API_KEY}` },
    signal: AbortSignal.timeout(500),
  });
  if (!res.ok) throw new Error(`lookup ${res.status}`);
  const data = await res.json();

  ctx.waitUntil(cache.put(cacheKey, new Response(JSON.stringify(data), {
    headers: { "Cache-Control": `max-age=${TTL}`, "Content-Type": "application/json" },
  })));
  return data;
}

function decide(country) {
  // No country → fail open. Only block a known country outside the allowlist.
  if (!country) return true;
  return ALLOW.has(country);
}

export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url);
    if (url.pathname === "/health" || url.pathname.startsWith("/assets/")) {
      return fetch(request);
    }

    let country = request.cf?.country ?? null;
    const ip = request.headers.get("CF-Connecting-IP");
    try {
      if (ip) {
        const data = await lookup(ip, env, ctx);
        country = data.location?.country_code ?? country;
      }
    } catch {
      // fail open: keep request.cf, or allow if both are missing
    }

    if (!decide(country)) {
      return new Response("This service isn’t available in your country.", {
        status: 403,
      });
    }
    return fetch(request);
  },
};

La Cache API es por data center y no cuesta extra. Si querés una caché compartida entre locaciones, guardá el JSON en Workers KV con expirationTtl. Para ir más allá del país y usar traits (is_hosting, is_tor, redes VPN conocidas), ver Cloudflare Workers: más allá de request.cf.

Nginx: auth_request y un sidecar chico

Nginx no tiene el país del visitante por sí solo, salvo que agregues un módulo de geo o una base local. Un sidecar chico deja la política en un solo lugar: Nginx le pregunta en cada request con auth_request, y el sidecar consulta GET /v0/ip/{ip}, cachea el resultado y responde 200 (permitir) o 403 (denegar). El sidecar también tiene que fallar abierto: si la API falla, devuelve 200; si el sidecar mismo está caído, Nginx convierte 502/503/504 en 200.

Pasá una sola IP de cliente en X-Client-IP. Si Nginx está en el borde, es $remote_addr. Si Cloudflare es el único proxy delante de Nginx, usá $http_cf_connecting_ip. No parsees X-Forwarded-For crudo: el cliente puede poner cualquier dirección ahí.

sidecar.js
// sidecar.js — Node 18+, listen on 127.0.0.1:8091
const http = require("http");

const API = "https://api.networkdatalabs.com/v0/ip/";
const KEY = process.env.NDL_API_KEY;
const ALLOW = new Set((process.env.ALLOWED_COUNTRIES || "US,CA").split(","));
const cache = new Map();
const TTL_MS = 6 * 60 * 60 * 1000;

function normalize(ip) {
  return ip && ip.startsWith("::ffff:") ? ip.slice(7) : ip;
}

async function lookup(ip) {
  const hit = cache.get(ip);
  if (hit && hit.exp > Date.now()) return hit.data;
  const res = await fetch(API + encodeURIComponent(ip), {
    headers: { Authorization: `Bearer ${KEY}` },
    signal: AbortSignal.timeout(800),
  });
  if (!res.ok) throw new Error(`lookup ${res.status}`);
  const data = await res.json();
  cache.set(ip, { data, exp: Date.now() + TTL_MS });
  return data;
}

http.createServer(async (req, res) => {
  if (req.url !== "/check") {
    res.writeHead(404);
    res.end();
    return;
  }
  const ip = normalize(req.headers["x-client-ip"]);
  try {
    const data = await lookup(ip);
    const country = data.location?.country_code ?? "";
    const allow = !country || ALLOW.has(country);  // fail open if unknown
    res.writeHead(allow ? 200 : 403, {
      "X-IP-Country": country,
      "Cache-Control": "no-store",
    });
  } catch {
    res.writeHead(200, { "X-IP-Country": "" });    // fail open
  }
  res.end();
}).listen(8091, "127.0.0.1");
nginx.conf (excerpt)
# Requires the auth_request module (included in most nginx packages).
# Sidecar listens on 127.0.0.1:8091 (see sidecar.js).

upstream geo_sidecar {
    server 127.0.0.1:8091;
    keepalive 8;
}

server {
    listen 80;
    server_name app.example.com;

    location = /_country_gate {
        internal;
        proxy_pass http://geo_sidecar/check;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_pass_request_body off;
        proxy_set_header Content-Length "";
        proxy_set_header X-Client-IP $remote_addr;
        # If Cloudflare is the only proxy in front of Nginx, use this instead:
        # proxy_set_header X-Client-IP $http_cf_connecting_ip;
        proxy_connect_timeout 200ms;
        proxy_read_timeout 800ms;
        proxy_intercept_errors on;
        error_page 502 503 504 =200 /_country_allow;
    }

    location = /_country_allow {
        internal;
        return 200;
    }

    location / {
        auth_request /_country_gate;
        auth_request_set $ip_country $upstream_http_x_ip_country;
        error_page 403 = @country_denied;
        proxy_set_header X-IP-Country $ip_country;
        proxy_pass http://127.0.0.1:3000;
    }

    location @country_denied {
        default_type text/plain;
        return 403 "This service isn't available in your country.\n";
    }
}

auth_request_set copia X-IP-Country del sidecar a $ip_country, para que el origin siga viendo el país después de un allow. Si podés, salteá el gate en health checks y assets estáticos, así esas rutas no gastan una consulta (la caché en proceso ya cubre IPs repetidas).

Fixtures de prueba

  • 8.8.8.8 — un resolver DNS público de EE. UU. La API devuelve location.country_code: "US" (y is_anycast / is_hosting). En una allowlist de US,CA tiene que pasar.
  • 203.0.113.10 — una dirección de documentación (TEST-NET). Vuelve con traits.is_bogon y sin país, así que los ejemplos de arriba la permiten. Sirve para chequear el fail-open, no como si fuera un usuario real.

Caché, timeouts y cuota

  • Cacheá por IP durante unas horas en el sidecar y en el Worker.
  • Mantené timeouts cortos (500–800 ms) y siempre fail-open si hay error.
  • El país está en el plan Free, pero 1.000 requests/mes no alcanzan para consultar cada request sin una caché.
  • Para backfill de logs, POST /v0/bulk (planes pagos) acepta hasta 100 IPs por request; cada IP cuenta para la cuota mensual.

Preguntas frecuentes

¿Uso request.cf o la API en un Worker?

Usá request.cf.country cuando solo necesitás el país del visitante actual en el edge. Usá la API cuando Nginx tiene que aplicar la misma regla, cuando querés un solo dataset para edge y origin, o cuando consultás IPs que no son las de este request. Las dos fuentes a veces pueden no coincidir; elegí una para el gate y quedate con esa.

¿Qué pasa si el usuario está en una VPN?

Ves el país del egress. is_vpn (redes VPN conocidas), is_tor e is_relay (relay de privacidad) son flags de planes pagos en la misma respuesta, si querés tratar ese tráfico distinto. No hacen falta para un filtro básico de país. Más en la API de detección de VPN.

¿Puedo bloquear por ciudad o región?

No lo hagas para un gate duro. Usá solo country_code. La ciudad o la región sirven cuando confidence es high o medium y la decisión es blanda (defaults, idioma), no un 403.

¿Qué pasa en desarrollo local?

127.0.0.1 y ::1 son direcciones bogon, sin país, así que los snippets las permiten. Apuntá el sidecar a una IP pública de EE. UU. como 8.8.8.8 cuando quieras ver un allow, y achicá la allowlist un rato cuando quieras ver un 403.

Relacionado

Registrarse Leer la documentación