Alarmserver - Microsoft Outlook Postfächer abfragen

Anlegen einer Anwendung in Azure

Offizielle Dokumentation https://learn.microsoft.com/de-de/azure/active-directory/develop/quickstart-register-app

1. Öffnen Sie das Azure-Portal https://portal.azure.com
2. Kopieren Sie sich die Mandanten-ID (hier bspw. 0123456-123f-123f-a012-123abcdef123)
   
   
   
3. Klicken Sie im Azure-Portal auf Verwalten > App-Registrierungen > + Neue Registrierung
   
   
4. Geben Sie als Namen bspw. "Integration mit DIVERA 24/7 Alarmserver" oder  einen anderen für Sie sprechenden Namen ein.
   
   Wählen Sie für unterstützte Kontotypen "Nur Konten in diesem Organisationsverzeichnis" aus
   
   Das Feld zur Umleitungs-URI kann leergelassen werden.
   
   Die Anwendung kann mit "Registrieren" dann erstellt werden.
   
   
5. Falls Sie nicht sofort in der Detailseite landen: In der Übersichtsliste (App-Registrierungen) finden Sie jetzt die soeben erstellte Anwendung, kopieren und notieren Sie sich die Anwendungs-ID
   
   
   
6. Öffnen Sie in der Detailansicht der Anwendung, und dann Verwalten > API-Berechtigungen, und klicken dort auf Berechtigung hinzufügen
   
   
   Wählen Sie dort "Von meiner Organisation verwendete APIs" und suchen nach "office", um "Office 365 Exchange Online" auszuwählen
   
   
   Wählen Sie dort Anwendungsberechtigungen > IMAP > IMAP.AccessAsApp aus.
   
   
   und  abschließend auf "Berechtigungen hinzufügen"
   
   
7. Der Anwendung muss jetzt von Ihnen zugestimmt werden, damit sie grundsätzlich in Ihrer Organisation verwendet werden kann.
    
   Wichtig: hieraus leitet sich nicht ab, dass diese Anwendung bereits Zugriff auf ein Postfach hat. Das muss explizit pro Postfach im nächsten Schritt erfolgen
   
   
8. Sie müssen jetzt noch für die Anwendung einen Zugangsschlüssel erzeugen. Öffnen Sie dazu Verwalten > Zertifikate & Geheimnisse > Geheime Clientschlüssel > Neuer geheimer Clientschlüssel
   
   
   Im Dialog geben Sie eine für sich sprechende Beschreibung ein, und wählen den Gültigkeitszeitraum, der für Ihren Anwendungsfall passend ist. 
   
   
   
   Kopieren Sie nach der Erstellung unmittelbar den Inhalt der Spalte "Wert" – er ist nur nach Erzeugung sichtbar und wird Ihnen später nicht mehr angezeigt werden! Er wird später in DIVERA 24/7 als "Client Secret" eingetragen.
   
   
   
9. Für den nächsten Schritt benötigen Sie noch die Objekt-ID der installierten Anwendung. Achtung, hierbei ist es wichtig im folgenden nicht die Objekt-ID der App-Registrierung zu notieren!
   Öffnen Sie dazu aus der Azure-Portal Ansicht Verwalten > Unternehmensanwendungen und suchen nach dem Namen der Anwendung
   
   Öffnen Sie die Detailansicht und kopieren die dort angezeigte Objekt-ID.

Sie sollten jetzt alle notwendigen Informationen beisammen haben. Ihre Mandanten-ID, die Anwendungs-ID, das Client-Secret und die Objekt-ID der installierten Anwendung. Sie werden diese Informationen in den nächsten Schritten benötigen.

Der Anwendung Zugriff auf ein Postfach erteilen

Offizielle Dokumentation: https://learn.microsoft.com/de-de/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth#register-service-principals-in-exchange

1. Installieren Sie gegebenenfalls die PowerShell, es ist mindestens Version 5.1 erforderlich: https://learn.microsoft.com/de-de/powershell/scripting/install/installing-powershell-on-windowsl
2. Öffnen Sie die PowerShell und führen folgende Befehle aus, um das ExchangeOnlineManagement Modul zu laden
   

   Install-Module -Name ExchangeOnlineManagement
   Import-Module ExchangeOnlineManagement
   

3. Anschließend verbinden Sie Ihre PowerShell-Session mit Ihrer Organisation über folgende Eingabe. Es öffnet sich normalerweise das Browser-Fenster, in dem Sie sich bei Microsoft 365 einloggen müssen. 
   (Die spitzen Klammen <> sind jeweils nicht mit anzugeben, die Mandanten-ID, sowie Anwendungs-ID und Objekt-ID sind aus Schritt 1)
   

   Connect-ExchangeOnline -Organization <mandanten-id>

4. Legen Sie eine ServicePricipal für die Anwendung an
   

   New-ServicePrincipal -DisplayName "Integration DIVERA 24/7 Alarmserver" -AppId <anwendungs-id> -ObjectId <objekt-id>

   Falls Sie eine alte Version des ExchangeOnline Befehls verwenden, müssen Sie ggf. -ServiceId statt -ObjectId als Parameter benutzen
   
   
5. Lassen Sie sich die soeben erstellte "Identity" der ServicePrincipal ausgeben. Dazu wird der Parameter Identity mit dem DisplayName zum Filter gefüllt.

   Get-ServicePrincipal -Identity "Integration DIVERA 24/7 Alarmserver" | Select Identity
   Identity
   --------
   <service-principal-identity>

   
   und erstellen die Berechtigung zum Mailbox-Zugriff, verwenden Sie hierbei die ServicePrincipal-Identity als "User"-Parameter
   

    Add-MailboxPermission -Identity "maxime@muster.gmbh" -User <service-principal-id> -AccessRights FullAcces

Hinterlegen der Zugangsdaten in DIVERA 24/7

1. Navigieren Sie zu Verwaltung > Einstellungen > Schnittstellen > Alarmserver und klicken Sie dann im unteren Bereich auf "+ Postfach"
   
2. Auf der neuen Seite müssen Sie zunächst die Art der Verbindung von "IMAP (Standard)" auf IMAP (Office 365 OAuth) ändern.
   
3. Jetzt hinterlegen Sie  analog zu normalen Postfächer zunächst den IMAP-Server von Office365.
   Dieser ist zum aktuellen Zeitpunkt outlook.office365.com, Port 993 mit TLS.
   
4. Anschließend verwenden Sie Ihre E-Mail-Adresse als Benutzernamen ein. Füllen das Feld Mandanten-ID mit der Login-URL + Mandanten-ID. In der Regel https://login.microsoftonline.com/<VERZEICHNIS-ID>. Die Anwendungs-ID und den geheimen Clientschlüssel haben Sie im vorherigen Schritt erstellt.
   
5. Nach einem Klick auf "Speichern" ist das Postfach erfolgreich hinterlegt! Warten Sie ca. 1 Minute ab, anschließend können Sie einen Test durchführen. Passen Sie dazu gegebenenfalls kurzzeitig die Standardeinstellungen der Schnittstelle an.