SSO-Login (OIDC)

Statt eines eigenen CachePanel-Passworts kannst du dich auch über deinen bestehenden Single-Sign-On-Anbieter anmelden — jeden, der den Standard OpenID Connect (OIDC) spricht (Authentik, Keycloak, Authelia, Zitadel, …). Diese Anleitung spielt es konkret mit Authentik durch, das Prinzip ist bei jedem anderen Anbieter identisch.

Das normale Passwort-Login bleibt daneben bestehen — SSO ist eine zusätzliche Option, kein Zwang.

Warum das über Umgebungsvariablen läuft, nicht über die Einstellungsseite

Alle anderen Integrationen (Discord, Grafana, SFTP, …) werden über Einstellungen in der Web-Oberfläche eingerichtet. SSO ist bewusst anders: die drei nötigen Werte werden in der .env-Datei gesetzt, nicht in der GUI.

Grund: Die Einstellungsseite ist selbst erst nach dem Login erreichbar — aber genau dieses Login soll SSO ja erst ermöglichen. Auf einer komplett frischen, noch nicht eingerichteten Instanz gäbe es sonst kein Huhn ohne Ei.

1. Provider bei Authentik anlegen

1. In Authentik: Applications → Providers → Create → OAuth2/OpenID Provider.

2. Authorization flow: euren Standard-Explicit-Consent- oder Implicit-Consent-Flow auswählen (wie bei jeder anderen OIDC-Anwendung in eurem Authentik).

3. Redirect URIs: exakt

   https://<eure-cachepanel-domain>/api/auth/oidc/callback

   eintragen — der Pfad ist fix, nur die Domain anpassen. Ein abweichender Pfad (z. B. fehlendes /api) lässt den Login fehlschlagen.

4. Signing Key: einen echten Signaturschlüssel auswählen (z. B. das mitgelieferte selbstsignierte Authentik-Zertifikat) — nicht leer lassen.

   Häufigster Stolperstein

   Ohne konfigurierten Signaturschlüssel liefert Authentiks JWKS-Endpunkt keine Schlüssel aus, und CachePanel kann die Anmeldung nicht validieren — die Anmeldung schlägt dann mit einer klaren Fehlermeldung fehl ("no signing keys"). Bereits beim Provider-Anlegen einen Schlüssel setzen, nicht erst nachträglich.

5. Applications → Create, den eben angelegten Provider zuweisen.

2. CachePanel konfigurieren

In der .env-Datei auf dem Server (docker-compose.yml-Verzeichnis) ergänzen:

OIDC_ISSUER_URL=https://<authentik-domain>/application/o/<euer-app-slug>/
OIDC_CLIENT_ID=<Client-ID aus Authentik>
OIDC_CLIENT_SECRET=<Client-Secret aus Authentik>
OIDC_PROVIDER_NAME=authentik

• OIDC_ISSUER_URL findest du in Authentik direkt am Provider (oder unter dessen .well-known/openid-configuration-Link) — CachePanel liest davon selbst Autorisierungs-/Token-/JWKS-Endpunkt ab, nichts davon muss man selbst heraussuchen.
• OIDC_PROVIDER_NAME ist nur die Beschriftung des Login-Buttons ("Mit authentik anmelden") — optional, Standardwert ist bereits authentik.

Danach den Container neu bauen/starten, damit die neuen Variablen geladen werden:

docker compose up -d --build

3. Anmelden

Auf der Login-Seite erscheint jetzt automatisch ein zusätzlicher Button unterhalb des Passwort-Formulars:

"Mit {Provider-Name} anmelden"

Fall A: Noch gar kein CachePanel-Konto vorhanden

Beim allerersten erfolgreichen SSO-Login auf einer frischen Instanz (kein Setup-Screen wurde je durchlaufen) legt CachePanel automatisch ein neues Admin-Konto mit deinem SSO-Benutzernamen an und loggt dich direkt ein — der übliche Ersteinrichtungs-Bildschirm wird dabei übersprungen. Genau der gleiche Vertrauensgrundsatz wie beim normalen Ersteinrichtungs-Screen: wer zuerst kommt, richtet ein.

Fall B: Es existiert bereits ein CachePanel-Konto

CachePanel prüft, ob dein SSO-Benutzername (bevorzugt preferred_username, sonst email, sonst sub aus dem Identity-Token) exakt mit einem bereits bestehenden CachePanel-Benutzernamen übereinstimmt:

• Stimmt er überein → du wirst in genau diesen Account eingeloggt, mit der Rolle (Admin/Nur-Lesen), die der Account in CachePanel schon hat. SSO bestimmt nur, wer du bist — was du darfst, entscheidet weiterhin CachePanel selbst, nicht der Identity-Provider.
• Stimmt keiner überein → Login wird abgelehnt ("kein passendes Konto"). CachePanel legt hier bewusst keinen neuen Account automatisch an, sobald die Instanz einmal eingerichtet ist — sonst könnte sich jeder mit Zugriff auf euren Identity-Provider selbst Zugang verschaffen. Ein Admin muss den Account vorher unter Einstellungen → Konto & Sicherheit manuell mit passendem Benutzernamen anlegen.

Passwort-Login abschalten (optional)

Ein eigenes "Passwort ändern"-Feld für den eingeloggten Account gibt es in der Oberfläche aktuell nicht — das Passwortfeld unter Einstellungen → Konto & Sicherheit gehört zum Formular für einen neuen Account, nicht zum Ändern eines bestehenden.

Willst du trotzdem, dass dein bestehender Account nur noch per SSO nutzbar ist, bleibt aktuell nur der direkte Weg auf dem Server: den password_hash in data/auth.json per Hand (bzw. per kurzem Python-Snippet mit bcrypt) auf einen langen, zufälligen, nirgendwo notierten Wert setzen. SSO funktioniert davon komplett unabhängig weiter, der Account bleibt bestehen. Ein echtes Self-Service-"Passwort ändern" ist eine offene Idee für eine künftige Version.

Was das Identity-Token bestimmt

CachePanel validiert die Signatur des vom Provider zurückgegebenen ID-Tokens immer gegen dessen echte, live abgerufene Signaturschlüssel (JWKS) — nicht gegen einen gecachten Stand, damit ein rotierter oder nachträglich hinzugefügter Schlüssel beim nächsten Login sofort funktioniert. Akzeptiert werden ausschließlich mit RS256 signierte Tokens.