Für Betreiber*innen selbst gehosteter Instanzen
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.
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 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.
Auf dieser Seite
- Die Kurzfassung
- Was ist das? Die Begriffe in einfachen Worten
- So läuft eine Anmeldung ab
- Lohnt sich Single Sign-on für deine Instanz?
- Vorab: die Checkliste
- Die Einstellungen in FediSuite
- Einrichtung mit authentik
- Einrichtung mit Keycloak
- Andere Provider
- In welchem Konto landet eine Anmeldung?
- Einführung in der sicheren Reihenfolge
- Was deine Nutzer*innen sehen
- So sicher ist das
- Datenschutz
- Fehler und Lösungen
- Wartung und Änderungen
- Häufige Fragen
- Was getestet wurde
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=truein der.env, siehe Notausstieg.
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.
| Begriff | Bedeutung |
|---|---|
| Identity-Provider | Der 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. |
| Issuer | Die Webadresse, die deinen Provider (oder eine Anwendung bzw. einen Realm darin) eindeutig bezeichnet. Von dort aus findet FediSuite alles Weitere selbst. |
| Client | Aus Sicht des Providers ist FediSuite ein Client, in manchen Oberflächen auch Anwendung genannt. Du registrierst ihn einmal beim Provider. |
| Client-ID und Client-Secret | Eine 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-URL | Die 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. |
| Scopes | Die Arten von Informationen, nach denen FediSuite fragt. openid ist Pflicht, email braucht FediSuite zum Zuordnen der Konten, profile sind die üblichen Namensangaben. |
| Claims | Die 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-Token | Eine signierte Nachricht des Providers, die sagt, wer sich angemeldet hat. FediSuite prüft Signatur, Aussteller, Empfänger, Ablaufzeit und einen Einmalwert (nonce). |
| PKCE | Ein 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
- Die Person öffnet die Anmeldeseite von FediSuite und klickt auf den Single-Sign-on-Knopf.
- 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.
- Die Person meldet sich beim Provider an, mit dem, was der Provider verlangt: Passwort, Passkey, zweiter Faktor.
- Der Provider schickt den Browser mit einem kurzlebigen Code zurück zur Weiterleitungs-URL von FediSuite.
- 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.
- FediSuite entscheidet, welches FediSuite-Konto zu dieser Identität gehört, siehe In welchem Konto landet eine Anmeldung?
- 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_URLstimmt. In der.envmussAPP_URLdie öffentliche Adresse deiner Instanz sein, zum Beispielhttps://fedisuite.example.org, ohne Schrägstrich am Ende. Die Weiterleitungs-URL wird daraus gebildet. Eine falscheAPP_URList der häufigste Grund für einenredirect_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=truein der.env. Reineshttp://nimmt FediSuite nur mit diesem Schalter an, sonst muss der Issuer mithttps://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.shaus, wie unter Backup und Restore beschrieben. Die Einstellungen liegen in der Datenbank. Das Client-Secret ist mitACCOUNT_ENCRYPTION_KEYverschlü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).
| Feld | Was du einträgst und was es bewirkt |
|---|---|
| Weiterleitungs-URL | Hier 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-URL | Die 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-ID | Die Client-ID vom Provider. |
| Client-Authentifizierung | Wie 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-Secret | Das Secret vom Provider. Es wird verschlüsselt gespeichert und nie wieder angezeigt. Danach kannst du es mit Ersetzen austauschen oder mit Entfernen löschen. |
| Scopes | Voreinstellung openid email profile. openid ist Pflicht. email braucht FediSuite, um Konten zuzuordnen oder anzulegen. |
| Verbindung testen | Liest 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. |
| Knopftext | Optional, zum Beispiel „Mit authentik anmelden“. Leer zeigt FediSuite einen allgemeinen Text. |
| Verifizierte E-Mail des Providers verlangen | Voreinstellung: 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üpfen | Voreinstellung: 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 anlegen | Voreinstellung: 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-Domains | Optional, durch Kommas getrennt, zum Beispiel example.org. Leer erlaubt jede Adresse, für die der Provider bürgt. |
| Passwort-Login abschalten | Voreinstellung: 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 aktivieren | Voreinstellung: 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
- Öffne die Admin-Oberfläche und gehe zu Applications → Applications → Create with Provider. Du kannst Provider und Anwendung auch getrennt anlegen.
- Gib der Anwendung einen Namen, zum Beispiel
FediSuite, und notiere den Slug, zum Beispielfedisuite. Der Slug wird Teil des Issuers. - Wähle als Provider-Typ OAuth2/OpenID Provider.
- Stelle Folgendes ein:
- Authorization flow: zum Beispiel
default-provider-authorization-explicit-consent(fragt einmal nach) oderdefault-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“).
- Authorization flow: zum Beispiel
- Speichere. Der Issuer lautet:
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.https://authentik.example.org/application/o/<application-slug>/
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:
- 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
emailund diesen Ausdruck:
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.return { "email": request.user.email, "email_verified": True, } - 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.
- 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
- Wähle deinen Realm und gehe zu Clients → Create client.
- Client type: OpenID Connect. Client ID: zum Beispiel
fedisuite. Klicke auf Next. - 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.
- Login settings: trage die Weiterleitungs-URL von FediSuite unter Valid redirect URIs ein und klicke auf Save.
- Öffne den Reiter Credentials und kopiere das Client secret.
- 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),
subliefern und zum Zuordnen von Kontenemail, am besten mitemail_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:
- 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.
- Die E-Mail-Adresse passt zu einem bestehenden FediSuite-Konto. Hier entscheiden die Einstellungen aus der Tabelle unten.
- 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:
| 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ätigt | ja | an oder aus | an | egal | Angemeldet, die Identität wird verknüpft. |
| bestätigt | ja | an oder aus | aus | egal | account_conflict. Die Person verknüpft den Provider in den Kontoeinstellungen. |
| bestätigt | nein | egal | egal | an | Ein neues Konto entsteht, die Person ist angemeldet. |
| bestätigt | nein | egal | egal | aus | no_account |
| nicht bestätigt | ja | an | egal | egal | email_unverified |
| nicht bestätigt | ja | aus | egal | egal | account_conflict. Die Person verknüpft den Provider in den Kontoeinstellungen. |
| nicht bestätigt | nein | an | egal | egal | email_unverified |
| nicht bestätigt | nein | aus | egal | an | Ein neues Konto entsteht, die Person ist angemeldet. |
| nicht bestätigt | nein | aus | egal | aus | no_account |
| gar keine Adresse | egal | egal | egal | egal | email_missing |
| Adresse außerhalb der erlaubten Domains | egal | egal | egal | egal | domain_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.TESTbeim Provider findeteve@lab.testin 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:
- Backup machen (Backup und Restore).
- Den Client beim Provider registrieren und Issuer, Client-ID und Secret notieren.
- Adminbereich → Einstellungen öffnen, die Karte ausfüllen, auf Verbindung testen klicken und das Ergebnis lesen. Es muss den Issuer deines Providers zeigen.
- 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.
- 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.
- Die echte Anmeldung testen. Melde dich ab und mit dem Knopf wieder an. Du musst in deinem eigenen Konto landen.
- 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.
- Erst dann, wenn du willst, den Passwort-Login abschalten. Der Schalter funktioniert nur, solange mindestens ein Admin verknüpft ist.
- 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:
- Setze in der
.envdie ZeileOIDC_PASSWORD_LOGIN_OVERRIDE=true. - Starte die Container neu:
docker compose up -d. - Melde dich mit deinem Passwort an. Die Admin-Seite zeigt einen Hinweis, dass der Notausstieg aktiv ist.
- Korrigiere die Einstellungen (oder schalte den Passwort-Login wieder ein), entferne die Variable aus der
.envund 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.
- Im Formular steht dort, wo sonst das Passwortfeld wäre, der Knopf Mit Single Sign-on bestätigen.
- 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=loginund prüftauth_timeim ID-Token. - 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=loginerneut nach den Zugangsdaten fragen undauth_timemitschicken. 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.
13. So sicher ist das
Das macht FediSuite bei jeder Anmeldung:
- Authorization-Code-Ablauf mit PKCE (S256),
stateundnonce. 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 aufjoseaufbaut): 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
stategilt 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=truenicht setzt. Reineshttp://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_KEYsicher 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
profileNamensangaben, 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
| Code | Meldung an die Person | Typische Ursache und Lösung |
|---|---|---|
denied | Der Provider hat die Anmeldung nicht erlaubt. | Die Person oder der Provider hat abgebrochen. Erneut versuchen. |
state | Die 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. |
failed | Die Anmeldung konnte nicht abgeschlossen werden. | Der Provider hat mit einem Fehler oder einem ungültigen ID-Token geantwortet. Lies das Log (siehe unten). |
disabled | Single Sign-on ist auf dieser Instanz abgeschaltet. | Der Schalter ist aus. |
email_missing | Der 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_unverified | Der 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_allowed | Die 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_account | Zu 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_conflict | Die 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_taken | Dieses 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_limited | Zu viele Anmeldeversuche. | Ein paar Minuten warten. |
reauth_failed | Die 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:
| Im Log oder beim Provider | Ursache |
|---|---|
discovered metadata issuer does not match the expected issuer | Der 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-Fehler | Die 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 beantwortet | Falsches 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_verifiedgeä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_URLauf 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.