Zum Inhalt springen

Self-Hosting

Single Sign-on (OIDC)

Lassen Sie Benutzer sich über OpenID Connect mit Ihrem Identitätsanbieter (Google Workspace, Keycloak, Okta, …) bei Notifuse anmelden, zusätzlich zur Anmeldung per Magic Code.

Notifuse unterstützt Single Sign-on (SSO) über OpenID Connect (OIDC). Ihr Team kann sich so über einen externen Identitätsanbieter (IdP) anmelden, etwa Google Workspace, Keycloak, Okta, Microsoft Entra ID, Authentik oder Dex.

SSO läuft neben der eingebauten Anmeldung per Magic Code und ersetzt sie nicht. Ist SSO aktiviert, zeigt die Anmeldeseite neben dem E-Mail-Formular eine zusätzliche Schaltfläche „Mit SSO anmelden“; beide Wege melden den Benutzer bei demselben Konto an.

Warnung

SSO erfordert eine Lizenz, die es enthält (die Enterprise-Stufe). Auf einer Installation ohne eine solche Lizenz erscheint die Schaltfläche Mit SSO anmelden nicht, ganz gleich, wie SSO konfiguriert ist, und alle melden sich stattdessen mit einem Anmeldecode an. Niemand wird ausgesperrt: Jedes SSO-Konto hat eine verifizierte E-Mail-Adresse, die Anmeldung per Code funktioniert immer, und bereits offene Sitzungen sind nicht betroffen. In diesem Fall meldet das Startprotokoll sso_gated=true, und Einstellungen → System weist neben dem Schalter darauf hin. Sobald Sie eine Lizenz mit SSO installieren, ist die Schaltfläche sofort wieder da, ohne Neustart. Siehe Lizenzschlüssel. Auf Notifuse Cloud wird der Schlüssel für Sie verwaltet, und SSO ist im Business-Tarif enthalten: siehe Auf Notifuse Cloud.

Hinweis

SSO ist standardmäßig aus. Bestehende Installationen, die es nicht konfigurieren, merken keinen Unterschied: Die Anmeldeseite bleibt genau wie bisher, nur mit dem Formular für den Magic Code.

Funktionsweise

Notifuse arbeitet als OIDC-Relying Party mit dem Authorization Code Flow mit PKCE:

  1. Der Benutzer klickt auf Mit SSO anmelden, und Notifuse leitet ihn zu Ihrem IdP weiter.
  2. Der Benutzer authentifiziert sich beim IdP (mit der MFA und den Richtlinien, die Sie dort vorschreiben).
  3. Der IdP leitet zurück zu …/api/user.oidc.callback. Notifuse prüft das ID-Token auf dem Server (Signatur, Issuer, Audience, Nonce, Ablauf) und meldet den Benutzer an.

Die Tokens des IdP werden vollständig auf dem Server ausgetauscht und geprüft: Nur das Sitzungstoken von Notifuse selbst gelangt jemals in den Browser. PKCE ist immer aktiv, und das Client-Secret wird dem Frontend nie offengelegt.

Hinweis

Anmeldung ist nicht gleich Zugriff auf einen Arbeitsbereich. Eine erfolgreiche SSO-Anmeldung authentifiziert den Benutzer, gibt ihm aber keinen Zugriff auf einen Arbeitsbereich. SSO-Benutzer brauchen weiterhin eine Einladung in einen Arbeitsbereich (oder müssen in ROOT_EMAIL stehen), bevor sie etwas tun können. Siehe Bereitstellung von Konten weiter unten.

Konfiguration

OIDC lässt sich auf drei Wegen konfigurieren, in dieser Rangfolge:

  1. Umgebungsvariablen (OIDC_*): für die Produktion empfohlen, sie haben immer Vorrang.
  2. Einrichtungsassistent: ein optionaler Abschnitt Single Sign-on beim ersten Start, mit der Weiterleitungs-URI, die Sie bei Ihrem IdP registrieren, und den Scopes.
  3. Systemeinstellungen → SSO (OpenID Connect): der Admin-Bereich in der Arbeitsbereichsauswahl der Konsole nach der Installation.

Ist ein Wert über eine Umgebungsvariable gesetzt, erscheint das passende Feld im Assistenten oder in den Einstellungen schreibgeschützt. Im Assistenten sperrt OIDC_ENABLED, OIDC_ISSUER_URL oder OIDC_CLIENT_ID den ganzen Abschnitt, der dann die gesetzten Variablen aufführt. Wenn Sie OIDC-Einstellungen in der Oberfläche speichern, startet der Server geordnet neu, um die Konfiguration neu zu laden (wie bei den SMTP-Einstellungen). Das Client-Secret wird verschlüsselt in der Datenbank gespeichert.

Umgebungsvariablen

VariableBeschreibungStandard
OIDC_ENABLEDHauptschalter. Bei false oder ohne Wert ist SSO deaktiviert und die Schaltfläche ausgeblendet.false
OIDC_ISSUER_URLIssuer-URL Ihres IdP (muss https verwenden). Notifuse ermittelt den Rest über <issuer>/.well-known/openid-configuration. Erforderlich, wenn SSO aktiviert ist.-
OIDC_CLIENT_IDOAuth2-Client-ID von Ihrem IdP. Erforderlich, wenn SSO aktiviert ist.-
OIDC_CLIENT_SECRETOAuth2-Client-Secret (vertraulicher Client). Wird verschlüsselt gespeichert und nie an den Browser gesendet. Erforderlich, wenn SSO aktiviert ist.-
OIDC_REDIRECT_URIDie bei Ihrem IdP registrierte Callback-URL. Ist sie leer, wird sie als <API_ENDPOINT>/api/user.oidc.callback abgeleitet.abgeleitet aus API_ENDPOINT
OIDC_SCOPESDurch Leerzeichen getrennte Scopes. openid ist immer enthalten; email ist erforderlich, und profile liefert den optionalen Anzeigenamen.openid email profile
OIDC_BUTTON_LABELText auf der Anmeldeschaltfläche.Sign in with SSO
OIDC_AUTO_CREATE_USERSBereitstellung von Konten bei Bedarf (Just-in-Time). Bei true ist OIDC_ALLOWED_DOMAINS erforderlich. Siehe Bereitstellung von Konten.false
OIDC_ALLOWED_DOMAINSDurch Komma, Semikolon oder Leerzeichen getrennte Liste der E-Mail-Domains, für die Konten automatisch angelegt werden dürfen. Pflicht bei OIDC_AUTO_CREATE_USERS=true (sonst startet der Server nicht).-
OIDC_ALLOW_UNVERIFIED_EMAILAkzeptiert ein ID-Token ohne email_verified-Claim, für Anbieter, die diesen nie senden (Microsoft Entra ID, Cloudflare Access). Bei einer ersten Anmeldung wird ein Token mit email_verified: false abgewiesen; eine Identität, die bereits mit einem Konto verknüpft ist, meldet sich über ihr Subject an und wird nicht erneut geprüft. Eine nicht verifizierte Adresse zählt nie für eine ausstehende Einladung (siehe Eingeladene Benutzer).false

Warnung

Bei OIDC_ENABLED=true prüft der Server die Konfiguration beim Start und bricht bei einer ungültigen sofort ab (fehlender Issuer, Client oder fehlendes Secret, ein Issuer ohne https oder automatisches Anlegen ohne Domainliste). Dieselbe Prüfung läuft, bevor der Einstellungsbereich speichert: Eine fehlerhafte Konfiguration wird mit einer Fehlermeldung abgelehnt und nicht gespeichert.

Bereitstellung von Konten

Standardmäßig ist SSO nur für eingeladene Benutzer gedacht: Ein Benutzer kann sich nur dann per SSO anmelden, wenn er bereits ein Notifuse-Konto hat oder in einen Arbeitsbereich eingeladen wurde (siehe Eingeladene Benutzer). Eine SSO-Anmeldung für eine Adresse, die niemand eingeladen hat, wird mit dem Hinweis abgewiesen, dass kein Konto existiert. Damit bleibt es dabei, dass sich bei Notifuse niemand selbst registrieren kann.

Damit neue Benutzer bei ihrer ersten SSO-Anmeldung automatisch angelegt werden, setzen Sie:

OIDC_AUTO_CREATE_USERS=true
OIDC_ALLOWED_DOMAINS=yourcompany.com

Ist das automatische Anlegen aktiv, entsteht bei der ersten Anmeldung ein Konto, wenn der IdP eine verifizierte E-Mail-Adresse bestätigt und deren Domain in OIDC_ALLOWED_DOMAINS steht. Auch dann hat der neue Benutzer erst nach einer Einladung Zugriff auf einen Arbeitsbereich. Für eine Adresse mit einer wartenden Einladung gelten stattdessen die Regeln unter Eingeladene Benutzer, in beide Richtungen: Die Einladung kann das Konto auch außerhalb der Domainliste anlegen, und ein Anbieter, der für die Adresse nicht maßgeblich ist, legt keines an.

Eingeladene Benutzer

Eine eingeladene Person muss den Link in der E-Mail nicht öffnen, bevor sie sich per SSO anmeldet. Bei ihrer ersten SSO-Anmeldung legt eine ausstehende Einladung an ihre Adresse ihr Konto an. Das gilt auch im Modus nur für Eingeladene und selbst dann, wenn ihre Domain nicht in OIDC_ALLOWED_DOMAINS steht, denn eine Einladung ist die ausdrückliche Wahl genau dieser Adresse durch einen Inhaber. Die Einladung wird nicht für sie angenommen: Sie landet in der Liste der Arbeitsbereiche unter Ausstehende Einladungen und klickt auf Beitreten.

Das geschieht nur, wenn Ihr Identitätsanbieter für die Adresse maßgeblich ist, denn der Beitritt aus der Konsole stützt sich auf die Adresse, die der Anbieter bestätigt:

AnbieterMaßgeblich, wenn
GoogleDie Adresse endet auf @gmail.com oder gehört zu einem Google-Workspace-Konto (der hd-Claim). Für ein privates Google-Konto, das mit der Adresse einer anderen Domain registriert ist, bürgt Google nicht.
Microsoft Entra IDDer Benutzer ist Mitglied Ihres Tenants, und das ID-Token enthält den optionalen Claim xms_edov mit dem Wert true. Fügen Sie ihn in Ihrer App-Registrierung unter Token configuration → Add optional claim → ID hinzu. Gäste, die sich mit einem privaten Microsoft- oder Google-Konto oder einem Einmal-Passcode anmelden, zählen nicht: Entra setzt xms_edov auch für sie.
Jeder andere AnbieterDas ID-Token enthält email_verified: true. Ein Anbieter, der andere vermittelt (Keycloak, Dex, Social Connections von Auth0), bürgt mit seinem eigenen email_verified für deren Adressen. Geben Sie es deshalb nur für Adressen weiter, denen Sie vertrauen.

Ist der Anbieter nicht maßgeblich, legt SSO für eine eingeladene Adresse kein Konto an (auch nicht mit OIDC_AUTO_CREATE_USERS), und die eingeladene Person öffnet stattdessen den Link in ihrer Einladungs-E-Mail. Hat sie die Einladung angenommen, funktioniert SSO für sie von da an.

Hinweis

Benutzer werden über das dauerhafte Paar (issuer, subject) des IdP zugeordnet, nicht über die E-Mail-Adresse. Ein Benutzer behält also dasselbe Konto, auch wenn sich seine E-Mail-Adresse beim IdP ändert. Die E-Mail-Adresse wird nur bei der ersten Anmeldung verwendet: um eine SSO-Identität mit einem bestehenden Konto zu verknüpfen oder um die Einladungen zu finden, die für diese Adresse warten. Ein ROOT_EMAIL-Konto wird nie automatisch mit einer externen Identität verknüpft (ein Schutz gegen die Übernahme des Plattform-Admins).

Einrichtung beim Identitätsanbieter

Die Callback- bzw. Weiterleitungs-URL, die Sie bei jedem Anbieter registrieren, lautet:

https://<your-notifuse-domain>/api/user.oidc.callback

Warnung

Die Weiterleitungs-URI muss bei Ihrem IdP und in Notifuse Byte für Byte übereinstimmen. Läuft Notifuse hinter einem Reverse Proxy, der Schema oder Host umschreibt, setzen Sie OIDC_REDIRECT_URI ausdrücklich auf die von außen sichtbare URL; sonst gibt der IdP den Fehler redirect_uri_mismatch zurück.

Google Workspace

  1. Öffnen Sie in der Google Cloud Console APIs & Services → Credentials → Create credentials → OAuth client ID.
  2. Wählen Sie Web application.
  3. Fügen Sie unter Authorized redirect URIs https://<your-notifuse-domain>/api/user.oidc.callback hinzu.
  4. Kopieren Sie Client ID und Client secret.
  5. Konfigurieren Sie Notifuse:
OIDC_ENABLED=true
OIDC_ISSUER_URL=https://accounts.google.com
OIDC_CLIENT_ID=xxxxxxxx.apps.googleusercontent.com
OIDC_CLIENT_SECRET=your-client-secret
# Restrict to your organization's domain:
OIDC_ALLOWED_DOMAINS=yourcompany.com

Hinweis

Private @gmail.com-Konten und Ihre Workspace-Konten teilen sich den Issuer accounts.google.com. Beschränken Sie die Anmeldung mit OIDC_ALLOWED_DOMAINS auf Ihre Organisation (oder behalten Sie den Standardmodus nur für Eingeladene bei). Eine @gmail.com-Adresse, die Sie eingeladen haben, kann sich trotzdem anmelden (siehe Eingeladene Benutzer).

Keycloak

  1. Legen Sie in Ihrem Realm einen Client an: Client type OpenID Connect, Client authentication ON (vertraulich), Standard flow aktiviert.
  2. Setzen Sie Valid redirect URIs auf https://<your-notifuse-domain>/api/user.oidc.callback.
  3. Kopieren Sie das Secret aus dem Tab Credentials des Clients.
  4. Konfigurieren Sie Notifuse:
OIDC_ENABLED=true
OIDC_ISSUER_URL=https://keycloak.example.com/realms/<your-realm>
OIDC_CLIENT_ID=notifuse
OIDC_CLIENT_SECRET=your-client-secret

Tipp

Die Standard-Client-Scopes von Keycloak liefern bereits email, email_verified, name und sub. Hat jemand den E-Mail-Mapper aus Ihrem Client entfernt, werden SSO-Anmeldungen abgewiesen (kein E-Mail-Claim): Fügen Sie den eingebauten Scope email wieder hinzu.

Andere Anbieter

Jeder für OpenID Connect zertifizierte Anbieter funktioniert auf dieselbe Weise: Setzen Sie OIDC_ISSUER_URL auf den Issuer des Anbieters, registrieren Sie die Weiterleitungs-URI und geben Sie Client-ID und Secret an. Dazu gehören Okta, Microsoft Entra ID (Azure AD), Authentik und Dex.

Hinweise zur Sicherheit

  • Nur zwei nicht geheime Werte gelangen in den Browser: window.OIDC_ENABLED und die Beschriftung der Schaltfläche. Client-ID, Client-Secret und Issuer-URL erscheinen nie in der Seite.
  • ID-Tokens werden mit den veröffentlichten Schlüsseln des Issuers geprüft (automatisch rotiert über JWKS). Signatur, Issuer, Audience, Nonce und Ablauf werden alle geprüft, und nur asymmetrische Algorithmen (RS256/ES256) werden akzeptiert.
  • Der CSRF-, Nonce- und PKCE-Zustand des Ablaufs liegt in einem kurzlebigen, verschlüsselten HttpOnly-Cookie.
  • Die HTTP-Aufrufe für OIDC (Discovery, Abruf der Schlüssel, Token-Austausch) haben ein Zeitlimit. Ein langsamer oder nicht erreichbarer Issuer kann die Anmeldung also nicht blockieren; die Anmeldung per Magic Code ist nicht betroffen.

Fehlerbehebung

SymptomUrsache und Lösung
„Single Sign-On ist vorübergehend nicht verfügbar“ nach dem Klick auf SSONotifuse kann den Issuer nicht erreichen oder seine Konfiguration nicht ermitteln. Prüfen Sie, ob OIDC_ISSUER_URL stimmt, vom Server aus erreichbar ist und ein Discovery-Dokument ausliefert. Notifuse versucht es automatisch erneut, sobald der Issuer wieder da ist.
„Mit dieser Identität ist kein Notifuse-Konto verknüpft. Wenn Sie eingeladen wurden, öffnen Sie den Link in Ihrer Einladungs-E-Mail“Für die Adresse gibt es kein Konto und nichts, woraus SSO eines anlegen könnte. Entweder hat sie niemand eingeladen (laden Sie den Benutzer ein oder aktivieren Sie OIDC_AUTO_CREATE_USERS mit einer Domainliste), oder es gibt eine ausstehende Einladung, aber Ihr Anbieter ist für die Adresse nicht maßgeblich (siehe Eingeladene Benutzer). Dann nimmt der Benutzer die Einladung über ihren Link an.
„Single Sign-On kann für Ihre E-Mail-Domain kein Konto erstellen“Das automatische Anlegen ist aktiv, und die Adresse liegt außerhalb von OIDC_ALLOWED_DOMAINS. Fügen Sie die Domain hinzu oder laden Sie den Benutzer ein: Eine Einladung hebt die Domainliste für diese Adresse auf, wenn Ihr Anbieter für sie maßgeblich ist (siehe Eingeladene Benutzer). Andernfalls nimmt der Benutzer die Einladung über ihren Link an.
redirect_uri_mismatch / invalid_redirect_uri beim IdPDie beim IdP registrierte Weiterleitungs-URI stimmt nicht genau mit dem überein, was Notifuse sendet. Registrieren Sie …/api/user.oidc.callback und setzen Sie OIDC_REDIRECT_URI, wenn ein Proxy davor Schema oder Host umschreibt.
Der Server startet nach dem Aktivieren von OIDC nichtDie Prüfung der Konfiguration ist fehlgeschlagen. Prüfen Sie, ob OIDC_ISSUER_URL https verwendet, ob OIDC_CLIENT_ID und OIDC_CLIENT_SECRET gesetzt sind und ob OIDC_ALLOWED_DOMAINS bei OIDC_AUTO_CREATE_USERS=true nicht leer ist.
Ein Benutzer kann sich anmelden, aber auf keinen Arbeitsbereich zugreifenDas ist so vorgesehen: Anmeldung ist keine Berechtigung. Laden Sie den Benutzer in den passenden Arbeitsbereich ein (oder nehmen Sie ihn in ROOT_EMAIL auf); eine ausstehende Einladung erscheint in seiner Liste der Arbeitsbereiche mit der Schaltfläche Beitreten.

Hinweis

Mehrere Notifuse-Replikate hinter einem Load Balancer? Der Einmalcode, der die Übergabe nach dem SSO abschließt, wird pro Instanz gehalten. Aktivieren Sie deshalb Sticky Sessions, damit SSO über mehrere Replikate zuverlässig funktioniert. Installationen mit einer einzigen Instanz brauchen keine weitere Konfiguration.