Single Sign-On für eine On-Premise-Installation

Diese Seite richtet sich an Betreiber einer On-Premise-Installation von MonoChat. Sie erklärt, wie sich Ihre Mitarbeitenden über OpenID Connect (OIDC) mit dem Identitätsanbieter (IdP) Ihres Unternehmens anmelden, zum Beispiel Microsoft Entra ID, Okta, Keycloak, AD FS oder Google Workspace.

Single Sign-On wird für die gesamte Installation in den Servereinstellungen eingerichtet, nicht pro Mandant. Ein MonoChat-Konto kann zu mehreren Mandanten gehören, und man meldet sich an, bevor man einen auswählt. Die Anmeldung gibt ein Konto, keinen Zugriff: Eine Person sieht einen Mandanten erst, nachdem dieser Mandant sie eingeladen und ihr eine Rolle gegeben hat.

So funktioniert die Anmeldung

Wenn jemand auf der Anmeldeseite auf die SSO-Schaltfläche klickt, öffnet MonoChat die Anmeldeseite Ihres IdP in einem Pop-up. Nachdem sich die Person dort angemeldet hat, schickt der IdP den Browser mit einem Einmalcode zu MonoChat zurück. Der MonoChat-Server tauscht den Code gegen ein ID-Token und prüft es, bevor er die Person anmeldet:

• Die Endpunkte und Signaturschlüssel des IdP werden bei jeder Anmeldung aus seinem Discovery-Dokument <issuer>/.well-known/openid-configuration gelesen.
• Die Anmeldung nutzt den Authorization-Code-Flow mit PKCE (S256), einem state und einer nonce. Eine Anmeldeanfrage ist 10 Minuten gültig und kann einmal verwendet werden.
• Das ID-Token muss mit einem der Schlüssel des IdP signiert sein und Ihren Issuer (iss), Ihre Client-ID (aud), die nonce der Anfrage und einen noch nicht abgelaufenen Ablaufzeitpunkt (exp) enthalten.
• Das ID-Token muss die E-Mail-Adresse der Person enthalten (email). Eine Anmeldung wird abgelehnt, wenn der IdP angibt, dass die Adresse nicht bestätigt ist (email_verified: false).

1. MonoChat bei Ihrem Identitätsanbieter registrieren

Legen Sie bei Ihrem IdP eine Anwendung (einen Client) für MonoChat mit diesen Werten an:

Einstellung beim IdP	Wert
Anwendungstyp	Webanwendung mit Client-Secret (ein vertraulicher Client)
Weiterleitungs-URI für die Anmeldung	https://<your MonoChat domain>/api/oauth/oidc/redirect
Grant-Typ	Authorization Code
Scopes	openid email profile
Client-Authentifizierung am Token-Endpunkt	Client-Secret per HTTP-Basic-Authentifizierung (client_secret_basic)

Stellen Sie sicher, dass das ID-Token den Claim email enthält. Notieren Sie Client-ID, Client-Secret und Issuer. Der Issuer ist der Wert issuer im Discovery-Dokument des IdP. Typische Formen:

Identitätsanbieter	Issuer
Microsoft Entra ID	https://login.microsoftonline.com/<tenant id>/v2.0
Okta	https://<your Okta domain>/oauth2/default oder https://<your Okta domain>
Keycloak	https://<your Keycloak host>/realms/<realm>
AD FS (2016 oder neuer)	https://<your AD FS host>/adfs
Google Workspace	https://accounts.google.com

Öffnen Sie <issuer>/.well-known/openid-configuration im Browser und kopieren Sie den Wert issuer exakt, einschließlich eines abschließenden /, falls vorhanden. MonoChat meldet niemanden an, wenn die beiden voneinander abweichen.

2. Einstellungen hinzufügen

Fügen Sie die oidc-Blöcke zu den Servereinstellungen hinzu und starten Sie MonoChat neu. Der öffentliche Block gehört unter public.oauth, der geheime Block unter oauth:

{
  "oauth": {
    "oidc": {
      "clientSecret": "<client secret>",
      "autoCreateAccounts": true,
      "allowedEmailDomains": ["company.com"]
    }
  },
  "public": {
    "oauth": {
      "oidc": {
        "issuer": "https://login.microsoftonline.com/<tenant id>/v2.0",
        "clientId": "<client id>",
        "redirectPath": "/api/oauth/oidc/redirect",
        "scope": "openid email profile",
        "buttonLabel": "Sign in with Company SSO"
      }
    }
  }
}

Einstellung	Wirkung
public.oauth.oidc.issuer	Der Issuer aus Schritt 1
public.oauth.oidc.clientId	Die Client-ID aus Schritt 1
public.oauth.oidc.redirectPath	Der Pfad der Weiterleitungs-URI aus Schritt 1
public.oauth.oidc.scope	Die Scopes, die MonoChat anfordert
public.oauth.oidc.buttonLabel	Der Text der Anmeldeschaltfläche. Leer zeigt „Mit SSO anmelden“ in der Sprache der Person
oauth.oidc.clientSecret	Das Client-Secret. Es bleibt auf dem Server
oauth.oidc.autoCreateAccounts	true legt das MonoChat-Konto bei der ersten SSO-Anmeldung einer Person an, auch wenn die Registrierung nur per Einladung möglich ist (public.disableSignup)
oauth.oidc.allowedEmailDomains	Nur Personen mit einer E-Mail-Adresse in einer dieser Domains dürfen sich per SSO anmelden. Weglassen, um alle Domains zuzulassen

Danach erscheint die SSO-Schaltfläche auf der Anmeldeseite.

Wer sich anmelden kann

• Neue Personen. Mit autoCreateAccounts: true legt die erste SSO-Anmeldung einer Person ihr Konto an. Ohne diese Einstellung wird das Konto nur angelegt, wenn public.disableSignup aus ist oder sich die Person über eine Einladung anmeldet.
• Personen, die bereits ein Konto mit derselben E-Mail-Adresse haben. Mit oauth.autoMerge: true verknüpft die erste SSO-Anmeldung SSO mit dem bestehenden Konto, aber nur, wenn das ID-Token angibt, dass die Adresse bestätigt ist (email_verified: true). Andernfalls, und ohne autoMerge immer, bittet MonoChat die Person, sich einmal mit ihrem Passwort anzumelden, und verknüpft SSO dann mit dem Konto; auch das Annehmen einer Einladung zu einem Mandanten verknüpft es. Da Microsoft Entra ID und AD FS kein email_verified senden, lassen Sie bei ihnen die Passwortanmeldung erlaubt, bis alle SSO verknüpft haben, oder laden Sie die Personen erneut ein.
• Zugelassene Domains. Mit allowedEmailDomains wird eine Adresse in jeder anderen Domain abgelehnt. Bei Google Workspace (Issuer https://accounts.google.com) prüft MonoChat statt der E-Mail-Adresse den Claim hd, die Workspace-Domain des Kontos, denn ein privates Google-Konto kann eine Adresse in jeder Domain verwenden.

SSO zur einzigen Anmeldemethode machen

1. Setzen Sie public.auth.methods auf ["oidc"]. Die Anmeldeseite zeigt dann nur die SSO-Schaltfläche, und der Server lehnt Passwort- und Social-Anmeldungen ab.
2. Root-Super-Benutzer (Benutzer mit der Root-Super-Rolle im Root-Mandanten) können sich weiterhin unter /auth/signin?fallback=1 mit ihrem Passwort anmelden, sodass die Installation nie ausgesperrt ist, wenn der IdP ausfällt.
3. Damit neue SSO-Konten keine eigenen Mandanten eröffnen, setzen Sie public.disableTenantCreation auf true. Dann können nur Personen mit der passenden Rolle in einem Mandanten darunter Mandanten anlegen.

Netzwerk

• Halten Sie /api/oauth/oidc/authorize und Ihren redirectPath für die Personen erreichbar, die sich anmelden. Beide werden in deren Browser geöffnet.
• Der MonoChat-Server muss das Discovery-Dokument, den Token-Endpunkt und den Schlüsselsatz (jwks_uri) Ihres IdP über HTTPS erreichen.

Einschränkungen

• Die mobile MonoChat-App bietet noch kein SSO. Wenn Sie SSO zur einzigen Anmeldemethode machen, können sich Agenten nicht in der mobilen App anmelden.
• Eine Abmeldung bei MonoChat meldet die Person nicht beim IdP ab, und eine Abmeldung beim IdP meldet sie noch nicht bei MonoChat ab.

Einrichtung prüfen

1. Öffnen Sie die Anmeldeseite und klicken Sie auf die SSO-Schaltfläche. Melden Sie sich bei Ihrem IdP an; das Pop-up schließt sich und Sie sind bei MonoChat angemeldet.
2. Melden Sie sich mit einer Person an, die noch kein MonoChat-Konto hat, und prüfen Sie, dass das Konto angelegt wird (oder abgelehnt, wenn Sie autoCreateAccounts nicht eingeschaltet haben).
3. Wenn Sie allowedEmailDomains gesetzt haben, versuchen Sie es mit einer Person aus einer anderen Domain und prüfen Sie, dass die Anmeldung abgelehnt wird.
4. Wenn Sie public.auth.methods gesetzt haben, prüfen Sie, dass eine Passwortanmeldung abgelehnt wird und sich ein Root-Super-Benutzer weiterhin unter /auth/signin?fallback=1 anmelden kann.