fail2ban-webui/docs/authentication.md

Anmeldung

AUTH_MODE legt fest, wie sich Benutzer anmelden. Ohne funktionierende Konfiguration startet der Container nicht – einen Modus ohne Anmeldung gibt es nicht.

Modus	Einsatz
local	ein gemeinsames Admin-Konto reicht
oidc	ein Identity Provider ist vorhanden (Authentik, Keycloak, Authelia, Zitadel, …)
local,oidc	Single Sign-on mit lokalem Notfallkonto
proxy	der Reverse Proxy meldet bereits an (Forward Auth, Basic Auth, IP-Liste)

Jede Änderung (Sperren/Entsperren) braucht zusätzlich das CSRF-Token der Sitzung und einen passenden Origin-Header; jede Aktion wird mit Benutzernamen protokolliert.

Lokaler Benutzer

docker compose run --rm -it fail2ban-webui hash-password

AUTH_MODE=local
AUTH_USER=admin
AUTH_PASSWORD_HASH='scrypt:32768:8:1$…'

• Passwörter brauchen mindestens 12 Zeichen; der Hash ist scrypt (Werkzeug).
• Nach LOGIN_MAX_ATTEMPTS (5) Fehlversuchen wird eine Client-IP für LOGIN_LOCK_MINUTES (15) gesperrt.
• Fehlgeschlagene Anmeldungen werden als LOGIN_FAILED user=… ip=… protokolliert – siehe operations.md, um sie von fail2ban am Proxy sperren zu lassen.
• Hinter einem Reverse Proxy TRUSTED_PROXY_HOPS=1 setzen, sonst erscheinen alle Clients mit der Adresse des Proxys und teilen sich einen Sperrzähler.

OpenID Connect

Voraussetzungen: PUBLIC_URL ist auf die externe https://-URL gesetzt, und der Provider erlaubt die Redirect-URI <PUBLIC_URL>/auth/callback.

Die Oberfläche nutzt den Authorization Code Flow mit PKCE (S256) und einen vertraulichen Client. Benutzername: OIDC_USERNAME_CLAIM (Standard preferred_username); Gruppen: OIDC_GROUPS_CLAIM (Standard groups).

Immer einschränken, wer sich anmelden darf – mit OIDC_ALLOWED_GROUPS und/oder OIDC_ALLOWED_USERS oder mit einer Zugriffsrichtlinie im Provider. Ohne beides kann jedes Konto, das der Provider für diesen Client zulässt, IPs sperren (beim Start wird eine Warnung protokolliert).

Authentik

1. Applications → Providers → Create → OAuth2/OpenID Provider

   • Name: fail2ban-webui
   • Authorization flow: default-provider-authorization-explicit-consent (oder implicit)
   • Client type: Confidential – Client ID und Client Secret notieren
   • Redirect URIs: strict · https://fail2ban.example.org/auth/callback
   • Signing key: ein beliebiges Zertifikat (z. B. authentik Self-signed Certificate)
   • Advanced protocol settings → Scopes: openid, email, profile (das Standard-Mapping profile enthält den Claim groups)

2. Applications → Applications → Create

   • Name: fail2ban-webui, Slug: fail2ban-webui, Provider: der aus Schritt 1

3. Directory → Groups → Create fail2ban-admins anlegen und die Benutzer hinzufügen.

4. Optional, empfohlen: in der Application unter Policy / Group / User Bindings die Gruppe fail2ban-admins binden – dann kommt sonst niemand bis zur Zustimmungsseite.

5. .env:

   PUBLIC_URL=https://fail2ban.example.org
   AUTH_MODE=oidc
   OIDC_ISSUER=https://auth.example.org/application/o/fail2ban-webui/
   OIDC_CLIENT_ID=…
   OIDC_CLIENT_SECRET='…'
   OIDC_ALLOWED_GROUPS=fail2ban-admins
   OIDC_BUTTON_LABEL=Authentik
   

6. docker compose up -d, PUBLIC_URL öffnen, auf Anmelden mit Authentik klicken.

Die Issuer-URL zeigt Authentik auf der Provider-Seite (OpenID Configuration Issuer).

Andere Provider

Provider	OIDC_ISSUER	Gruppen
Keycloak	https://kc.example.org/realms/<realm>	einen Group Membership-Mapper mit Claim-Name groups anlegen, „Full group path" aus
Authelia	https://auth.example.org	Scope groups; OIDC_SCOPES=openid email profile groups setzen
Zitadel	https://<instanz>.zitadel.cloud	Rollen statt Gruppen – OIDC_ALLOWED_USERS oder eine Projektrollen-Prüfung in Zitadel verwenden

Abmelden

„Abmelden" beendet die Sitzung in der Weboberfläche. Die Sitzung beim Provider bleibt aktiv; der nächste Klick auf „Anmelden mit …" meldet daher meist ohne Passwort wieder an.

Proxy-Modus

Der Proxy übernimmt die Anmeldung; die Oberfläche prüft nur, woher Anfragen kommen, und optional, welchen Benutzer der Proxy meldet.

AUTH_MODE=proxy
TRUSTED_PROXY_HOPS=1
# only accept requests from the proxy (address as seen by the container)
AUTH_PROXY_ALLOWED_IPS=172.23.51.1/32
# optional: user name for the audit log, set by the proxy
AUTH_PROXY_HEADER=X-authentik-username
# optional: logout URL of the proxy/IdP
AUTH_PROXY_LOGOUT_URL=https://fail2ban.example.org/outpost.goauthentik.io/sign_out

• AUTH_PROXY_ALLOWED_IPS wird gegen den direkten Gegenüber des Containers geprüft, nicht gegen X-Forwarded-For. Läuft der Proxy auf demselben Docker-Host und erreicht den Container über den veröffentlichten Port, ist das das Netzwerk-Gateway (172.23.51.1 in der Beispiel-Compose); nach einer Anfrage mit docker compose logs prüfen.
• Ist AUTH_PROXY_HEADER gesetzt, werden Anfragen ohne diesen Header abgelehnt (401). Der Proxy muss diesen Header aus Client-Anfragen entfernen – Forward-Auth-Integrationen (Authentik, Authelia) tun das.
• Ohne AUTH_PROXY_HEADER steht im Protokoll der Benutzer proxy.

Beispiele für Nginx Proxy Manager, Traefik und Caddy stehen in reverse-proxy.md.