Zum Hauptinhalt springen

SAML mit Azure Entra ID

Diese Seite beschreibt die Einrichtung von SAML (Single Sign-On) mit Microsoft Entra ID für Bubble Chat. Die grundlegenden Schritte sind für CMS und Website Messenger identisch.

Ziel und Nutzen​

Mit SAML melden sich Benutzer mit ihrem bestehenden Unternehmenskonto an. Die Authentifizierung erfolgt über den Identity Provider (IdP), während Bubble Chat als Service Provider (SP) die Anmeldung verifiziert und den Zugriff gewährt.

Vorteile:

  • Zentrale Benutzerverwaltung über Microsoft Entra ID
  • Einheitliche Login-Prozesse über bestehendes SSO
  • Kein separates Passwort-Management in Bubble Chat

Ablauf auf hoher Ebene​

Voraussetzungen​

  • Zugriff auf das Azure Portal
  • Berechtigung zum Erstellen und Konfigurieren von Enterprise Applications in Microsoft Entra ID
  • Bekannte Ziel-URL(s) von Bubble Chat für den jeweiligen Einsatzfall (CMS und/oder Website Messenger)

Einrichtung in Microsoft Entra ID​

  1. Öffne das Azure Portal.
  2. Navigiere zu Microsoft Entra ID > Enterprise applications.
  3. Wähle New application.
  4. Klicke auf Create your own application.
  5. Vergib einen Namen, z. B. Bubble Chat.
  6. Wähle Integrate any other application you don't find in the gallery (Non-gallery).
  7. Klicke auf Create.
  8. Öffne in der neuen App den Bereich Single sign-on und wähle SAML.

Basic SAML Configuration​

In Basic SAML Configuration werden mindestens folgende Werte benötigt:

  • Identifier (Entity ID): frei definierbarer Issuer-Wert, z. B. bubble-chat
  • Reply URL (Assertion Consumer Service URL): URL des Bubble-Chat-Endpunkts für den SAML-Callback

Beispiel für CMS:

Hinweis für Website Messenger:

  • Die Reply URL ist projektspezifisch und muss dem für den Messenger konfigurierten SAML-Callback entsprechen.
  • Verwende hierfür den von Bubble Chat bereitgestellten Endpunkt.

Werte aus Entra ID für Bubble Chat​

Für die Bubble-Chat-Konfiguration werden aus Entra ID insbesondere folgende Werte benötigt:

  • Login URL (aus Set up [Application Name] SSO) → entryPoint
  • Certificate (Base64) (aus SAML Signing Certificate) → idpCert
  • Identifier (Entity ID) aus der Basic SAML Configuration → issuer

Benutzerattribute und Claims​

Damit Benutzerdaten korrekt in Bubble Chat ankommen, müssen die benötigten Claims im Bereich User Attributes & Claims bereitgestellt werden.

Empfohlen:

  • E-Mail (z. B. mail oder user.mail)
  • Vorname (z. B. givenname)
  • Nachname (z. B. surname)

Zusätzlich sollte geprüft werden, welcher Wert als Name ID übertragen wird (z. B. E-Mail-Adresse), damit Benutzer eindeutig zugeordnet werden können.

Zuordnung für CMS und Website Messenger​

Die SAML-Basisparameter (Issuer, Entry Point, IdP-Zertifikat) sind für beide Einsatzfälle gleichartig. Unterschiede bestehen vor allem bei der Reply URL, da CMS und Website Messenger unterschiedliche Callback-Endpunkte haben können.

Empfehlung:

  • Pro Einsatzfall (CMS, Website Messenger) die von Bubble Chat bereitgestellte Reply URL verwenden
  • Bei separaten Anwendungen in Entra ID je Einsatzfall eigene Reply URL(s) hinterlegen

Validierung nach der Einrichtung​

  • Login startet und leitet zu Entra ID weiter
  • Anmeldung bei Entra ID erfolgreich
  • Rückleitung zu Bubble Chat erfolgt ohne Fehler
  • Benutzer ist in Bubble Chat angemeldet
  • Benutzerattribute (mindestens E-Mail, Vorname, Nachname) werden korrekt übernommen

Typische Fehlerquellen​

  • Reply URL stimmt nicht exakt mit dem konfigurierten Bubble-Chat-Endpunkt überein
  • Zertifikat wurde unvollständig übernommen
  • Issuer-Wert in Entra ID und Bubble Chat stimmt nicht überein
  • Clock Skew zwischen Systemen führt zu ungültigen Assertions
  • Benötigte Claims (E-Mail, Vorname, Nachname) fehlen oder sind falsch zugeordnet

Weiterführende Kapitel​