Einrichtung einer OAuth-App

Richten Sie ein neues Microsoft 365-/Outlook-Konto ein? Auf Grund von Microsofts Sicherheitsmaßnahmen ist die Eingabe eines Benutzernamens und eines Passworts nicht ausreichend.

Zunächst müssen Sie Zammad über das Microsoft Azure-Portal als OAuth-App mit Ihrem Microsoft-Konto verbinden. Sobald dies erledigt ist, können Sie beliebig viele Microsoft 365-Konten mit Zammad verbinden und dabei nur eine aktive Browsersitzung verwenden (keine Benutzernamen oder Passwörter erforderlich).

Bemerkung

🤔 Was bitte ist OAuth?

Wenn Sie sich bereits bei einem Dienst mit „Login über Google/Facebook/Twitter“ angemeldet haben, haben Sie OAuth bereits verwendet. OAuth ist ein Verfahren, bei dem externe Dienste nur auf einen kleinen Teil der Daten Ihres Google/Facebook/Twitter Kontos zugreifen können, ohne das Passwort preiszugeben (wodurch sie Zugriff auf alles hätten).

Wenn ein Dienst OAuth benutzen möchte, muss dieser zuerst beim Provider eingerichtet werden (z.B. Microsoft). Dadurch weiß der Provider, wer auf die Benutzer-Daten zugreift und der Benutzer kann im Zweifelsfall den Zugriff entziehen.

In diesem Fall ist Zammad der externe Dienst. Deshalb ist das hinzufügen eines Microsoft-Kontos ein zweistufiger Prozess: als erstes müssen Sie Zammad als Dienst bei Microsoft einrichten, der auf Daten zugreifen möchte. Anschließend müssen Sie sich als Microsoft-Benutzer hinzufügen, der Zammad den Abruf von E-Mails erlaubt.

Schritt für Schritt

Um loszulegen, gehen Sie zu Microsofts Azure-Portal <https://portal.azure.com/>`_. Stellen Sie sicher, dass Sie ein Administratorkonto für Ihre Organisation verwenden. Andernfalls muss ein Administrator Ihre Änderungen genehmigen, bevor sie wirksam werden können.

1. App-Registrierung hinzufügen

   Tragen Sie unter App-Registrierung > ➕ Neue Registrierung folgende Werte ein:

   Unterstützte Konten-Typen

   Wählen Sie die Option, die für Ihre Organisation am besten geeignet ist (oder klicken Sie auf Helfen Sie mir bei der Auswahl…, wenn Sie sich nicht sicher sind).

   • Nur Konten in dieser Organisationseinheit (nur Standardverzeichnis - einzelner tenant)

   • Konten in einer beliebigen Organisationseinheit (beliebiges Azur AD-Verzeichnis - Multi-Tenant)

   • Konten in einer beliebigen Organisationseinheit (beliebiges Azur AD-Verzeichnis - Multi-Tenant) und persönliche Microsoft-Konten (z.B. Skype, Xbox)

   Bemerkung

   🙅 Die Option „Nur persönliche Microsoft-Konten“ wird nicht unterstützt.

   Weiterleitungs-URI

   Web > Z.B. https://your-domain.com/api/v1/external_credentials/microsoft365/callback

   Sie finden diese in den Admin-Einstellungen unter Kanäle > Microsoft 365 > Microsoft 365 App verbinden > Ihre Callback URL.

   

2. API-Berechtigungen hinzufügen

   Fügen Sie unter API-Berechtigungen > ➕ Berechtigung hinzufügen > Microsoft Graph > Berechtigungen folgendes hinzu:

   OpenId-Berechtigungen

   • email

   • offline_access

   • openid

   • profile

   IMAP

   • IMAP.AccessAsUser.all

   SMTP

   • SMTP.Send

   

3. Weitere Informationen zur Administrator-Zustimmung (optional)

   Hinweis

   Dieser Schritt ist nur bei Tenants erforderlich, bei denen eine Administrator-Zustimmung eingerichtet ist. Die Zustimmung des Administrators bietet eine weitere Sicherheitsebene für die Benutzer Ihres Tenants und ermöglicht es Administratoren zu definieren, wer Benutzerinformationen weitergeben darf.

   Wählen Sie unter Unternehmensanwendungen Ihre App aus. Wenn Sie im Rahmen der App-Registrierungen eine App erstellen, erstellt Microsoft automatisch auch eine Unternehmensanwendung für Sie.

   Setzen Sie Zuweisung erforderlich in den App-Eigenschaften auf Ja und klicken Sie auf Speichern. Dies aktiviert Ihre App und fordert die Zustimmung des Administrators an.

   

   3.1 Ihre App noch weiter anpassen (empfohlen, optional)

   Dieser Schritt schützt Ihre Tenant-Benutzer vor unerwünschten Anpassungen der Berechtigungen (z.B. der Anforderung von mehr Berechtigungen als ursprünglich angegeben).

   Es hat noch einen weiteren Vorteil: Sie können das betreffende E-Mail-Konto sofort hinzufügen, ohne dass ein Administrator manuell eingreifen muss.

   Wählen Sie in Unternehmensanwendungen > Benutzer und Gruppen aus. In diesem Abschnitt können Sie bestimmte Benutzer und/oder Gruppen auswählen (Benutzer müssen direkte Mitglieder sein!), die Ihre App zum Hinzufügen von Postfächern zu Zammad verwenden dürfen.

   Nachdem Sie Benutzer und Gruppen hinzugefügt haben, kehren Sie zur Startseite des Azure-Portals zurück und wählen Sie App-Registrierung aus. Gehen Sie in Ihrer gewünschten App zu API-Berechtigungen und verwenden Sie die Schaltfläche Administrator-Zustimmung für {Unternehmensname} erteilen, um die Verbindung für Benutzer zu erlauben, denen Sie zuvor zugestimmt haben.

   Bemerkung

   Wenn Benutzer/Gruppen nicht sofort hinzugefügt oder Administrator-Zustimmung nicht sofort erteilt wird, erzwingt Microsoft zumindest den ersten Benutzer dazu, einen Grund für die Zustimmungs-Anfrage anzugeben. Danach erteilt Microsoft automatisch die Zustimmung für Ihren Mandanten.

   Administrator-Konten können auch die Option „Einwilligung im Namen Ihrer Organisation“ im oben genannten Berechtigungsdialog verwenden.

   

4. Verbinden Ihrer Microsoft-App mit Zammad

   Kopieren Sie die Application (client) ID und Directory (tenant) ID aus Ihrer App-Registrierung (zu finden unter Overview > Essentials) in Zammad im Admin-Bereich unter Kanäle > Microsoft 365 > Microsoft 365-App verbinden.

   Erstellen Sie dann unter Certificates and Secrets > ➕ New Client Secret ein solches und kopieren Sie es ebenfalls im Zammad Admin-Bereich in das vorgesehene Feld.

   

🍾 Herzlichen Glückwunsch! Jetzt können Sie Microsoft 365- oder Outlook-Konten mit Zammad verbinden.