scriptos/external-whitelist-auth-gate

Fork 0

Files

Patrick Asmus 8122b5274a Initial

2026-05-11 20:47:25 +02:00

7.8 KiB

Raw Permalink Blame History

Traefik-External Whitelist Auth Gate

Kleiner Traefik-ForwardAuth-Dienst mit externer Whitelist und BasicAuth-Ausweichlösung

🏰 Webseite · 📰 Gemeinschaft · 🐘 Mastodon · 💬 Hilfe

Kleiner Traefik-ForwardAuth-Dienst für dieses Zugriffsmuster:

Wenn sich die Client-IP in einer externen Whitelist befindet, wird die Anfrage erlaubt.
Wenn sich die Client-IP nicht in der Whitelist befindet, wird BasicAuth angefordert.
Die externe Whitelist wird alle 5 Minuten aktualisiert und aufgelöst.
Die letzte gültige Whitelist bleibt erhalten, falls die externe Datei oder DNS-Abfragen fehlschlagen.

Die externe Whitelist kann DNS-Namen, IP-Adressen und CIDR-Bereiche enthalten.

Dateien

external_whitelist_auth_gate.py: der ForwardAuth-Dienst.
Dockerfile: Container-Image für den Dienst.
docker-compose.example.yaml: minimales Traefik-Compose-Beispiel.
traefik-dynamic.example.yml: Traefik-Middleware-Definition.
protected-router.example.yml: Beispiel-Router, der die Middleware verwendet.
.env.example: Beispiel-Zugangsdaten.
whitelist.example.txt: externe Beispiel-Whitelist-Datei.

Whitelist-Format

Veröffentliche eine Klartextdatei, die vom Container erreichbar ist:

# Kommentare sind erlaubt
office.example.com
vpn.example.com
203.0.113.42
198.51.100.0/24
2001:db8:1234::/48

DNS-Einträge werden in A- und AAAA-Records aufgelöst. Einzelne IPv4-Adressen werden zu /32, einzelne IPv6-Adressen zu /128.

Einrichtung

Kopiere diesen Ordner in dein Traefik-Projekt:

/path/to/traefik/external-whitelist-auth-gate

Füge den Dienst zu deiner Traefik-docker-compose.yaml hinzu:

external-whitelist-auth-gate:
  build:
    context: ./external-whitelist-auth-gate
  image: local/external-whitelist-auth-gate:1.0
  container_name: external-whitelist-auth-gate
  restart: unless-stopped
  read_only: true
  tmpfs:
    - /tmp
  security_opt:
    - no-new-privileges:true
  cap_drop:
    - ALL
  environment:
    WHITELIST_URL: "https://example.com/network-whitelist.txt"
    REFRESH_INTERVAL_SECONDS: "300"
    BASIC_AUTH_REALM: "${EXTERNAL_WHITELIST_AUTH_REALM:-Geschützter Bereich}"
    BASIC_AUTH_USER: "${EXTERNAL_WHITELIST_AUTH_USER:?EXTERNAL_WHITELIST_AUTH_USER in .env setzen}"
    BASIC_AUTH_PASSWORD: "${EXTERNAL_WHITELIST_AUTH_PASSWORD:?EXTERNAL_WHITELIST_AUTH_PASSWORD in .env setzen}"
    BASIC_AUTH_USER_2: "${EXTERNAL_WHITELIST_AUTH_USER_2:-}"
    BASIC_AUTH_PASSWORD_2: "${EXTERNAL_WHITELIST_AUTH_PASSWORD_2:-}"
    BASIC_AUTH_PASSWORD_SHA256_2: "${EXTERNAL_WHITELIST_AUTH_PASSWORD_SHA256_2:-}"
    BASIC_AUTH_USER_3: "${EXTERNAL_WHITELIST_AUTH_USER_3:-}"
    BASIC_AUTH_PASSWORD_3: "${EXTERNAL_WHITELIST_AUTH_PASSWORD_3:-}"
    BASIC_AUTH_PASSWORD_SHA256_3: "${EXTERNAL_WHITELIST_AUTH_PASSWORD_SHA256_3:-}"
    CLIENT_IP_STRATEGY: "rightmost"
  ports:
    - "127.0.0.1:9180:8080"

Füge die Zugangsdaten zu .env hinzu:

EXTERNAL_WHITELIST_AUTH_REALM=Geschützter Bereich
EXTERNAL_WHITELIST_AUTH_USER=admin
EXTERNAL_WHITELIST_AUTH_PASSWORD=bitte-aendern-langes-zufaelliges-passwort
EXTERNAL_WHITELIST_AUTH_USER_2=team
EXTERNAL_WHITELIST_AUTH_PASSWORD_2=zweites-langes-zufaelliges-passwort
EXTERNAL_WHITELIST_AUTH_USER_3=support
EXTERNAL_WHITELIST_AUTH_PASSWORD_3=drittes-langes-zufaelliges-passwort

Der erste BasicAuth-Benutzer ist Pflicht. Benutzer 2 und 3 sind optional; lasse die zugehörigen .env-Variablen leer oder entferne sie, wenn du sie nicht brauchst.

Füge die Traefik-Middleware in einer File-Provider-Konfiguration hinzu, zum Beispiel in dynamic/external-whitelist-auth.yml:

---
http:
  middlewares:
    external-whitelist-auth:
      forwardAuth:
        address: "http://127.0.0.1:9180/auth"
        trustForwardHeader: false
        maxResponseBodySize: 8192
        authResponseHeaders:
          - X-Access-Gate-User
          - X-Access-Gate-Reason

Hänge die Middleware nur an HTTPS-Router, die geschützt werden sollen:

middlewares:
  - external-whitelist-auth@file
  - deine-bestehenden-header

Belasse HTTP-Router als reine Weiterleitungen auf HTTPS. Andernfalls können Benutzer BasicAuth sehen, bevor die Weiterleitung erfolgt.

Starte den Dienst oder baue ihn neu:

docker compose up -d --build external-whitelist-auth-gate
docker compose up -d

Betrieb

Status prüfen:

curl -s http://127.0.0.1:9180/status

Erwartete Antwort:

{"last_error":"","last_refresh":1778437250,"network_count":5,"source_hosts":["office.example.com","vpn.example.com"]}

Aufgelöste IPs/CIDRs anzeigen:

curl -s "http://127.0.0.1:9180/status?verbose=1"

Konkrete IP gegen die aktuell geladene Whitelist prüfen:

curl -s "http://127.0.0.1:9180/check?ip=203.0.113.42"

Erwartete Antwort, wenn die IP enthalten ist:

{"allowlisted":true,"ip":"203.0.113.42","ip_source":"query","matched_networks":["203.0.113.42/32"]}

Die von Headern erkannte Client-IP prüfen:

curl -s -H "X-Forwarded-For: 203.0.113.42" http://127.0.0.1:9180/check

Eine nicht in der Whitelist enthaltene IP testen:

curl -i -H "X-Forwarded-For: 203.0.113.200" http://127.0.0.1:9180/auth

BasicAuth testen:

curl -i -u "admin:bitte-aendern-langes-zufaelliges-passwort" -H "X-Forwarded-For: 203.0.113.200" http://127.0.0.1:9180/auth

Optionalen zweiten oder dritten BasicAuth-Benutzer testen:

curl -i -u "team:zweites-langes-zufaelliges-passwort" -H "X-Forwarded-For: 203.0.113.200" http://127.0.0.1:9180/auth

Umgebungsvariablen

WHITELIST_URL: URL der externen Whitelist-Textdatei.
REFRESH_INTERVAL_SECONDS: Aktualisierungsintervall, Standardwert 300.
BASIC_AUTH_REALM: BasicAuth-Realm des Browsers.
BASIC_AUTH_USER: erster BasicAuth-Benutzername.
BASIC_AUTH_PASSWORD: Passwort des ersten BasicAuth-Benutzers.
BASIC_AUTH_PASSWORD_SHA256: optionale Alternative zu BASIC_AUTH_PASSWORD; Hex-SHA-256-Digest des ersten Passworts.
BASIC_AUTH_USER_2: optionaler zweiter BasicAuth-Benutzername.
BASIC_AUTH_PASSWORD_2: optionales Passwort des zweiten BasicAuth-Benutzers.
BASIC_AUTH_PASSWORD_SHA256_2: optionale Alternative zu BASIC_AUTH_PASSWORD_2; Hex-SHA-256-Digest des zweiten Passworts.
BASIC_AUTH_USER_3: optionaler dritter BasicAuth-Benutzername.
BASIC_AUTH_PASSWORD_3: optionales Passwort des dritten BasicAuth-Benutzers.
BASIC_AUTH_PASSWORD_SHA256_3: optionale Alternative zu BASIC_AUTH_PASSWORD_3; Hex-SHA-256-Digest des dritten Passworts.
WHITELIST_EXTRA_CIDRS: optionale, kommagetrennte CIDR/IP-Liste, die zur externen Whitelist hinzugefügt wird.
CLIENT_IP_STRATEGY: standardmäßig rightmost, alternativ leftmost.
CLIENT_IP_HEADER: optionaler benutzerdefinierter Client-IP-Header; standardmäßig X-Forwarded-For.

Hinweise

Der Dienst ist für Traefiks forwardAuth-Middleware ausgelegt. Er gibt 204 zurück, wenn der Zugriff erlaubt ist, und 401 mit WWW-Authenticate, wenn BasicAuth erforderlich ist.

Wenn Traefik mit network_mode: host läuft, ist das Binden des Auth-Dienstes an 127.0.0.1:9180 einfach und verhindert, dass er öffentlich erreichbar ist.

7.8 KiB Raw Permalink Blame History