Single Sign-On und zweiter Faktor

Standardmäßig melden sich Personen mit ihrer E-Mail-Adresse und einem Einmalcode per E-Mail an (oder mit einem Kennwort, falls eines festgelegt wurde). Für Unternehmen gibt es zwei Ergänzungen:

• Single Sign-On (SSO) über Ihren eigenen Anmeldeanbieter – Microsoft Entra ID, Google Workspace, Keycloak, Okta oder jeden anderen OpenID-Connect-Anbieter.
• Einen zweiten Faktor: Nach der Anmeldung ist zusätzlich ein Code per E-Mail einzugeben.

Beides wird über Umgebungsvariablen auf dem Server eingerichtet und gilt für die ganze Installation – alle Workspaces. In der Oberfläche gibt es dafür keinen Schalter.

Anmeldearten

Art	So melden sich Personen an	Einstellung
Code per E-Mail (Standard)	E-Mail-Adresse eingeben, dann den sechsstelligen Code aus der E-Mail – oder das Kennwort, falls eines festgelegt wurde.	nichts einzustellen
Single Sign-On	Die Anmeldeseite leitet zu Ihrem Anmeldeanbieter weiter; dort melden sich die Personen mit ihrem Firmenkonto an. Code per E-Mail und Kennwörter sind abgeschaltet.	AIKIT_LOGIN_OAUTH_URL ist gesetzt
Zweiter Faktor	Nach dem Firmenkonto oder dem Kennwort ist zusätzlich ein Code per E-Mail nötig.	AIKIT_LOGIN_MFA=otp

Mit SSO leitet die Anmeldeseite sofort zum Anbieter weiter. Nach dem Abmelden zeigt sie stattdessen einen Knopf – damit der Anbieter die Person nicht unbemerkt wieder anmeldet:

So funktioniert Single Sign-On

Das AI Kit verwendet den Standard OpenID Connect mit dem Authorization-Code-Ablauf und PKCE. Der Server löst den Code selbst ein, mit dem Client-Secret – das Secret erreicht nie den Browser.

1. Eine Person öffnet das AI Kit und wird zur Anmeldeseite Ihres Anbieters weitergeleitet.
2. Sie meldet sich dort an – einschließlich der Mehr-Faktor-Anmeldung, die Ihr Anbieter verlangt.
3. Der Anbieter schickt den Browser zurück an /login/callback.
4. Das AI Kit prüft die Antwort des Anbieters: Signatur, Aussteller, Empfänger, Ablauf und einen Einmalwert, der die Antwort an diesen Browser bindet.
5. Es meldet die Person mit einer eigenen Sitzung an. Die Tokens des Anbieters werden sofort verworfen – weder gespeichert noch protokolliert.

Nur eingeladene Konten. SSO legt keine Konten an. Anmelden kann sich nur, wen ein Administrator vorher eingeladen hat – mit der E-Mail-Adresse, die die Person beim Anbieter hat. Groß- und Kleinschreibung spielen keine Rolle.

Die erste Anmeldung verknüpft das Konto. Das AI Kit merkt sich, welches Konto beim Anbieter zur Person gehört. Meldet der Anbieter später dieselbe E-Mail-Adresse für ein anderes Konto (etwa weil die Adresse an eine neue Mitarbeiterin vergeben wurde), wird die Anmeldung abgewiesen, bis ein Administrator die Verknüpfung löst – siehe Konten und E-Mail-Adressen.

Sitzungen. Eine Anmeldung über den Anbieter gilt höchstens 48 Stunden. Danach leitet das AI Kit erneut zum Anbieter weiter – meist ohne Rückfrage, solange die Person dort noch angemeldet ist. Wer beim Anbieter gesperrt wird, ist damit spätestens nach 48 Stunden ausgesperrt.

Schalten Sie SSO oder den zweiten Faktor ein, werden bestehende Sitzungen nicht mehr verlängert: Alle melden sich beim nächsten Erneuern der Sitzung einmal neu an.

Vor dem Einrichten

• Adresse der Installation. Das AI Kit muss unter einer festen Adresse (FRONTEND_DOMAIN) per HTTPS erreichbar sein. Die beim Anbieter einzutragende Redirect-URI lautet https://<Ihre-Adresse>/login/callback.
• Ausgehende Verbindung. Der Server muss den Anbieter per HTTPS erreichen – siehe Netzwerkzugriff.
• Zuerst einladen. Laden Sie mindestens einen Admin – am besten alle Personen – mit der E-Mail-Adresse ein, die sie beim Anbieter haben, bevor Sie SSO einschalten. Danach kann sich niemand mehr mit einem Code anmelden; Ihr bisheriges Administratorkonto funktioniert also nur, wenn seine Adresse beim Anbieter existiert.

Microsoft Entra ID einrichten

Im Microsoft Entra Admin Center:

1. App-Registrierungen → Neue Registrierung. Name zum Beispiel AI Kit. Unterstützte Kontotypen: Nur Konten in diesem Organisationsverzeichnis (ein Mandant).
2. Unter Umleitungs-URI die Plattform Web wählen und https://<Ihre-Adresse>/login/callback eintragen.
3. Zertifikate & Geheimnisse → Neuer geheimer Clientschlüssel. Den Wert kopieren.
4. In der Übersicht die Anwendungs-ID (Client) und die Verzeichnis-ID (Mandant) kopieren.
5. Optional: Tokenkonfiguration → Optionalen Anspruch hinzufügen → Tokentyp ID → email. Ohne diesen Anspruch verwendet das AI Kit den Anmeldenamen (preferred_username, meist der UPN) als E-Mail-Adresse.

Dann auf dem Server setzen:

AIKIT_LOGIN_OAUTH_URL=https://login.microsoftonline.com/<Mandanten-ID>/v2.0
AIKIT_LOGIN_OAUTH_CLIENT_ID=<Anwendungs-ID>
AIKIT_LOGIN_OAUTH_CLIENT_SECRET=<Wert des geheimen Clientschlüssels>

Mandanten-ID verwenden. Adressen mit common, organizations oder consumers lehnt das AI Kit beim Start ab – damit könnte sich jeder Microsoft-Mandant anmelden.

Plattform „Web", nicht „Single-Page-Anwendung". Das AI Kit löst den Code auf dem Server mit dem Secret ein. Bei SPA-Registrierungen lehnt Entra das ab (Fehler AADSTS9002327).

Google Workspace einrichten

In der Google Cloud Console:

1. APIs & Dienste → OAuth-Zustimmungsbildschirm: Nutzertyp Intern.
2. Anmeldedaten → Anmeldedaten erstellen → OAuth-Client-ID, Anwendungstyp Webanwendung. Unter Autorisierte Weiterleitungs-URIs https://<Ihre-Adresse>/login/callback eintragen.
3. Client-ID und Clientschlüssel kopieren.

AIKIT_LOGIN_OAUTH_URL=https://accounts.google.com
AIKIT_LOGIN_OAUTH_CLIENT_ID=<Client-ID>.apps.googleusercontent.com
AIKIT_LOGIN_OAUTH_CLIENT_SECRET=<Clientschlüssel>
AIKIT_LOGIN_OAUTH_ALLOWED_DOMAINS=example.com

Setzen Sie AIKIT_LOGIN_OAUTH_ALLOWED_DOMAINS auf Ihre Workspace-Domain. Sonst kann jedes Google-Konto eine Anmeldung beginnen (abgewiesen wird sie trotzdem, wenn kein eingeladenes Konto passt). Mit gesetzter Domain prüft das AI Kit zusätzlich Googles Workspace-Domain (hd).

Andere Anbieter

Jeder OpenID-Connect-Anbieter funktioniert – Keycloak, Okta, Auth0, ADFS und andere. Setzen Sie die Issuer-URL des Anbieters, für Keycloak zum Beispiel https://sso.example.com/realms/<Realm>, dazu Client-ID und Secret. Alles Weitere liest das AI Kit aus dem Discovery-Dokument des Anbieters (<URL>/.well-known/openid-configuration).

Anbieter ohne Discovery-Dokument. Dann prüft das AI Kit die Standardpfade <URL>/authorize und <URL>/token und verwendet sie, wenn sie wie OAuth-Endpunkte antworten. Tun sie das nicht, geben Sie die Endpunkte ausdrücklich an (AIKIT_LOGIN_OAUTH_AUTHORIZE_URL, AIKIT_LOGIN_OAUTH_TOKEN_URL, bei Bedarf AIKIT_LOGIN_OAUTH_USERINFO_URL). Veröffentlicht der Anbieter keine Signaturschlüssel, erkennt das AI Kit das ID-Token über die HTTPS-Verbindung zum Token-Endpunkt an, über die es das Token selbst abgeholt hat – Aussteller, Empfänger, Ablauf und Einmalwert werden trotzdem geprüft.

Zusätzliche Parameter. AIKIT_LOGIN_OAUTH_AUTHORIZE_PARAMS ergänzt die Weiterleitung (zum Beispiel prompt=select_account oder bei Entra domain_hint=example.com); AIKIT_LOGIN_OAUTH_TOKEN_PARAMS ergänzt das Einlösen des Codes (zum Beispiel resource=… bei ADFS).

Zweiter Faktor

AIKIT_LOGIN_MFA=otp

Nach der Anmeldung mit dem Firmenkonto – oder mit einem Kennwort – schickt das AI Kit einen sechsstelligen Code an die E-Mail-Adresse des Kontos, genau wie bei der Anmeldung per Code. Erst danach ist die Person angemeldet.

• Ein Code gilt 5 Minuten. Es zählt nur der zuletzt verschickte Code.
• Neuen Code senden erscheint nach 60 Sekunden. Vorher verschickt das AI Kit keinen neuen Code, solange einer offen ist.
• Nach 5 falschen Codes ist der Code verbraucht – Neuen Code senden schickt einen weiteren. Der Schritt selbst gilt 10 Minuten; danach meldet sich die Person neu an.
• Wer sich mit einem Code per E-Mail anmeldet, hat den Zugriff auf das Postfach schon nachgewiesen – dann wird kein zweiter Code verlangt.
• Konten mit Kennwort melden sich immer mit dem Kennwort an – nie mit einem Code allein.

Der zweite Faktor braucht funktionierenden Mailversand (SMTP). Er funktioniert auch ohne SSO, zusammen mit Kennwörtern.

Übersicht der Einstellungen

Alle Einstellungen werden beim Start gelesen. Starten Sie das AI Kit nach einer Änderung neu.

Einstellung	Bedeutung	Standard
AIKIT_LOGIN_OAUTH_URL	Issuer-URL des Anbieters. Gesetzt = SSO ist aktiv.	– (SSO aus)
AIKIT_LOGIN_OAUTH_CLIENT_ID	Client-ID der Registrierung beim Anbieter. Pflicht mit SSO; ohne sie startet das AI Kit nicht.	–
AIKIT_LOGIN_OAUTH_CLIENT_SECRET	Client-Secret. Ohne Secret tritt das AI Kit als öffentlicher Client auf (nur PKCE).	–
AIKIT_LOGIN_OAUTH_REDIRECT_URI	Adresse, an die der Anbieter zurückschickt – genau diese eintragen.	<FRONTEND_DOMAIN>/login/callback
AIKIT_LOGIN_OAUTH_SCOPES	Angefragte Scopes, durch Leerzeichen oder Kommas getrennt. openid wird immer ergänzt.	openid profile email
AIKIT_LOGIN_OAUTH_TOKEN_AUTH	Wie das Secret übermittelt wird: client_secret_post (in der Anfrage), client_secret_basic (als Header) oder none.	aus dem Discovery-Dokument, bevorzugt client_secret_post
AIKIT_LOGIN_OAUTH_ALLOWED_DOMAINS	Nur E-Mail-Adressen dieser Domains, durch Kommas getrennt.	alle
AIKIT_LOGIN_OAUTH_EMAIL_CLAIM	Claims, aus denen die E-Mail-Adresse kommt – der erste vorhandene zählt.	email, preferred_username, upn
AIKIT_LOGIN_OAUTH_LABEL	Name auf dem Knopf (Weiter mit …).	Microsoft / Google, sonst ein allgemeiner Text
AIKIT_LOGIN_OAUTH_AUTHORIZE_PARAMS	Zusätzliche Parameter für die Weiterleitung, als a=1&b=2.	–
AIKIT_LOGIN_OAUTH_TOKEN_PARAMS	Zusätzliche Parameter für das Einlösen des Codes.	–
AIKIT_LOGIN_OAUTH_AUTHORIZE_URL, _TOKEN_URL, _USERINFO_URL, _JWKS_URL	Endpunkte, wenn weder das Discovery-Dokument noch die Standardpfade passen.	aus dem Discovery-Dokument
AIKIT_LOGIN_MFA	otp: ein Code per E-Mail als zweiter Faktor.	– (aus)

Das AI Kit startet nicht, wenn ein Wert ungültig ist – etwa ein unbekannter Wert für AIKIT_LOGIN_MFA, eine fehlende Client-ID oder eine Entra-Adresse mit common. Das Startprotokoll nennt den Grund.

Konten und E-Mail-Adressen

• Mit der Adresse beim Anbieter einladen. Die Einladung funktioniert wie bisher (Benutzer verwalten) – die Adresse muss die sein, die der Anbieter meldet.
• E-Mail-Adressen ändern nur Administratoren. Die eigene Adresse lässt sich im Profil nicht ändern; das erledigt ein Admin unter Administration → Benutzer & Rollen → Zeilenmenü → E-Mail-Adresse ändern. Jeder Admin der Installation (Admin in irgendeinem Workspace) darf die Adresse jeder Person ändern. Die Adresse muss eindeutig sein, unabhängig von Groß- und Kleinschreibung.
• Namensänderungen. Ändert sich die Adresse einer Person beim Anbieter, ändern Sie sie auch im AI Kit. Bis dahin wird die Anmeldung abgewiesen, weil die Adressen nicht übereinstimmen.
• Adresse neu vergeben. Meldet der Anbieter eine bekannte Adresse für ein anderes Konto, wird die Anmeldung abgewiesen. Ein Admin löst die alte Verknüpfung über das Zeilenmenü → SSO-Verknüpfung lösen; die nächste Anmeldung verknüpft das neue Konto.

Notfallzugang

Ist der Anbieter nicht erreichbar oder falsch eingerichtet, entfernen Sie AIKIT_LOGIN_OAUTH_URL und starten das AI Kit neu. Dann funktioniert die Anmeldung mit einem Code per E-Mail wieder für jedes Konto. Setzen Sie die Variable wieder, sobald der Anbieter funktioniert.

Die Einrichtung prüfen

Beim Start schreibt das AI Kit die wirksame Anmeldekonfiguration in sein Protokoll: die Anmeldeart, den Anbieter, die Client-ID (ob ein Secret gesetzt ist, nie das Secret selbst), die einzutragende Redirect-URI, die Scopes und den zweiten Faktor. Danach prüft es den Anbieter und vermerkt, ob er sich verwenden lässt – und wenn nicht, warum. Auch jede Anmeldung hinterlässt eine Zeile, bei Ablehnung mit dem Grund. Alle diese Zeilen beginnen mit 🔐, grep 🔐 findet sie.

Was Personen sehen	Ursache und Abhilfe
Ihr Anmeldeanbieter ist gerade nicht erreichbar	Falsche URL, kein OpenID-Connect-Anbieter unter dieser Adresse oder keine Netzwerkverbindung. AIKIT_LOGIN_OAUTH_URL prüfen; das Startprotokoll nennt den Grund.
Eine Fehlerseite beim Anbieter (Entra AADSTS50011, Google redirect_uri_mismatch)	Die Redirect-URI ist nicht eingetragen. Genau die aus dem Startprotokoll eintragen.
Noch kein Zugang	Kein eingeladenes Konto mit der Adresse, die der Anbieter meldet. Die Person mit genau dieser Adresse einladen.
… passt nicht zur hier hinterlegten	Die Adresse beim Anbieter hat sich geändert. Unter Benutzer & Rollen ändern.
… mit einem anderen Firmenkonto verknüpft	Die Adresse wurde beim Anbieter an jemand anderen vergeben. SSO-Verknüpfung lösen, wenn das neue Konto richtig ist.
Ihr Anmeldeanbieter hat die Anmeldung abgelehnt	Client-ID oder Secret falsch oder abgelaufen; gegebenenfalls AIKIT_LOGIN_OAUTH_TOKEN_AUTH setzen.
Ihr Anmeldeanbieter hat keine E-Mail-Adresse übermittelt	Den Scope email anfragen oder AIKIT_LOGIN_OAUTH_EMAIL_CLAIM setzen.
Die Anmeldung hat zu lange gedauert oder wurde in einem anderen Fenster begonnen	Einfach erneut anmelden. Eine Anmeldung muss innerhalb von 10 Minuten im selben Browser-Tab abgeschlossen werden.

Audit-Log

Mit dem Compliance-Paket hält das Audit-Log jede Anmeldung mit ihrem Verfahren fest (Code, Kennwort oder SSO), dazu den zweiten Faktor und bei Fehlversuchen den Grund. Außerdem zeigt es Firmenkonto verknüpft, Firmenkonto-Verknüpfung gelöst und E-Mail-Adresse geändert.

Empfehlungen

• ✅ Registrieren Sie das AI Kit beim Anbieter als Webanwendung für einen Mandanten und schränken Sie dort ein, wer sie nutzen darf (Entra: Zuweisung erforderlich).
• ✅ Überlassen Sie die Mehr-Faktor-Anmeldung Ihrem Anbieter. AIKIT_LOGIN_MFA=otp nur ergänzen, wenn der Anbieter sie nicht erzwingen kann.
• ✅ Testen Sie die Einrichtung mit einem eingeladenen Admin-Konto, bevor Sie alle einladen.
• ⚠️ Halten Sie mindestens zwei Admins, deren Adressen beim Anbieter existieren.
• ❌ Verwenden Sie für Entra ID weder common noch organizations.

Nächste Schritte

• Benutzer verwalten – Personen einladen und E-Mail-Adressen ändern.
• Netzwerkzugriff – Verbindungen, die das AI Kit braucht.
• Audit-Log – Anmeldungen und Kontoänderungen.