GeoIP und geografische Zugriffskontrolle

QuoteNode enthält eine optionale geografische Zugriffskontrolle und länderbezogenes Tracking auf Basis einer lokalen GeoIP-Länderdatenbank (standardmäßig keyless DB-IP Country Lite oder MaxMind GeoLite2).

Zwei Verwendungen von GeoIP

1. Anwendungs-Zugriffskontrolle

Wenn aktiviert, kann der GeoIP-Filter den Anwendungszugriff auf bestimmte Länder beschränken. Anfragen aus nicht erlaubten Ländern erhalten HTTP 403 (Forbidden).

Das ist nützlich für Organisationen, die:

• nur in bestimmten Jurisdiktionen tätig sind,
• die Angriffsfläche für automatisierte Angriffe aus bestimmten Regionen verringern möchten,
• Vorgaben zur Datenresidenz oder Zugriffskontrolle einhalten müssen.

2. Tracking von Angebotsinteraktionen

Wenn ein Kunde einen öffentlichen Angebotslink öffnet, erfasst das System den Ländercode des Kunden (ISO 3166-1 alpha-2) zusammen mit dem Interaktionsereignis. Das liefert geografischen Kontext für die Angebotsanalyse:

• „Ihr Angebot wurde aus Deutschland geöffnet“ — bestätigt internationale Reichweite,
• „Mehrere Öffnungen aus verschiedenen Ländern“ — kann darauf hindeuten, dass das Angebot weitergeleitet wurde.

Funktionsweise

Datenbank

Die GeoIP-Auflösung verwendet eine lokale Länderdatenbank im MaxMind-DB-Format (.mmdb) — keine externe API. Alle Abfragen erfolgen im Arbeitsspeicher ohne Netzwerkaufrufe.

Standardmäßig ist das die keyless DB-IP Country Lite (Lizenz CC-BY-4.0, kein Konto nötig). Der Container lädt sie beim Start automatisch herunter (und nach einem Tagesplan), wenn sie fehlt oder veraltet ist — unabhängig von GEOIP_ENABLED, gesteuert durch GEOIP_AUTO_UPDATE (Standard true). Die Datenbank kann also bereit sein, während die Länder-Durchsetzung aus ist. Kein manuelles Herunterladen oder Einbinden der Datei. Um stattdessen MaxMind GeoLite2 zu verwenden, setzen Sie MAXMIND_ACCOUNT_ID / MAXMIND_LICENSE_KEY (ein kostenloses MaxMind-Konto); es ist dasselbe .mmdb-Format. Die Datei lässt sich auch manuell mit scripts/update-geoip.sh befüllen.

IP-Erkennung

Die Client-IP wird vollständig von der Anwendung aufgelöst — sie wird nicht blind aus Request-Headern übernommen. Ein gefälschter X-Forwarded-For-, X-Real-IP- oder CF-Connecting-IP-Header von einem direkten Client kann die Länderprüfung niemals täuschen.

1. Die Anwendung nimmt den Transport-Peer (die Adresse, die die Verbindung tatsächlich geöffnet hat).
2. Ist dieser Peer nicht intern, werden alle Weiterleitungs-Header ignoriert und der Peer wird direkt verwendet. Ein Peer ist intern, wenn er ein explizit vertrauenswürdiger Proxy oder eine beliebige nicht global routbare Adresse ist (privat/RFC 1918, Loopback, Link-Local, CGNAT, IPv6 ULA) — die hinter Docker/Coolify immer container-intern ist.
3. Ist der Peer intern, wird der Client aus seinen Weiterleitungs-Metadaten in dieser Reihenfolge ermittelt: CF-Connecting-IP (sodass ein CDN wie Cloudflare, das X-Forwarded-For umschreibt, weiterhin den echten Client liefert) → X-Forwarded-For (von rechts nach links durchlaufen, interne Hops überspringend) → X-Real-IP. Es werden nur literale IPs akzeptiert (kein DNS).

Da private Peers und CDNs automatisch behandelt werden, benötigen die meisten Deployments keine Konfiguration — der gebündelte Caddy, eine Coolify-Edge oder ein vorgelagertes CDN funktionieren sofort. Die optionale Variable SECURITY_TRUSTED_PROXIES (durch Kommas getrennte literale IP/CIDR und/oder Service-Hostnamen) fügt nur Vertrauen für ein ungewöhnliches Proxy hinzu, dessen Transport-Peer eine öffentliche Adresse ist.

Die Client-IP ist ein grober Best-Effort-Filter — keine Authentifizierung. Wer den Ursprung direkt erreichen kann (unter Umgehung von CDN/Proxy), könnte ein gewähltes CF-Connecting-IP vortäuschen; empfohlene Härtung ist, den Ursprung per Firewall so zu beschränken, dass nur Ihr CDN/Proxy ihn erreicht.

Nicht global routbare Client-Adressen (Loopback, privat/RFC 1918, Link-Local, CGNAT, IPv6 ULA) werden nie geo-blockiert — sie lassen sich nicht geolokalisieren — sodass localhost-Health-Checks und LAN-/Same-Host-Deployments funktionieren, während GeoIP aktiv ist. Die IP-Whitelist und die Authentifizierung gelten weiterhin für sie.

Ausgenommene Pfade

Die folgenden Pfade sind immer ausgenommen von geografischen Beschränkungen, damit sie weltweit erreichbar bleiben:

• öffentliche Angebotslinks (/offer/public/*) und öffentliches Branding (/api/v1/public/branding/*),
• E-Mail-Link-Aktionen: Abmeldung (/api/v1/notifications/unsubscribe-token/*) und öffentliche Präferenzen (/api/v1/notifications/preferences-public/*),
• Infrastruktur-/Health-Endpunkte (/health*, /actuator/health, /actuator/info).

Admin-Authentifizierung (/api/v1/auth/login, 2FA) und authentifizierte Assets bleiben geo-geschützt.

Konfiguration

Variable	Standard	Beschreibung
GEOIP_ENABLED	false	Nur Schalter für die Länder-Durchsetzung — zugleich Notfallschalter. Beeinflusst nicht das Laden der Datenbank: Die DB wird weiterhin geladen und aktualisiert (siehe GEOIP_AUTO_UPDATE), kann also bereit sein, während die Durchsetzung aus ist. false deaktiviert die gesamte Länder-Durchsetzung zuverlässig (siehe Wiederherstellung unten).
GEOIP_DB_PATH	/app/data/geoip/GeoLite2-Country.mmdb	Pfad zur .mmdb-Länderdatenbankdatei (wird bei aktiviertem GeoIP automatisch befüllt).
GEOIP_AUTO_UPDATE	true	Datenbank beim Start automatisch herunterladen (standardmäßig keyless DB-IP; MaxMind, wenn MAXMIND_* gesetzt sind), wenn sie fehlt oder älter als GEOIP_AUTO_UPDATE_MAX_AGE_DAYS ist (Standard 25). false setzen, um die Datei selbst zu verwalten.
SECURITY_GEOIP_ALLOWED_COUNTRIES	(leer)	Durch Kommas getrennte ISO-3166-1-alpha-2-Ländercodes (z. B. PL,DE,FR). Codes werden in Großbuchstaben normalisiert und validiert; ungültige Codes werden abgelehnt. Leer = keine Einschränkung. Wenn gesetzt, ist dieser Operatorwert maßgeblich gegenüber der In-App-Einstellung des Tenants.

Wenn keine Länderliste konfiguriert ist, arbeitet der GeoIP-Filter passiv — er löst Ländercodes für Tracking-Zwecke auf, blockiert aber keine Anfragen. Das Aktivieren der Länderfilterung im Admin-Bereich verwendet einen validierten Länderwähler (ISO 3166-1 alpha-2) und erfordert mindestens ein Land sowie eine geladene Datenbank.

Aktualisieren der Datenbank: der automatische Download beim Start hält sie hinreichend aktuell, aber nach dem manuellen Austausch der .mmdb-Datei können Sie sie ohne Neustart unter Administration → Sicherheit → effektiver Zustand → Datenbank neu laden neu laden (ein abgesichertes Neuladen — eine beschädigte oder fehlende Kandidatendatei behält die aktuell geladene Datenbank). Ein Backend-Neustart übernimmt die neue Datei ebenfalls. Das Panel des effektiven Zustands zeigt, ob die Datenbank geladen ist, samt Build-/Ladezeitstempel.

Wiederherstellung nach einer GeoIP-Sperre

Wenn eine Länder-Erlaubnisliste versehentlich Ihr eigenes Land ausschließt, erhalten Sie HTTP 403 mit dem Wiederherstellungshinweis GEO_BLOCKED. So stellen Sie den Zugriff wieder her:

1. Setzen Sie GEOIP_ENABLED=false in der Backend-Umgebung.
2. Starten Sie das Backend neu (das deaktiviert die GeoIP-Durchsetzung, bevor eine Richtlinie ausgewertet wird).
3. Korrigieren oder leeren Sie die Länder-Erlaubnisliste, setzen Sie dann GEOIP_ENABLED=true und starten Sie erneut neu.

Dies ist unabhängig vom Wiederherstellungsschalter der IP-Whitelist — die Wiederherstellung des einen deaktiviert nie stillschweigend das andere.

Datenschutzhinweise

• Die GeoIP-Auflösung ist zustandslos — es wird keine dauerhafte IP-zu-Land-Zuordnung gespeichert.
• Für das Angebots-Tracking wird nur der Ländercode erfasst (z. B. „DE“), nicht die IP-Adresse selbst.
• In Angebots-Web-Ereignissen erfasste IP-Adressen unterliegen dem konfigurierbaren IP-Anonymisierungs-Job, der sie nach einer konfigurierbaren Anzahl von Tagen für die DSGVO-Konformität hasht.