SSO-Break-Glass

Wenn SSO für deine Organisation erzwungen wird, melden sich Mitglieder über deinen Identitätsanbieter an. Wird dieser IdP unerreichbar oder falsch konfiguriert oder bricht die SSO-Verbindung, funktioniert die normale Anmeldeseite der Organisation nicht mehr, und Mitglieder können sich nicht authentifizieren. Diese Seite beschreibt, wie du den Zugriff wiederherstellst, ohne zu warten, bis der IdP zurück ist.

Was ausfällt und was nicht

Die organisationsspezifische SSO-Anmeldung unter frem.sh/user/login?redirect_to=/<org> erzwingt SSO. Ist der IdP nicht erreichbar oder falsch konfiguriert, schlägt die Weiterleitung fehl, und Mitglieder sehen einen Fehler.

Die lokale fremforge-Anmeldung unter https://frem.sh/user/login ist davon getrennt. Sie akzeptiert lokale Zugangsdaten aus Benutzername und Passwort und läuft nicht über die SSO-Konfiguration der Organisation. Owner der Organisation haben immer lokale Zugangsdaten und können diesen Weg auch nutzen, wenn SSO ausgefallen ist.

Schritt 1: als Owner über die lokale Anmeldung anmelden

Rufe direkt auf:

https://frem.sh/user/login

Verwende nicht frem.sh/user/login?redirect_to=/<org>. Diese Seite erzwingt SSO und schlägt fehl.

Gib deinen lokalen fremforge-Benutzernamen und dein Passwort ein. Ist für dein lokales Konto die Zwei-Faktor-Authentifizierung aktiv, schließe auch diesen Schritt ab. Siehe Zwei-Faktor-Authentifizierung, falls dein TOTP nicht verfügbar ist.

Schritt 2: die SSO-Erzwingung abschalten

Sobald du als Owner der Organisation angemeldet bist:

Gehe zu Organisationsverwaltung → SSO → Auth-Quellen (frem.sh/<org>/_admin/sso).
Suche die Auth-Quelle, die fehlschlägt.
Klicke auf Entfernen und bestätige auf der Seite /_admin/sso/auth-sources/<id>/delete-confirm. (Einen Schalter zum Deaktivieren gibt es derzeit nicht: Das Entfernen der Auth-Quelle stellt die passwortbasierte Anmeldung wieder her; sobald der IdP repariert ist, legst du sie mit dem SSO-Assistenten neu an.)

Das Abschalten der Auth-Quelle stellt die passwortbasierte Anmeldung für alle Mitglieder der Organisation wieder her, während du das Problem mit dem IdP untersuchst und behebst. Mitglieder können sich jetzt unter frem.sh/user/login?redirect_to=/<org> mit ihren lokalen fremforge-Zugangsdaten anmelden.

Schritt 3: den IdP reparieren

Ohne SSO-Erzwingung hast du Zeit für die Fehlersuche, ohne dass Nutzer ausgesperrt sind. Häufige Ursachen:

Abgelaufenes Zertifikat: Das Signaturzertifikat des IdP ist abgelaufen. Exportiere das Zertifikat erneut und aktualisiere es in der Konfiguration der Auth-Quelle. Siehe OIDC-SSO.
Abweichende Redirect-URI: Die im IdP registrierte Callback-URL stimmt nicht mit dem überein, was fremforge sendet. Vergleiche https://frem.sh/user/oauth2/<auth-source-name>/callback, mit dem genauen Namen, der auf der Karte der Auth-Quelle unter Organisationsverwaltung → SSO steht, mit dem, was in der IdP-App registriert ist.
Ausfall des IdP: Ist der IdP selbst ausgefallen, warte, bis er wieder läuft. In diesem Fall sind keine Änderungen an fremforge nötig.

Schritt 4: SSO wieder einschalten

Sobald der IdP funktioniert:

Gehe zu Organisationsverwaltung → SSO und starte den SSO-Assistenten unter /<org>/_admin/sso/wizard/start, um die Auth-Quelle mit der korrigierten Konfiguration neu anzulegen.
Teste die SSO-Anmeldung in einem privaten Browserfenster unter frem.sh/user/login?redirect_to=/<org>, um zu bestätigen, dass sie gelingt.
Die SSO-Erzwingung für die Organisation gilt wieder, sobald die neue Auth-Quelle aktiv ist.

Wenn die lokalen Zugangsdaten des Owners unbekannt sind

Wurde das Owner-Konto ausschließlich über SSO angelegt und nie ein lokales Passwort gesetzt, funktioniert der oben beschriebene Break-Glass-Weg nicht.

Schreib an support@frem.sh mit dem Betreff „SSO break-glass“. Gib an:

den Slug deiner Organisation
die registrierte E-Mail-Adresse des Owners
eine Beschreibung der Lage

Der Support prüft die Identität auf einem separaten Kanal und stellt für das Owner-Konto einen temporären Token zum Zurücksetzen des lokalen Passworts aus. Die Antwort erfolgt laut Support-SLA innerhalb eines Werktags. Die Geschäftszeiten findest du unter Support.

Das Break-Glass-Konto ist dauerhaft: behalte es, härte es

Das Bootstrap-Admin-Konto, das fremforge bei der Registrierung einer Organisation anlegt, ist dein Break-Glass-Konto. Lösche es nicht, nachdem du SSO eingerichtet hast. Ohne einen lokalen Owner, der sich unabhängig vom IdP unter frem.sh/user/login anmelden kann, sperrt ein Ausfall oder eine Fehlkonfiguration des IdP die gesamte Organisation aus, und die Wiederherstellung erfordert ein Support-Ticket (siehe Wenn die lokalen Zugangsdaten des Owners unbekannt sind oben).

Härte stattdessen das lokale Konto, damit es sicher bestehen bleiben kann, auch wenn SSO im Alltag der Weg ist:

Ersetze das Bootstrap-Passwort bei der ersten Anmeldung durch ein langes, zufälliges (Benutzereinstellungen → Sicherheit → Passwort). Das Passwort aus der Willkommens-E-Mail ist einmalig und sollte sofort ersetzt werden. Erzeuge ein Passwort mit mindestens 24 Zeichen in einem Passwortmanager; du wirst es selten eintippen.
Schalte die Zwei-Faktor-Authentifizierung für das lokale Konto ein. fremforge / Forgejo unterstützt TOTP (jede Authenticator-App) und WebAuthn / Passkeys (Benutzereinstellungen → Sicherheit → Zwei-Faktor-Authentifizierung). Zwei-Faktor-Authentifizierung auf dem Break-Glass-Konto ist Pflicht, nicht optional: Ein langes, zufälliges Passwort ohne zweiten Faktor ist immer noch ein einzelner, phishbarer Faktor, und ein Break-Glass-Weg mit nur einem Faktor macht den Sinn einer SSO-Pflicht zunichte. Bewahre die Wiederherstellungscodes sicher auf (verschlüsselter Passwortmanager, versiegelter Umschlag in einem Tresor, keine Slack-Direktnachricht).
Prüfe, dass die lokale Anmeldung noch funktioniert, bevor du SSO auf erzwungen setzt. Öffne ein privates Browserfenster, rufe https://frem.sh/user/login auf, melde dich mit dem lokalen Passwort und dem zweiten Faktor an und bestätige, dass du Organisationsverwaltung → SSO erreichst. Mach das, solange deine normale Sitzung in einem regulären Fenster noch offen ist, damit du eingreifen kannst, falls etwas nicht stimmt.
Behalte mindestens zwei Owner, die die obigen Schritte jeweils unabhängig erledigt haben. Verliert ein Owner den Zugriff (verlorenes Gerät, gestohlener Laptop, Jobwechsel), kann der zweite den Zugriff neu vergeben, ohne den Support einzuschalten. Das ist die wirksamste einzelne Maßnahme für Organisationen mit erzwungenem SSO.
Plane eine vierteljährliche Break-Glass-Übung. Einmal pro Quartal meldet sich ein Owner über den lokalen Weg an, bestätigt, dass die Zwei-Faktor-Authentifizierung funktioniert, und prüft, dass das Abschalten von SSO noch funktioniert. Kostet wenig und deckt den Fall „ich habe meine Wiederherstellungscodes vergessen“ auf, solange wenig auf dem Spiel steht.

Querverweise

OIDC-SSO: Einrichtung der OIDC-Auth-Quelle und Verwaltung der Zertifikate
Zwei-Faktor-Authentifizierung: Zwei-Faktor-Authentifizierung und Wiederherstellungscodes für lokale Konten
Support: wie du den Support erreichst und welche Antwortzeiten du erwarten kannst
Fehlerbehebung: OIDC-Fehlermeldungen