Anmeldung mit Single Sign-on (OIDC) einrichten

Mit Single Sign-on melden sich Menschen nicht mehr mit einem FediSuite-Passwort an, sondern über einen Identity-Provider, den du selbst betreibst, zum Beispiel authentik oder Keycloak. Diese Anleitung erklärt zuerst in einfachen Worten, worum es geht, führt dich dann Schritt für Schritt durch die Einrichtung und zeigt am Ende, wie du Fehler findest. Du musst OpenID Connect vorher nicht kennen.

Verfügbar ab FediSuite 2.4.0

Alles hier gilt für FediSuite 2.4.0 und neuer. Du schaltest die Funktion im Webinterface unter Adminbereich → Einstellungen ein. An der docker-compose.yml musst du nichts ändern, und es ist keine Umgebungsvariable nötig, um die Funktion zu aktivieren.

Die Android-App kann kein Single Sign-on

Die FediSuite-Android-App meldet sich nur mit E-Mail und Passwort an. Konten, die nur über Single Sign-on existieren, haben kein nutzbares Passwort. Schaltest du den Passwort-Login ab, kann sich mit der Android-App niemand mehr anmelden. Lass den Passwort-Login an, wenn Leute die App nutzen.

Wichtig: Reihenfolge einhalten, sonst sperrst du dich aus

Wer den Passwort-Login abschaltet, bevor der Login über den Provider nachweislich funktioniert, kommt nicht mehr in seine Instanz. Gehe deshalb genau so vor, wie es der Abschnitt Einführung in der sicheren Reihenfolge beschreibt. Für den Notfall gibt es einen Notausstieg.

  • Mach vorher ein Backup (Backup und Restore).
  • Lass den Passwort-Login zuerst an und schalte ihn erst am Ende aus, falls du das überhaupt willst.
  • Verknüpfe zuerst dein eigenes Admin-Konto mit dem Provider und teste die Anmeldung.

1. Die Kurzfassung

Single Sign-on, kurz SSO, heißt: Deine Nutzer*innen tippen kein FediSuite-Passwort ein. Sie klicken auf einen Knopf, melden sich bei deinem Identity-Provider an und landen danach angemeldet in FediSuite. Der Provider kennt die Menschen und prüft ihre Zugangsdaten, FediSuite verlässt sich auf seine Antwort.

FediSuite benutzt dafür den Standard OpenID Connect, kurz OIDC. Deshalb funktioniert die Anbindung mit authentik und Keycloak und mit jedem anderen Provider, der OIDC beherrscht.

  • Du schaltest SSO unter Adminbereich → Einstellungen → Single Sign-on (OIDC) ein.
  • Du brauchst von deinem Provider die Adresse (Issuer), eine Client-ID und ein Client-Secret. Beim Provider trägst du außerdem die Weiterleitungs-URL von FediSuite ein.
  • Bestehende Konten werden über die E-Mail-Adresse zugeordnet, aber nur, wenn der Provider die Adresse als bestätigt meldet.
  • Die Admin-Rolle vergibt nie der Provider. Rollen bleiben immer in FediSuite.
  • Die sichere Reihenfolge lautet: Einstellungen speichern und den Passwort-Login anlassen, eigenes Admin-Konto verknüpfen, Anmeldung testen, erst danach den Passwort-Login bei Bedarf abschalten.
  • Wenn du dich aussperrst, hilft OIDC_PASSWORD_LOGIN_OVERRIDE=true in der .env, siehe Notausstieg.
Anmeldeseite von FediSuite mit E-Mail- und Passwortfeld. Unter dem Trenner „oder“ steht der Knopf „Mit Single Sign-on anmelden“.
Die Anmeldeseite mit dem zusätzlichen Single-Sign-on-Knopf

2. Was ist das? Die Begriffe in einfachen Worten

Stell dir ein Bürogebäude vor. Jede Firma darin könnte eigene Schlüssel an ihre Leute ausgeben und selbst prüfen, wer reindarf. Es geht auch anders: Am Empfang sitzt jemand, der jeden Ausweis prüft und der Firma im dritten Stock sagt: Diese Person kenne ich, sie darf zu euch. Genau so arbeitet Single Sign-on. Der Empfang ist dein Identity-Provider, die Firma im dritten Stock ist FediSuite.

Du musst die folgenden Begriffe nicht auswendig kennen. Sie tauchen in den Einstellungen und in Fehlermeldungen auf, deshalb stehen sie hier an einer Stelle.

Begriffe rund um Single Sign-on und ihre Bedeutung
BegriffBedeutung
Identity-ProviderDer Dienst, der deine Nutzer*innen kennt und ihre Passwörter prüft, zum Beispiel authentik oder Keycloak. FediSuite fragt ihn: Wer ist diese Person?
OpenID Connect (OIDC)Die gemeinsame Sprache, in der FediSuite und der Provider miteinander reden. Sie baut auf OAuth 2.0 auf und liefert zusätzlich eine signierte Aussage darüber, wer sich angemeldet hat.
IssuerDie Webadresse, die deinen Provider (oder eine Anwendung bzw. einen Realm darin) eindeutig bezeichnet. Von dort aus findet FediSuite alles Weitere selbst.
ClientAus Sicht des Providers ist FediSuite ein Client, in manchen Oberflächen auch Anwendung genannt. Du registrierst ihn einmal beim Provider.
Client-ID und Client-SecretEine Art Benutzername und Passwort für FediSuite selbst, damit der Provider weiß, dass die Anfrage wirklich von deiner Instanz kommt. Das Secret wird verschlüsselt gespeichert und nie wieder angezeigt.
Weiterleitungs-URLDie Adresse in FediSuite, zu der der Provider die Leute nach der Anmeldung zurückschickt. Du musst genau diese Adresse beim Provider eintragen. FediSuite zeigt sie dir in den Einstellungen an.
ScopesDie Arten von Informationen, nach denen FediSuite fragt. openid ist Pflicht, email braucht FediSuite zum Zuordnen der Konten, profile sind die üblichen Namensangaben.
ClaimsDie einzelnen Angaben in der Antwort des Providers, etwa die E-Mail-Adresse, ob sie bestätigt ist (email_verified) und eine dauerhafte Nutzer-ID (sub).
ID-TokenEine signierte Nachricht des Providers, die sagt, wer sich angemeldet hat. FediSuite prüft Signatur, Aussteller, Empfänger, Ablaufzeit und einen Einmalwert (nonce).
PKCEEin zusätzlicher Schutz für den Code, der bei der Anmeldung entsteht. FediSuite benutzt ihn immer.
Subject (sub)Die dauerhafte, interne ID einer Person beim Provider. Sie ändert sich nicht, wenn jemand die E-Mail-Adresse wechselt. FediSuite verknüpft Konten über Issuer und Subject.

3. So läuft eine Anmeldung ab

  1. Die Person öffnet die Anmeldeseite von FediSuite und klickt auf den Single-Sign-on-Knopf.
  2. FediSuite schickt den Browser zum Provider, zusammen mit einem zufälligen Einmalwert und einer Code-Prüfung. Ein kleines Cookie bindet den Vorgang an diesen Browser.
  3. Die Person meldet sich beim Provider an, mit dem, was der Provider verlangt: Passwort, Passkey, zweiter Faktor.
  4. Der Provider schickt den Browser mit einem kurzlebigen Code zurück zur Weiterleitungs-URL von FediSuite.
  5. FediSuite tauscht den Code direkt beim Provider gegen das ID-Token ein (von Server zu Server, nicht über den Browser) und prüft das Token.
  6. FediSuite entscheidet, welches FediSuite-Konto zu dieser Identität gehört, siehe In welchem Konto landet eine Anmeldung?
  7. Der Browser bekommt ein Einmal-Ticket, das 60 Sekunden gilt, tauscht es gegen eine normale FediSuite-Sitzung, und die Person ist drin. In der Adressleiste taucht nie ein Token auf.

FediSuite speichert das Passwort der Person beim Provider nicht, bekommt es nie zu sehen und erhält keinen Zugriff auf andere Anwendungen der Person.

4. Lohnt sich Single Sign-on für deine Instanz?

Es passt gut, wenn

  • du schon einen Identity-Provider betreibst und an einer zentralen Stelle Zugänge anlegen und entziehen willst, einschließlich Mehrfaktor-Anmeldung,
  • mehrere Menschen die Instanz nutzen, etwa ein Team oder eine Organisation,
  • du dich bei vielen selbst gehosteten Diensten mit demselben Konto anmelden willst.

Es bringt wenig, wenn

du die einzige Person auf deiner Instanz bist und noch keinen Provider hast. Dann ist der Passwort-Login von FediSuite einfacher, und der Provider wäre ein weiterer Dienst, der dauerhaft laufen muss.

Das solltest du vorher bedenken

  • Erreichbarkeit. Schaltest du den Passwort-Login aus und der Provider fällt aus, kann sich niemand anmelden, bis er wieder läuft. Den Notausstieg solltest du kennen.
  • Zwei-Faktor-Anmeldung. Wer sich über den Provider anmeldet, überspringt die Zwei-Faktor-Abfrage von FediSuite. Für die Mehrfaktor-Anmeldung ist dann dein Provider zuständig. Stelle dort sicher, dass er sie verlangt, wenn du dich darauf verlässt.
  • Android-App. Die FediSuite-Android-App meldet sich mit E-Mail und Passwort an. Schaltest du den Passwort-Login aus, können sich Menschen mit der App nicht mehr anmelden. Lass den Passwort-Login an, wenn die App genutzt wird.
  • Datenschutz. Der Provider erfährt, wann sich jemand bei deiner Instanz anmeldet. Deine Datenschutzerklärung muss das nennen, siehe Datenschutz.
  • Kein offener Anmeldemodus. FediSuite vertraut nur dem einen Provider, den du einträgst. Ein „Melde dich mit irgendeinem Provider an“ gibt es nicht.

5. Vorab: die Checkliste

  • FediSuite 2.4.0 oder neuer. Die Version zeigt dir docker compose exec -T app printenv VITE_APP_VERSION, oder du siehst im Changelog nach.
  • APP_URL stimmt. In der .env muss APP_URL die öffentliche Adresse deiner Instanz sein, zum Beispiel https://fedisuite.example.org, ohne Schrägstrich am Ende. Die Weiterleitungs-URL wird daraus gebildet. Eine falsche APP_URL ist der häufigste Grund für einen redirect_uri-Fehler beim Provider. Nach einer Änderung startest du die Container neu.
  • Der Provider ist vom FediSuite-Container aus erreichbar, nicht nur von deinem Browser. Steht der Provider in deinem eigenen Netz, brauchst du ALLOW_PRIVATE_INSTANCE_URLS=true in der .env. Reines http:// nimmt FediSuite nur mit diesem Schalter an, sonst muss der Issuer mit https:// beginnen.
  • Die Uhren gehen richtig. Server und Provider brauchen die korrekte Zeit (NTP). Eine Uhr, die Minuten abweicht, lässt das ID-Token abgelaufen oder noch nicht gültig aussehen.
  • Ein Backup liegt bereit. Führe ./scripts/backup.sh aus, wie unter Backup und Restore beschrieben. Die Einstellungen liegen in der Datenbank. Das Client-Secret ist mit ACCOUNT_ENCRYPTION_KEY verschlüsselt, deshalb gehört dieser Schlüssel wie bisher sicher aufbewahrt.
  • Du hast einen funktionierenden Admin-Zugang mit Passwort und am besten ein zweites Admin-Konto.
  • Deine Datenschutzerklärung ist geprüft. Siehe Datenschutz.
  • Du weißt, wie du Nutzer*innen beim Provider anlegst und ob ihre E-Mail-Adressen dort als bestätigt gelten, siehe In welchem Konto landet eine Anmeldung?

6. Die Einstellungen in FediSuite

Öffne Adminbereich → Einstellungen. Dort findest du die Karte Single Sign-on (OIDC).

Karte „Single Sign-on (OIDC)“ im Adminbereich unter Einstellungen. Sie enthält Weiterleitungs-URL, Issuer-URL, Client-ID, Client-Secret, Scopes, den Knopf „Verbindung testen“ und die Schalter für verifizierte E-Mail, Konten anlegen, Passwort-Login und Aktivierung.
Die Einstellungen für Single Sign-on im Adminbereich
Felder der Karte Single Sign-on (OIDC) mit Erklärung
FeldWas du einträgst und was es bewirkt
Weiterleitungs-URLHier trägst du nichts ein. Mit Kopieren übernimmst du die Adresse und registrierst genau sie beim Provider. Sie besteht aus APP_URL und /api/auth/oidc/callback.
Issuer-URLDie Adresse deines Providers, mit oder ohne den Zusatz /.well-known/openid-configuration. Du kannst die Adresse einfügen, die dein Provider als Konfigurationsadresse anzeigt. Sie muss mit dem Issuer in den Metadaten des Providers genau übereinstimmen. authentik verwendet einen Schrägstrich am Ende, Keycloak nicht. FediSuite probiert bei einer Abweichung einmal die andere Schreibweise und speichert die, die der Provider meldet.
Client-IDDie Client-ID vom Provider.
Client-AuthentifizierungWie sich FediSuite beim Provider ausweist. Client-Secret (HTTP Basic) ist die Voreinstellung und passt für die meisten Provider. Client-Secret (Request-Body) brauchst du, wenn dein Provider das Secret im Formular erwartet. Keine (Public Client, nur PKCE) ist für einen öffentlichen Client ohne Secret. Die Einstellung muss zur Einstellung des Clients beim Provider passen.
Client-SecretDas Secret vom Provider. Es wird verschlüsselt gespeichert und nie wieder angezeigt. Danach kannst du es mit Ersetzen austauschen oder mit Entfernen löschen.
ScopesVoreinstellung openid email profile. openid ist Pflicht. email braucht FediSuite, um Konten zuzuordnen oder anzulegen.
Verbindung testenLiest die Metadaten des Providers und zeigt den antwortenden Issuer. Meldet der Provider kein PKCE (S256), bekommst du eine Warnung. Erlaubt sind 10 Tests je 15 Minuten.
KnopftextOptional, zum Beispiel „Mit authentik anmelden“. Leer zeigt FediSuite einen allgemeinen Text.
Verifizierte E-Mail des Providers verlangenVoreinstellung: an. Dann lehnt FediSuite die Anmeldung ab, wenn der Provider die Adresse nicht als bestätigt meldet. Schalte das nur aus, wenn der Provider Adressen selbst prüft oder nur du dort Konten anlegst.
Bestehende Konten über bestätigte E-Mail-Adresse verknüpfenVoreinstellung: an. Die erste Anmeldung wird mit dem FediSuite-Konto mit derselben Adresse verknüpft, aber nur, wenn der Provider die Adresse als bestätigt meldet. Hat dieses Konto seine Adresse nie bestätigt, wird sein Passwort ersetzt und funktioniert nicht mehr.
Konten bei der ersten Anmeldung anlegenVoreinstellung: aus. Aus heißt: Nur wer schon ein Konto hat (oder dessen Adresse zu einem Konto passt), kommt hinein. An heißt: Alle, die der Provider durchlässt, bekommen ein normales Nutzerkonto.
Erlaubte E-Mail-DomainsOptional, durch Kommas getrennt, zum Beispiel example.org. Leer erlaubt jede Adresse, für die der Provider bürgt.
Passwort-Login abschaltenVoreinstellung: aus. Schaltet Passwort-Anmeldung, Registrierung und Passwort-Zurücksetzen ab. Das geht nur, solange Single Sign-on an ist und mindestens ein Admin mit dem Provider verknüpft ist.
Single Sign-on aktivierenVoreinstellung: aus. Zeigt den Knopf auf der Anmeldeseite.

Mit Single-Sign-on-Einstellungen speichern übernimmst du die Änderungen. Klicke vor dem Speichern auf Verbindung testen, sobald du den Issuer eingetragen hast.

7. Einrichtung mit authentik

Getestet mit authentik 2026.8.5. Die Menünamen können in anderen Versionen leicht abweichen.

In authentik

  1. Öffne die Admin-Oberfläche und gehe zu Applications → Applications → Create with Provider. Du kannst Provider und Anwendung auch getrennt anlegen.
  2. Gib der Anwendung einen Namen, zum Beispiel FediSuite, und notiere den Slug, zum Beispiel fedisuite. Der Slug wird Teil des Issuers.
  3. Wähle als Provider-Typ OAuth2/OpenID Provider.
  4. Stelle Folgendes ein:
    • Authorization flow: zum Beispiel default-provider-authorization-explicit-consent (fragt einmal nach) oder default-provider-authorization-implicit-consent (fragt nicht nach).
    • Client type: Confidential. Kopiere die angezeigte Client ID und das Client Secret.
    • Redirect URIs/Origins: trage die Weiterleitungs-URL aus FediSuite mit dem Abgleichsmodus Strict ein.
    • Signing Key: wähle einen Schlüssel, zum Beispiel das selbstsignierte Zertifikat, das authentik mitbringt. Dann werden ID-Tokens mit RS256 signiert. Ohne Schlüssel signiert authentik mit HS256 und dem Client-Secret. FediSuite akzeptiert das bei einem vertraulichen Client. Ein öffentlicher Client hat kein Secret zum Signieren, gib ihm deshalb einen Signing Key.
    • Scopes: openid, email, profile.
    • Grant types (ab authentik 2026.8): aktiviere Authorization Code. Ein Provider ohne diese Einstellung beantwortet jede Anmeldung mit invalid_request („Invalid grant_type for provider“).
  5. Speichere. Der Issuer lautet:
    https://authentik.example.org/application/o/<application-slug>/
    Mit dem Schrägstrich am Ende. authentik zeigt auf der Provider-Seite außerdem die OpenID Configuration URL. Diese Adresse kannst du ebenfalls in FediSuite einfügen.

Die Falle mit email_verified

Seit authentik 2025.10 meldet der Standard-Scope für E-Mail den Wert email_verified als false. Mit den Voreinstellungen von FediSuite endet dann jede Anmeldung mit „Der Provider hat deine E-Mail-Adresse noch nicht bestätigt“. Die Person kann das nicht selbst beheben, denn authentik kennt für von Admins angelegte Nutzer*innen keinen Bestätigungsschritt. Du hast drei Möglichkeiten:

  1. Die Adresse per Scope-Mapping als bestätigt markieren. Das empfiehlt sich, wenn du die Nutzer*innen selbst anlegst und den Adressen vertraust. Gehe in authentik zu Customization → Property Mappings → Create → Scope Mapping, vergib den Scope-Namen email und diesen Ausdruck:
    return {
        "email": request.user.email,
        "email_verified": True,
    }
    Bearbeite dann den Provider und ersetze das Standard-Mapping für email durch dein neues. Tu das nur, wenn jede E-Mail-Adresse in authentik wirklich geprüft ist, etwa weil nur Administrator*innen Nutzer*innen anlegen.
  2. In FediSuite „Verifizierte E-Mail des Providers verlangen“ ausschalten. Dann können neue Konten auch aus unbestätigten Adressen entstehen. Bestehende FediSuite-Konten werden aber nie über eine unbestätigte Adresse verknüpft. Diese Menschen melden sich einmal mit ihrem Passwort an und verknüpfen den Provider in ihren Kontoeinstellungen, siehe Was deine Nutzer*innen sehen.
  3. authentik die Adressen prüfen lassen, mit einem Enrollment-Flow, der eine Bestätigungsmail verschickt und den Wert setzt.

In FediSuite

Trage Issuer, Client-ID und Client-Secret ein, lass die Client-Authentifizierung auf HTTP Basic, klicke auf Verbindung testen und dann auf Speichern.

Den Subject mode später nicht mehr ändern

Die authentik-Einstellung Subject mode bestimmt, wie die dauerhafte Nutzer-ID aussieht. Ändere sie nicht, nachdem sich Menschen angemeldet haben. Die ID wechselt, verknüpfte Konten passen nicht mehr, und die Anmeldung endet mit account_conflict, bis die Person die alte Verknüpfung entfernt und den Provider in den Kontoeinstellungen neu verknüpft. Das geht nur, solange der Passwort-Login an ist.

8. Einrichtung mit Keycloak

Getestet mit Keycloak 26.6. Der Issuer lautet https://keycloak.example.org/realms/<realm>, bei aktuellen Keycloak-Versionen ohne /auth.

In Keycloak

  1. Wähle deinen Realm und gehe zu Clients → Create client.
  2. Client type: OpenID Connect. Client ID: zum Beispiel fedisuite. Klicke auf Next.
  3. Capability config: schalte Client authentication auf On. Unter Authentication flow lässt du Standard flow an, die anderen Abläufe können aus bleiben. Klicke auf Next.
  4. Login settings: trage die Weiterleitungs-URL von FediSuite unter Valid redirect URIs ein und klicke auf Save.
  5. Öffne den Reiter Credentials und kopiere das Client secret.
  6. Achte darauf, dass die Nutzer*innen eine E-Mail-Adresse haben und Email verified gesetzt ist, siehe nächster Absatz.

Bestätigte E-Mail-Adressen in Keycloak

email_verified folgt dem Schalter Email verified der einzelnen Nutzer*in (Users → Nutzer*in → Email verified). Du kannst Nutzer*innen von Hand als bestätigt markieren, im Realm die E-Mail-Bestätigung einschalten, damit Menschen ihre Adresse selbst bestätigen, oder in FediSuite Verifizierte E-Mail des Providers verlangen ausschalten, wenn nur du die Nutzer*innen anlegst.

In FediSuite

Trage https://keycloak.example.org/realms/<realm> als Issuer ein, dazu die Client-ID (fedisuite) und das Secret. Lass die Client-Authentifizierung auf HTTP Basic, klicke auf Verbindung testen und dann auf Speichern.

9. Andere Provider

Andere Provider wie Authelia, Zitadel, Microsoft Entra ID oder Google sollten funktionieren, wenn sie

  • ein OpenID-Connect-Konfigurationsdokument veröffentlichen (.well-known/openid-configuration),
  • den Authorization-Code-Ablauf unterstützen,
  • es erlauben, die Weiterleitungs-URL genau so zu registrieren,
  • ID-Tokens asymmetrisch signieren, zum Beispiel mit RS256 (bei einem vertraulichen Client geht auch HS256),
  • sub liefern und zum Zuordnen von Konten email, am besten mit email_verified.

Diese Provider hat das FediSuite-Projekt nicht getestet. Die Schritte sind immer dieselben: einen vertraulichen Client registrieren, die Weiterleitungs-URL eintragen, Client-ID und Secret kopieren, in FediSuite den Issuer setzen und auf Verbindung testen klicken.

10. In welchem Konto landet eine Anmeldung?

Nach einer erfolgreichen Anmeldung beim Provider entscheidet FediSuite in dieser Reihenfolge:

  1. Die Identität ist schon verknüpft. Das Paar aus Issuer und Subject ist bekannt: Die Person landet im verknüpften FediSuite-Konto. Die E-Mail-Adresse spielt dann keine Rolle mehr.
  2. Die E-Mail-Adresse passt zu einem bestehenden FediSuite-Konto. Hier entscheiden die Einstellungen aus der Tabelle unten.
  3. Es gibt noch kein Konto. Hier entscheidet Konten bei der ersten Anmeldung anlegen.

Bestehende Konten werden nie über eine Adresse verknüpft, die der Provider nicht bestätigt hat. Diese Regel lässt sich nicht abschalten. Sie schützt vor jemandem, der beim Provider ein Nutzerkonto mit einer fremden Adresse anlegt und so das FediSuite-Konto der eigentlichen Besitzer*in übernimmt.

Das passiert bei der ersten Anmeldung einer Person, die noch nicht verknüpft ist:

Ergebnis der ersten Anmeldung je nach Meldung des Providers und Einstellungen
Der Provider meldet die Adresse als Konto mit dieser Adresse vorhanden? Verifizierte E-Mail verlangen Über bestätigte E-Mail verknüpfen Konten anlegen Ergebnis
bestätigtjaan oder ausanegalAngemeldet, die Identität wird verknüpft.
bestätigtjaan oder ausausegalaccount_conflict. Die Person verknüpft den Provider in den Kontoeinstellungen.
bestätigtneinegalegalanEin neues Konto entsteht, die Person ist angemeldet.
bestätigtneinegalegalausno_account
nicht bestätigtjaanegalegalemail_unverified
nicht bestätigtjaausegalegalaccount_conflict. Die Person verknüpft den Provider in den Kontoeinstellungen.
nicht bestätigtneinanegalegalemail_unverified
nicht bestätigtneinausegalanEin neues Konto entsteht, die Person ist angemeldet.
nicht bestätigtneinausegalausno_account
gar keine Adresseegalegalegalegalemail_missing
Adresse außerhalb der erlaubten Domainsegalegalegalegaldomain_not_allowed

Weitere Regeln:

  • Rollen kommen nie vom Provider. Neue Konten sind immer normale Nutzer*innen. Admins behalten ihre Rolle in FediSuite, und niemand wird über den Provider zum Admin.
  • Konten, die ihre Adresse nie bestätigt haben. Wurde ein Konto registriert, aber nie bestätigt, und passt eine vom Provider bestätigte Adresse, wird das Konto übernommen: Das Passwort wird durch ein unbrauchbares ersetzt, und das Konto gilt als bestätigt. Deshalb ist die Einstellung eine bewusste Entscheidung.
  • Groß- und Kleinschreibung spielt keine Rolle. Eve@Lab.TEST beim Provider findet eve@lab.test in FediSuite.
  • Eine Verknüpfung je Provider. Ein FediSuite-Konto kann mit einer Identität je Issuer verknüpft sein, und eine Provider-Identität gehört zu einem FediSuite-Konto (sonst link_taken).
  • Die Verknüpfung gehört zum Issuer. Trägst du später einen anderen Issuer ein, ist niemand mehr verknüpft, siehe Wartung und Änderungen.

11. Einführung in der sicheren Reihenfolge

In der falschen Reihenfolge eingeschaltet, kann dich Single Sign-on aussperren. Gehe so vor:

  1. Backup machen (Backup und Restore).
  2. Den Client beim Provider registrieren und Issuer, Client-ID und Secret notieren.
  3. Adminbereich → Einstellungen öffnen, die Karte ausfüllen, auf Verbindung testen klicken und das Ergebnis lesen. Es muss den Issuer deines Providers zeigen.
  4. Speichern, mit eingeschaltetem „Single Sign-on aktivieren“ und weiterhin eingeschaltetem Passwort-Login. Öffne die Anmeldeseite in einem privaten Browserfenster. Der Single-Sign-on-Knopf muss erscheinen.
  5. Dein eigenes Admin-Konto verknüpfen. Melde dich mit deinem Passwort an, öffne die Kontoeinstellungen, suche die Karte Single Sign-on und klicke auf Konto verknüpfen. Melde dich beim Provider an.
  6. Die echte Anmeldung testen. Melde dich ab und mit dem Knopf wieder an. Du musst in deinem eigenen Konto landen.
  7. Mit einer normalen Nutzer*in testen, die keine Admin-Rechte hat, am besten auch mit einer Person, deren Adresse der Provider nicht bestätigt hat. So siehst du, welche Meldung die Menschen bekommen.
  8. Erst dann, wenn du willst, den Passwort-Login abschalten. Der Schalter funktioniert nur, solange mindestens ein Admin verknüpft ist.
  9. Deine Nutzer*innen informieren und sagen, was sich ändert, siehe Was deine Nutzer*innen sehen.

Der Notausstieg

Kommst du nicht mehr hinein, weil der Provider ausgefallen ist, das Secret abgelaufen ist oder der Passwort-Login aus ist und der Provider nicht antwortet, schaltest du den Passwort-Login vom Server aus wieder ein:

  1. Setze in der .env die Zeile OIDC_PASSWORD_LOGIN_OVERRIDE=true.
  2. Starte die Container neu: docker compose up -d.
  3. Melde dich mit deinem Passwort an. Die Admin-Seite zeigt einen Hinweis, dass der Notausstieg aktiv ist.
  4. Korrigiere die Einstellungen (oder schalte den Passwort-Login wieder ein), entferne die Variable aus der .env und starte erneut.

Der Notausstieg bringt nur den Passwort-Login zurück. Die gespeicherten Einstellungen ändert er nicht. Setze die Variable nur, solange du sie brauchst. Alle Variablen im Überblick findest du unter Umgebungsvariablen.

12. Was deine Nutzer*innen sehen

  • Anmeldeseite. Bei eingeschaltetem Single Sign-on erscheint unter dem Passwortformular ein Knopf („Mit Single Sign-on anmelden“ oder dein eigener Knopftext). Bei abgeschaltetem Passwort-Login zeigt die Seite nur noch den Knopf.
  • Anmelden. Ein Klick, dann die Anmeldung beim Provider (mit dem zweiten Faktor, falls er danach fragt), dann FediSuite.
  • Bestehende Konten. Je nach deinen Einstellungen werden Menschen bei der ersten Anmeldung automatisch verknüpft (bestätigte Adresse) oder melden sich einmal mit dem Passwort an und verknüpfen ihr Konto in den Kontoeinstellungen unter Single Sign-on → Konto verknüpfen. Danach können sie den Knopf nutzen.
  • Verknüpfung entfernen. Mit Verknüpfung entfernen an derselben Stelle. Das geht nicht, solange der Passwort-Login abgeschaltet ist, weil sich die Person sonst aussperren könnte.
  • Passwörter. Das FediSuite-Passwort bleibt gültig, solange der Passwort-Login an ist. Mit Single Sign-on braucht die Person es nicht.
  • Zwei-Faktor-Anmeldung. Die FediSuite-eigene Zwei-Faktor-Abfrage entfällt bei der Anmeldung über den Provider. Es gilt, was der Provider verlangt.
  • Android-App. Die App meldet sich mit E-Mail und Passwort an. Lass den Passwort-Login an, wenn Menschen die App nutzen.
  • Meldungen. Geht etwas schief, zeigt die Anmeldeseite eine verständliche Meldung, zum Beispiel „Der Provider hat deine E-Mail-Adresse noch nicht bestätigt“. Die zugehörigen Codes stehen unter Fehler und Lösungen.

Konten ohne Passwort

Legt Single Sign-on ein Konto an oder übernimmt es, weil die Adresse nie bestätigt war, bekommt dieses Konto ein zufälliges Passwort, das niemand kennt. Die Person braucht es auch nicht, denn sie meldet sich beim Provider an. Nur an wenigen Stellen fragt FediSuite sonst nach dem aktuellen Passwort: beim Löschen des Kontos, beim Ändern der E-Mail-Adresse oder des Passworts und beim Umzug (Export und Import). Für solche Konten gibt es dort eine Bestätigung mit Single Sign-on statt des Passwortfelds.

  1. Im Formular steht dort, wo sonst das Passwortfeld wäre, der Knopf Mit Single Sign-on bestätigen.
  2. Die Person wird zum Provider geschickt und muss sich dort noch einmal anmelden, auch wenn beim Provider noch eine Sitzung läuft. Die Anmeldung darf höchstens zwei Minuten alt sein, und es muss dieselbe Person sein, die mit dem Konto verknüpft ist. Dafür verlangt FediSuite prompt=login und prüft auth_time im ID-Token.
  3. FediSuite bringt die Person zurück auf die Seite, von der sie kam. Das Formular zeigt, dass bestätigt ist, und die Person schließt den Schritt innerhalb von 5 Minuten ab. Jede Bestätigung gilt für genau einen Schritt.
  • Ein Passwort lässt sich festlegen. Mit derselben Bestätigung legt die Person unter Einstellungen → Account → Passwort ändern ein Passwort fest. Danach ist das Konto ein normales Konto, und die Android-App kann sich damit anmelden, solange der Passwort-Login an ist.
  • Die Verknüpfung lässt sich nicht lösen, solange das Konto kein Passwort hat, weil die Person sonst den Zugang verlöre.
  • Zwei-Faktor-Anmeldung von FediSuite gibt es für Konten ohne Passwort nicht. Der Provider ist für den zweiten Faktor zuständig. Wer zuerst ein Passwort festlegt, bekommt die Einstellungen.
  • Der Provider muss mitspielen. Er muss bei prompt=login erneut nach den Zugangsdaten fragen und auth_time mitschicken. Keycloak 26.6 und authentik 2026.8.5 tun beides. Sonst endet die Bestätigung mit „Die Bestätigung beim Anbieter hat nicht geklappt“, und die Person holt sich über „Passwort vergessen“ ein Passwort, solange der Passwort-Login an ist.
Karte „Single Sign-on“ in den Kontoeinstellungen mit dem Hinweis, dass das Konto noch nicht mit dem Anmelde-Provider verknüpft ist, und dem Knopf „Konto verknüpfen“.
Konto in den Kontoeinstellungen mit dem Provider verknüpfen

13. So sicher ist das

Das macht FediSuite bei jeder Anmeldung:

  • Authorization-Code-Ablauf mit PKCE (S256), state und nonce. Der Anmeldecode nützt niemandem etwas ohne den Code-Verifier, den nur FediSuite kennt.
  • Prüfung des ID-Tokens durch eine zertifizierte Bibliothek (openid-client, die auf jose aufbaut): Signatur (gegen die veröffentlichten Schlüssel des Providers), Aussteller, Empfänger, Ablaufzeit und Nonce. Eine selbst gebastelte Token-Auswertung gibt es nicht.
  • Bindung an den Browser. Ein Cookie hängt die Anmeldung an den Browser, der sie gestartet hat. Eine Anmeldung, die in einem Browser beginnt, lässt sich in einem anderen nicht abschließen (Fehler state). Das verhindert Login-CSRF.
  • Einmalwerte. Der state gilt 10 Minuten und genau einmal. Das Sitzungs-Ticket gilt 60 Sekunden und genau einmal. Kein Token erscheint in der Adresse.
  • Ein vertrauter Issuer. FediSuite spricht nur mit dem Provider, den du eingetragen hast. Ein ID-Token eines anderen Ausstellers wird abgelehnt.
  • Keine Rollen aus Claims. Admin-Rechte vergibt der Provider nie.
  • Keine Verknüpfung über unbestätigte Adressen. Siehe In welchem Konto landet eine Anmeldung?
  • Bestätigungs-Tickets. Das Ticket einer Bestätigung mit Single Sign-on gilt 5 Minuten, nur für die angemeldete Sitzung derselben Person, nur solange das Konto kein Passwort hat und nur einmal.
  • Begrenzungen. 60 Anmeldeanfragen je 15 Minuten und Adresse, 10 Verbindungstests je 15 Minuten und Admin. Wer die Grenze erreicht, sieht rate_limited.
  • Regeln für ausgehende Verbindungen. Anfragen an den Provider laufen durch dieselben Regeln wie andere externe Anfragen. Private und lokale Adressen sind gesperrt, solange du ALLOW_PRIVATE_INSTANCE_URLS=true nicht setzt. Reines http:// gibt es nur mit diesem Schalter.
  • Umgang mit dem Secret. Das Client-Secret liegt verschlüsselt in der Datenbank, die API gibt es nie zurück, und es wird nicht protokolliert. Logzeilen mit dem Kürzel [OIDC] enthalten keine Secrets oder Tokens.
  • Protokoll. Erfolgreiche und abgelehnte Anmeldungen, Verknüpfen, Trennen und Änderungen der Einstellungen landen im Audit-Log.

Das bleibt deine Aufgabe:

  • Die Sicherheit des Providers selbst: starke Passwörter oder Passkeys, Mehrfaktor-Anmeldung, Updates und wer Nutzer*innen anlegen darf.
  • Wer beim Provider Konten anlegen darf und mit welchen E-Mail-Adressen. Ist Verifizierte E-Mail des Providers verlangen aus, kann jemand, der beim Provider Nutzer*innen anlegen darf, eine fremde Adresse für ein neues FediSuite-Konto beanspruchen.
  • Den Schlüssel ACCOUNT_ENCRYPTION_KEY sicher aufzubewahren.

14. Datenschutz

  • Was FediSuite speichert. Bei einer verknüpften Person: den Issuer, die dauerhafte Subject-ID, die E-Mail-Adresse und den Zeitpunkt der letzten Anmeldung. Einen Namen oder ein Bild vom Provider speichert FediSuite nicht.
  • Was der Provider erfährt. Dass sich jemand bei deiner Instanz anmeldet, wann, aus welchem Browser, und die Adresse deiner Instanz.
  • Was der Provider schickt. E-Mail-Adresse, ob sie bestätigt ist, die Subject-ID und mit dem Scope profile Namensangaben, die FediSuite nicht speichert.
  • Deine Datenschutzerklärung. Die Vorlage unter Adminbereich → Rechtstexte nennt den Provider und beschreibt den Datenfluss, solange Single Sign-on an ist. Einen eigenen Text ändert FediSuite nicht automatisch. Prüfe ihn und ergänze den Provider, wenn du einen eigenen Text verwendest.
  • Die Datenschutzhinweise des Providers gelten auf seiner Seite. Betreibst du ihn selbst, entscheidest du darüber.

15. Fehler und Lösungen

Meldungen auf der Anmeldeseite

Fehlercodes der Anmeldung mit Meldung, Ursache und Lösung
CodeMeldung an die PersonTypische Ursache und Lösung
deniedDer Provider hat die Anmeldung nicht erlaubt.Die Person oder der Provider hat abgebrochen. Erneut versuchen.
stateDie Anmeldung ist abgelaufen oder wurde schon benutzt.Sie dauerte länger als 10 Minuten, wurde doppelt benutzt oder in einem anderen Browser beendet als gestartet. Neu starten.
failedDie Anmeldung konnte nicht abgeschlossen werden.Der Provider hat mit einem Fehler oder einem ungültigen ID-Token geantwortet. Lies das Log (siehe unten).
disabledSingle Sign-on ist auf dieser Instanz abgeschaltet.Der Schalter ist aus.
email_missingDer Provider hat keine E-Mail-Adresse geschickt.Trage beim Provider eine Adresse für die Person ein und stelle sicher, dass der Scope email erlaubt ist.
email_unverifiedDer Provider hat deine E-Mail-Adresse noch nicht bestätigt.Der Provider meldet email_verified=false, während FediSuite eine Bestätigung verlangt. Markiere die Adresse beim Provider als bestätigt (siehe die Abschnitte zu authentik und Keycloak) oder schalte die Pflicht in FediSuite aus.
domain_not_allowedDie Domain deiner E-Mail-Adresse ist auf dieser Instanz nicht erlaubt.Trage die Domain unter Erlaubte E-Mail-Domains ein oder leere die Liste.
no_accountZu dieser Anmeldung gehört kein FediSuite-Konto.Lege ein Konto an oder verknüpfe eines, oder schalte Konten bei der ersten Anmeldung anlegen ein.
account_conflictDie E-Mail-Adresse gehört zu einem Konto, das sich nicht automatisch verknüpfen lässt.Mit dem Passwort anmelden und unter Single Sign-on → Konto verknüpfen verknüpfen. Der Code erscheint auch nach einem geänderten Subject mode.
link_takenDieses Provider-Konto ist schon mit einem anderen FediSuite-Konto verknüpft.Die Person ist schon anderswo verknüpft. Ein Admin muss diese Verknüpfung entfernen.
rate_limitedZu viele Anmeldeversuche.Ein paar Minuten warten.
reauth_failedDie Bestätigung beim Anbieter hat nicht geklappt.Die Person hat sich als andere Identität angemeldet, die Anmeldung war älter als zwei Minuten, oder der Provider unterstützt prompt=login und auth_time nicht. Noch einmal versuchen; sonst über „Passwort vergessen“ ein Passwort holen.

Das Log lesen

docker compose logs --since 15m app | grep OIDC

Typische Einträge und was sie bedeuten:

Typische Einträge im Log oder beim Provider mit ihrer Ursache
Im Log oder beim ProviderUrsache
discovered metadata issuer does not match the expected issuerDer Issuer, den du eingetragen hast, weicht von dem ab, den der Provider meldet (Schrägstrich am Ende, http statt https, anderer Hostname). Nimm die Adresse aus dem Konfigurationsdokument des Providers.
Provider-Seite „Redirect URI mismatch“ oder redirect_uri-FehlerDie Weiterleitungs-URL beim Provider ist nicht genau die, die FediSuite anzeigt. Prüfe APP_URL und die eingetragene Adresse (in authentik Abgleichsmodus Strict).
authentik invalid_request, „Invalid grant_type for provider“Beim Provider ist der Grant Type Authorization Code nicht aktiviert.
invalid_client oder Token-Anfrage mit 401 beantwortetFalsches Client-Secret oder falsche Einstellung bei Client-Authentifizierung.
ID-Token abgelehnt, „unsupported algorithm“Der Provider signiert mit einem Verfahren, das FediSuite nicht gegen seine Schlüssel prüfen kann. Setze beim Provider einen Signing Key (RS256).
ID-Token abgelaufen oder „noch nicht gültig“Die Uhren von Server und Provider gehen unterschiedlich. Richte NTP ein.
„The provider address is not allowed by the outbound policy“Der Provider steht in einem privaten Netz. Setze ALLOW_PRIVATE_INSTANCE_URLS=true.
Verbindungstest: „…nicht erreichbar oder bietet keine nutzbare OpenID-Connect-Konfiguration“Falsche Adresse, der Provider ist aus dem Container nicht erreichbar, oder es gibt kein Konfigurationsdokument. Teste vom Server aus, siehe unten.

Den Provider vom Server aus testen

docker compose exec -T app node -e "fetch('https://auth.example.org/application/o/fedisuite/.well-known/openid-configuration').then(r => r.json()).then(j => console.log(j.issuer, j.authorization_endpoint))"

Gibt der Befehl den Issuer und den Authorization-Endpoint aus, erreicht der Container den Provider. Der ausgegebene Issuer ist genau der, den FediSuite erwartet.

16. Wartung und Änderungen

  • Client-Secret erneuern. Erzeuge beim Provider ein neues Secret, öffne Adminbereich → Einstellungen, klicke beim Secret auf Ersetzen, gib das neue ein und speichere.
  • Den Issuer ändern. Die Verknüpfungen gehören zum Issuer. Nach einer Änderung (auch nur der Schreibweise, etwa mit und ohne Schrägstrich am Ende) passen die bestehenden Verknüpfungen nicht mehr. Die Menschen melden sich dann mit dem Passwort an und verknüpfen neu. Plane das vor der Änderung.
  • Zu einem anderen Provider umziehen. Lass den Passwort-Login während des Umzugs an, ändere Issuer und Zugangsdaten, lass die Menschen neu verknüpfen und schalte den Passwort-Login danach bei Bedarf aus.
  • Single Sign-on ausschalten. Schalte Single Sign-on aktivieren aus. Die Verknüpfungen bleiben in der Datenbank. War der Passwort-Login aus, schalte ihn vorher wieder ein oder nutze den Notausstieg.
  • Ein Backup einspielen. Die Einstellungen gehören zur Datenbank. Das Secret braucht den ACCOUNT_ENCRYPTION_KEY, mit dem das Backup entstanden ist. Ist der Schlüssel verloren, trägst du das Client-Secret neu ein.
  • Updates. Provider-Updates können Voreinstellungen ändern (authentik 2025.10 hat email_verified geändert). Klicke nach einem Provider-Update auf Verbindung testen und melde dich einmal an.

17. Häufige Fragen

Brauche ich Single Sign-on, um FediSuite zu nutzen?
Nein. Der Passwort-Login funktioniert weiter und bleibt die Voreinstellung.
Können Menschen nach dem Einschalten noch ihr Passwort benutzen?
Ja, bis du den Passwort-Login abschaltest.
Kann ich mehrere Provider gleichzeitig nutzen?
Nein. FediSuite verwendet einen Provider je Instanz.
Kann ich Google-, Apple- oder Microsoft-Konten verwenden?
Technisch funktioniert jeder Provider, der OIDC spricht. Zentrale Verbraucher-Logins empfiehlt FediSuite nicht und bietet sie nicht fertig an. Das Projekt setzt auf digitale Unabhängigkeit.
Wer wird Admin?
Niemand über den Provider. Admins legst du in FediSuite fest.
Was passiert, wenn ich jemanden beim Provider entferne?
Die Person kann sich nicht mehr über den Provider anmelden. Eine bestehende Sitzung in FediSuite bleibt gültig, bis sie abläuft, und das Konto samt Passwort (falls der Login an ist) bleibt bestehen. Entferne oder deaktiviere das Konto auch in FediSuite.
Was passiert, wenn sich die E-Mail-Adresse beim Provider ändert?
Eine verknüpfte Person kann sich weiter anmelden, denn die Verknüpfung nutzt die dauerhafte Subject-ID und nicht die Adresse.
Fragt FediSuite den Provider später noch einmal?
Nein. Der Provider wird nur gefragt, während sich jemand anmeldet. FediSuite legt keinen Refresh-Token an.
Funktioniert das hinter Traefik oder einem anderen Reverse Proxy?
Ja. Setze APP_URL auf die öffentliche Adresse und sorge dafür, dass der Container den Provider erreicht. Mehr zum Proxy steht unter Reverse Proxy.

18. Was getestet wurde

Die Funktion wurde in einer abgeschotteten virtuellen Maschine gegen echte Provider getestet: authentik 2026.8.5 und Keycloak 26.6.

  • Getestete Fälle: Verbindungstest, Anmeldung über eine verknüpfte Identität, Verknüpfen über die bestätigte E-Mail-Adresse, unbestätigte Adresse, Kontoanlage an und aus, erlaubte Domains, falsches Secret, client_secret_post, öffentlicher Client mit PKCE (authentik), E-Mail-Adresse in gemischter Schreibweise, Nutzer*in ohne E-Mail-Adresse, Anmeldung in einem anderen Browser beendet, Verknüpfen und Trennen in den Kontoeinstellungen, link_taken, abgeschalteter Passwort-Login mit seinen Ablehnungen, der Notausstieg und der Admin-Dialog.
  • Konten ohne Passwort: Bestätigung mit Single Sign-on für Konto löschen, E-Mail-Adresse ändern und Passwort festlegen im Browser sowie Import freigeben auf API-Ebene, mit Keycloak 26.6 und authentik 2026.8.5, samt zu alter Anmeldung, anderer Identität, abgelaufenem und wiederverwendetem Ticket.
  • Nicht getestet: authentik vor 2026.8, die Android-App, andere Provider und ein Screenreader auf der Einstellungskarte.

Fragen und Fehlerberichte gehören ins Support-Forum.