schiwagoaandClaude Opus 5.5
019c74a418
README and all guides under docs/ are now in German, with German anchors for the cross references. Code and configuration blocks are unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
120 lines
5.4 KiB
Markdown
120 lines
5.4 KiB
Markdown
# 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
|
||
|
||
```bash
|
||
docker compose run --rm -it fail2ban-webui hash-password
|
||
```
|
||
|
||
```ini
|
||
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](operations.md#login-mit-fail2ban-absichern), 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`:
|
||
|
||
```ini
|
||
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.
|
||
|
||
```ini
|
||
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](reverse-proxy.md).
|