Einrichtung einer OAuth-App

Sie möchten ein neues Microsoft 365 Konto einrichten? Folgen Sie unserer Anleitung zur grundlegenden Einrichtung, um loszulegen.

Zunächst müssen Sie Zammad über das Microsoft Entra-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).

Vorbereitung

• Nur relevant für selbst gehostete Zammad-Instanzen: Überprüfen Sie Ihren FQDN unter Einstellungen > System > Vollqualifizierter Domainname in Einstellungen Zammad. Wenn er nicht korrekt ist, ändern Sie ihn jetzt. Andernfalls wird die Einrichtung des Kanals fehlschlagen.

• Gehen Sie zu Kanäle > Microsoft 365 IMAP E-Mail und klicken Sie auf Microsoft 365 App verbinden. Kopieren Sie die angezeigte Callback-URL.

Schritt für Schritt

Um loszulegen, gehen Sie zu Microsofts Entra-Portal. Stellen Sie sicher, dass Sie ein Administratorkonto für Ihre Organisation verwenden. Andernfalls muss ein Administrator Ihre Änderungen genehmigen, bevor sie loslegen können.

App erstellen

• Erstellen Sie eine neue App, indem Sie zu Applications > App registrations gehen und New registration wählen.

• Geben Sie einen passenden Namen ein und wählen Sie einen Kontotyp. Unterstützte Typen sind:

  • Nur Konten in diesem Organisationsverzeichnis (einzelner Mandant)

  • Konten in einem beliebigen Organisationsverzeichnis (mandantenfähig)

  • Konten in beliebigen Organisationsverzeichnissen (Multitenant) und persönliche Microsoft Konten (z.B. Skype, Xbox)

    Bemerkung

    „Nur persönliche Microsoft-Konten“ werden nicht unterstützt.

• Wählen Sie unter Redirect URI die Plattform Web und fügen Sie die bereits kopierte Callback URL von Zammad ein.

• Klicken Sie auf Register.

Geheimnis erstellen

• Gehen Sie in Entra zu Certificates & secrets und fügen Sie ein Secret hinzu, indem Sie auf die Schaltfläche New client secret klicken.

• Geben Sie eine Beschreibung ein, legen Sie eine Gültigkeitsdauer fest und klicken Sie auf Hinzufügen.

• Kopieren Sie die Zeichenkette unter Value, dies ist das Secret. Fügen Sie es bei Zammad in das Feld Client-Secret ein.

  Warnung

  Achten Sie darauf, den Wert des Value zu kopieren, nicht die ID. Andernfalls schlägt Ihre Einrichtung fehl.

API-Berechtigungen konfigurieren

• Gehen Sie zu API permissions und fügen eine Berechtigung über Add a permission hinzu.

• Wählen Sie Microsoft Graph und Delegated permissions.

• Fügen Sie die folgenden Berechtigungen hinzu:

  • email

  • openid

  • profile

  • offline_access

  • IMAP.AccessAsUser.all

  • SMTP.Send

Speichern Sie sie, indem Sie auf die Schaltfläche Add permissions klicken.

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 Enterprise applications Ihre App aus. Wenn Sie per App registrations eine App erstellen, erstellt Microsoft automatisch auch eine Unternehmensanwendung für Sie.

Setzen Sie Assignment required in den App-Eigenschaften auf Yes und klicken Sie auf Save. Dies aktiviert Ihre App und fordert die Zustimmung des Administrators an.

Optimierung der App (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 Users and groups in Enterprise applications. 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 registrations aus. Gehen Sie in Ihrer gewünschten App zu API permissions und verwenden Sie die Schaltfläche Grant admin consent for {company name}, 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 Consent on behalf of your organization im oben genannten Berechtigungsdialog verwenden.

App Konfiguration

• Klicken Sie in der Kanalkonfiguration von Zammad auf App konfigurieren.

• Geben Sie Ihre App-Details ein:

  • Client ID: Application (client) ID

  • Client Secret: Value bzw. Wert des Client secrets (nicht die „Secret ID“!)

  • Tenant UUID/Name: Directory (tenant) ID (nicht erforderlich für freigegebene Postfächer)

• Klicken Sie auf Übermitteln.

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