Microsoft¶
Die Microsoft-Anbindung von Zammad ermöglicht es Ihren Benutzern mit Microsoft-Konten, sich anzumelden. Dies funktioniert auch für Entra-ID-Benutzer und kann eine Alternative zu LDAP/Active Directory darstellen. Die Konfiguration in Zammad finden Sie unter Einstellungen > Sicherheit > Anwendungen von Drittanbietern im Abschnitt Anmeldung über Microsoft. Für den Zugriff ist die Berechtigung admin.security erforderlich.
Bemerkung
Diese Seite behandelt nicht den Microsoft 365 E-Mail-Kanal.
Einschränkungen¶
Bitte beachten Sie, dass Zammad nur diese Kontotypen unterstützt (App-abhängig):
Single tenant only: Anmeldung beschränkt auf Benutzer (oder Gäste) in Ihrem eigenen Tenant.
Multiple Entra ID tenants: Ermöglicht Benutzern in beliebigen Microsoft Entra-Tenants die Anmeldung.
Any Entra ID tenant + personal Microsoft accounts: Ermöglicht Benutzern in beliebigen Microsoft Entra-Tenants sowie Benutzern mit persönlichen Microsoft-Konten (z.B. Skype, Xbox) die Anmeldung.
Eine Microsoft-App in Entra ID registrieren¶
Melden Sie sich beim Microsoft Entra Admin Center an, rufen Sie App registrations auf und erstellen Sie eine neue App. Geben Sie die erforderlichen Informationen ein, um Ihre App zu registrieren.
- Name
Wählen Sie einen aussagekräftigen Namen. Dieser wird Benutzern angezeigt, die versuchen, sich mit dieser Anwendung zu authentifizieren.
- Unterstützte Konten-Typen
Wählen Sie einen der oben aufgeführten Kontotypen aus. Der richtige Kontotyp hängt von Ihrem Anwendungsfall ab. Wenn Sie nur die interne Authentifizierung verwenden möchten, wählen Sie die erste Option. Wenn Sie unsicher sind, verwenden Sie den Link „Help me choose…“.
- Redirect URI (optional)
Wählen Sie Web als Plattform aus und geben Sie Ihre Callback-URL an. Sie finden diese im schreibgeschützten Feld Ihre Callback-URL von Zammad, wo Sie sie kopieren können. Fügen Sie sie in das Feld „Redirect URI“ in der App-Konfiguration von Microsoft ein.
Die Callback-URL sieht wie folgt aus:
https://zammad.example.com/auth/microsoft_office365/callback
Für die Anmeldung ist lediglich die API-Berechtigung User.Read erforderlich, über die neue Apps bereits verfügen. Sie können dies unter API permissions unter Microsoft Graph > Delegated permissions überprüfen. Der Scope openid ist Teil des Anmeldeprotokolls und wird automatisch übermittelt, sodass keine weiteren Berechtigungen erforderlich sind.
Erstellen Sie unter Certificates & secrets ein neues Client-Secret. Notieren Sie sich den zurückgegebenen Wert des Secrets für den nächsten Schritt. Verwenden Sie nicht die Secret ID!
Hinzufügen der Anmeldedaten in Zammad¶
Nun sind Sie bereit, die Werte in Zammad einzutragen. Die folgende Tabelle ordnet die Werte aus Entra den Feldern in Zammad zu.
Entra ID |
Zammad-Feld |
Kommentar |
|---|---|---|
Application (client) ID |
App ID |
Aus Overview im Entra ID Portal. |
Client secret (value) |
App Secret |
Aus Certificates & secrets > Client secrets. Verwenden Sie den Wert („value“) und nicht die secret ID. |
Directory (tenant) ID |
Verzeichnis-ID (Mandant) |
Optional. Nur erforderlich, wenn die App den Kontotyp Single tenant only verwendet. |
Stellen Sie sicher, dass Sie den Schalter neben Anmeldung über Microsoft aktivieren, und klicken Sie auf Übermitteln, um Ihre Konfiguration zu aktivieren und zu speichern.
Optional: Eine verifizierte E-Mail-Domain für die Kontoverknüpfung voraussetzen¶
In Multi-Tenant-Umgebungen (/common) kann jeder, der sich anmeldet, eine E-Mail-Adresse aus einer beliebigen Domain angeben. Microsoft signalisiert über den Claim xms_edov („email domain owner verified“) im ID-Token, ob die Domäne dieser Adresse für den Tenant des Kontos verifiziert ist. Aktivieren Sie Erfordert eine verifizierte E-Mail-Domain, damit Zammad diese Kennzeichnung prüft, bevor eine Microsoft-Anmeldung über die E-Mail-Adresse mit einem bestehenden Zammad-Benutzer verknüpft wird.
Bemerkung
Diese Option wirkt sich nur in Verbindung mit Automatische Kontoverbindung bei der Erstanmeldung aus. Ohne diese Option verknüpft Zammad eine Anmeldung über einen Drittanbieter grundsätzlich nicht mit einem bestehenden Konto auf Basis der E-Mail-Adresse.
Ist diese Option aktiviert, ordnet Zammad eine Anmeldung nur dann einem bestehenden Benutzer zu, wenn alle folgenden Bedingungen erfüllt sind:
Das ID-Token enthält einen Claim mit dem Namen
xms_edovund dem Werttrue.Das ID-Token enthält einen nicht leeren Claim des Typs
email.Dieser
emailWert stimmt mit der E-Mail-Adresse des Kontos überein, das verknüpft werden soll (Groß- und Kleinbuchstaben werden als identisch betrachtet).
Sollte eine dieser Bedingungen nicht erfüllt sein, lehnt Zammad die Verknüpfung der Konten ab und die Anmeldung schlägt mit einer Fehlermeldung fehl: Entweder wird die E-Mail-Adresse bereits von einem anderen Benutzer verwendet, oder - falls die Option Keine Erstellung von Benutzern bei der Anmeldung aktiviert ist - existiert das Benutzerkonto nicht. Betroffene Benutzer können dennoch Zugriff erhalten: Sie melden sich auf andere Weise bei ihrem bestehenden Zammad-Konto an und verknüpfen ihr Microsoft-Konto selbst unter Profil > Verknüpfte Konten.
Solange die Option deaktiviert ist (Standardeinstellung), verlangt Zammad diesen Claim nicht: Microsoft meldet entweder eine verifizierte Domain über xms_edov oder lässt es gänzlich weg, sodass ein bestehendes Konto verknüpft wird, sobald die E-Mail-Adresse übereinstimmt. Erst durch die Aktivierung der Option wird die verifizierte Domain zur Voraussetzung.
Warnung
Beide Claims müssen zunächst in Ihrer App-Registrierung konfiguriert werden. Rufen Sie das Microsoft Entra Admin Center auf, navigieren Sie zu Entra ID > App registrations, wählen Sie Ihre App und Token configuration unter Manage aus. Wählen Sie Add optional claim, setzen Sie den Token Type auf ID token und fügen Sie die Claims email und xms_edov hinzu. Solange diese Angaben fehlen, blockiert die Aktivierung dieser Option jegliche Verknüpfung von Microsoft-Konten per E-Mail-Adresse.