Erstellen einer Unternehmensanwendung in Microsoft Entra ID

Melden Sie sich in Ihrem Microsoft Entra Admin Center (https://entra.microsoft.com/) an und rufen Sie im Menü auf der linken Seite in der Kategorie "Identität" unter "Anwendungen" den Punkt "App-Registrierungen" auf.

Anwendung erstellen

Hier können Sie dann durch Klick auf die Aktion "Neue Registrierung" eine Anwendung erstellen, über die Advolux auf Ihre Postfächer zugreifen kann.

Bitte beachten Sie, dass es mehrere Minuten und in seltenen Fällen auch Stunden dauern kann, bis die erstellte Anwendung bei den relevanten Microsoft-Systemen bekannt ist.

Vergeben Sie nun einen eindeutigen Namen für die Anwendung (Beispiel: Advolux Imap Zugriff) und passen Sie die weiteren Einstellungen wie folgt an:

• Zugriff erlauben für "Nur Konten in diesem Organisationsverzeichnis"
• Umleitungs-URI - hier den Wert "Web" und "http://localhost" einstellen

Die Anwendung kann nun mit diesen Einstellungen erstellt werden. Schließen Sie dazu die Bearbeitung mit Klick auf den Button "Registrieren" am unteren Bildrand ab.

Berechtigungen vergeben

Nachdem die Anwendung erstellt wurde, müssen Sie die Berechtigungen auf das Postfach über die Protokolle IMAP und SMTP erlauben. Wählen Sie hierzu  im Menü in der Kategorie "Verwalten" den Menüpunkt "API-Berechtigungen" aus.

Über die Aktion "Berechtigung hinzufügen" können Sie jetzt die notwendigen Berechtigungen vergeben.

Wechseln Sie zum Tabreiter "Von meiner Organisation verwendete APIs" und stellen Sie den Filter auf "Office 365 Exchange Online", wählen Sie dann in der Liste den angezeigten Eintrag "Office 365 Exchange Online":

Dann die Option "Anwendungsberechtigungen" wählen:

Sie sehen nun eine Liste von Berechtigungen, die Sie der Unternehmensanwendung zuweisen können. Wählen Sie hier die Berechtigungen "IMAP.AccessAsApp" sowie "SMTP.SendAsApp" und bestätigen Sie. Zum einfacheren Auffinden der Einträge können Sie das Filterfeld benutzen und dort z. B. den Text "asApp" eintragen:

Es sollten dann folgende Berechtigungen vorhanden sein.

  Bestätigen Sie die Zuweisung durch Ausführen der Aktion "Administratorzustimmung für ... erteilen":

Geheimen Clientschlüssel (Client Secret) erzeugen

Damit Advolux sich als berechtigte Anwendung ausweisen kann, ist es nun erforderlich, einen geheimen Clientschlüssel zu generieren (Client Secret). Wählen Sie im Menü den Punkt "Zertifikate & Geheimnisse" und dann den Tabreiter "Geheime Clientschlüssel" aus.

Durch Ausführen der Aktion "Neuer geheimer Clientschlüssel" können Sie den Schlüssel anlegen. Vergeben Sie eine Beschreibung und einen Gültigkeitszeitraum. Microsoft empfiehlt eine Gültigkeitsdauer von 180 Tagen, Sie können nach eigenem Ermessen aber auch einen längeren Zeitraum einstellen.

Nach der Erstellung wird in der Übersicht in der Liste der neue Clientschlüssel in der Spalte "Wert" angezeigt - kopieren Sie hier unbedingt über den Kopieren-Button den Eintrag in der Spalte "Wert", Sie müssen diesen in Advolux hinterlegen. 

Dieser Wert wird nur bei der Neuanlage angezeigt und kann zu einem späteren Zeitpunkt nicht mehr ausgelesen werden!

  Für die folgenden Schritte benötigen Sie die Anwendungs-ID und die Objekt-ID der erstellten Anwendung. Sie finden diese Werte in der Übersicht der Anwendung (Menüpunkt Identität > Anwendungen > Unternehmensanwendungen). Kopieren Sie diese Werte für die spätere Verwendung.

Anlegen eines "Service Principals" über die Powershell

Damit Advolux über die angelegte Unternehmensanwendung auf die Postfächer zugreifen kann, ist es zusätzlich erforderlich, einen "Service Principal" für die Unternehmensanwendung anzulegen. Öffnen Sie dazu die mit Windows ausgelieferte Powershell als Administrator und führen Sie die folgenden Schritte aus (die Befehle, die Sie in der Powershell ausführen müssen sind fett gedruckt, Werte, die Sie durch eigene Werte ersetzen müssen, zusätzlich kursiv):

Install-Module -Name ExchangeOnlineManagement

Dieser Befehl installiert die notwendigen Komponenten für die Verwaltung Ihres Exchange-Servers. Falls Sie diese Komponenten bereits installiert haben, kann dieser Schritt entfallen.

Import-module ExchangeOnlineManagement

Lädt die Komponenten für die Exchange-Verwaltung

Connect-ExchangeOnline -Organization MANDANTEN_ID

Dieser Befehl stellt nun die Verbindung zu Ihrem Exchange-Server her. Hier müssen Sie den Text MANDANTEN_ID durch Ihre von Microsoft vergebene Mandanten-ID ersetzen. Diese finden Sie in Microsoft Entra ID (https://entra.microsoft.com) im Menü unter Identität > Übersicht.

New-ServicePrincipal -AppId ANWENDUNGS_ID -ObjectId OBJEKT_ID

Hier müssen Sie wieder die Texte ANWENDUNGS_ID und OBJEKT_ID durch die beim Anlegen der Anwendung automatisch vergebenen Werte für Anwendungs-ID und Objekt-ID, die Sie in einem der vorherigen Schritte kopiert haben, ersetzen.

Get-ServicePrincipal | Where-Object { $_.AppId -eq "ANWENDUNGS_ID" } | fl 

Sie benötigen im nächsten Schritt die ID des angelegten Service Principals. Über Get-ServicePrincipal können Sie diese ermitteln. Ersetzen Sie im Befehl wieder ANWENDUNGS_ID durch die tatsächliche Anwendungs-ID.

In der Ausgabe des Befehls finden Sie die ID des Service Principals in der Zeile "Id".

Add-MailboxPermission -Identity "postfach@ihre-domain.de" -User SERVICE_PRINCIPAL_ID -AccessRights FullAccess

Ersetzen Sie den Text postfach@ihre-domain.de durch Ihre E-Mail-Adresse sowie den Text SERVICE_PRINCIPAL_ID durch die im vorherigen Befehl ermittelte ID des Service Principals. 

  Diesen Befehl müssen Sie für alle E-Mail-Postfächer, die in Advolux genutzt werden, durchführen!

  Diese Schritte sind auch in der Microsoft-Dokumentation im Abschnitt "Register service principals in Exchange" erläutert: https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth

Konfiguration in Advolux

In Advolux gelangen Sie über das Menü System > Einstellungen und dann den Punkt "E-Mail-Anbindung" zu den Einstellungen der Mailkonten. Wenn Sie bereits ein IMAP-Konto für den Zugriff verwenden, selektieren Sie dieses und klicken auf den Button "Konto ändern". Um ein neues IMAP-Konto anzulegen, klicken Sie auf "Neues Konto" und wählen dann aus der Liste "Neues-IMAP-Konto" aus.

  Die aktuellen Einstellungen für den Posteingangs-Server und den Postausgangsserver finden Sie bei Microsoft: https://learn.microsoft.com/de-de/exchange/clients-and-mobile-in-exchange-online/pop3-and-imap4/pop3-and-imap4

Auf der Seite Authentifizierungs-Einstellungen müssen Sie folgende Werte einstellen:

• In der Auswahlliste "OAuth2 Microsoft" auswählen
• Checkbox "Einstellungen manuell anpassen" anhaken
• Checkbox "Nicht die interaktive Anmeldung verwenden" anhaken

In den Eingabefeldern tragen Sie folgende Werte ein

• Anwendungs-ID: die Anwendungs-ID Ihrer im ersten Schritt in Microsoft Entra ID angelegten Anwendung
• Authority: https://login.microsoftonline.com/MANDANTEN_ID/ - den Text MANDANTEN_ID ersetzen Sie wieder durch Ihre Mandanten-ID
• Scope: https://outlook.office365.com/.default
• Client-Secret: der Wert des geheimen Clientschlüssels, den Sie im Schritt "Geheimen Clientschlüssel (Client Secret) erzeugen" angelegt haben

  Nachdem Sie die Werte entsprechend eingetragen haben, müssen Sie die Authentifizierung für das E-Mail-Konto durch Klicken auf "Authentifizierung durchführen" abschließen.

Advolux sollte hier melden, dass die Authentifizierung erfolgreich war. Der Verbindungstest für das Konto sollte dann ebenfalls erfolgreich sein.

Häufige Probleme bei der Einrichtung

Fehlermeldung in Advolux beim Schritt "Authentifizierung durchführen" oder beim Verbindungstest

Operation timed out

• Prüfen Sie, ob die Einstellungen für den Posteingangsserver und den Postausgangsserver korrekt sind (z. B. die Portnummern) 
• Überprüfen Sie in den Einstellungen Ihrer Firewall oder sonstiger Sicherheitssoftware, ob diese die Kommunikation über IMAP oder SMTP blockieren

NO AUTHENTICATE failed

Dieses Problem kann sowohl bei der Authentifizierung (Button "Authentifizierung durchführen") als auch beim Test der Verbindung nach erfolgreicher Authentifizierung auftreten. Die Meldung besagt, dass der Exchange-Server die Anmeldung ablehnt. Hierfür kann es mehrere Ursachen geben:

• Berechtigungen - fehlende Administratorzustimmung in Entra ID
• Berechtigungen - Protokolle IMAP und SMTP für Postfach nicht erlaubt

Problem: Fehlende Administratorzustimmung

Prüfen Sie in Ihrem Microsoft Entra ID Portal über das Menü Identität > Anwendungen > App-Registrierungen > Ihre Anwendung > API-Berechtigungen, ob die Zustimmung erteilt wurde. 

Wenn in der Übersicht der Berechtigungen ein Warn-Icon ( ) angezeigt wird, klicken Sie über der Liste auf die Aktion "Administratorzustimmung für ... erteilen".

Korrekt sollte die Übersicht wie folgt aussehen:

Problem: Protokolle IMAP und SMTP nicht erlaubt

Überprüfen Sie in Ihrem Microsoft 365 admin center, ob für das Postfach die erforderlichen Protokolle IMAP und SMTP aktiviert sind. Öffnen Sie dazu im Browser die Adresse https://admin.microsoft.com und navigieren Sie zum Menüpunkt Benutzer > Aktive Benutzer.

Wählen Sie in der Übersicht das Postfach aus und klicken Sie im sich öffnenden Bereich in der Kategorie E-Mail-Apps auf den Punkt "E-Mail-Apps verwalten". 

Stellen Sie sicher, dass die Optionen "IMAP" und "Authentifiziertes SMTP" aktiviert sind.

Zusätzlich ist es möglich, über die Powershell den SMTP Zugriff zu aktivieren - Microsoft bietet hier eine entsprechende Anleitung:
https://learn.microsoft.com/de-de/exchange/clients-and-mobile-in-exchange-online/authenticated-client-smtp-submission

Fehlermeldung in der Powershell beim Anlegen des Service Principals

Unbekannte Parameter

Es kann - je nach Version der Powershell - zu Fehlermeldungen kommen, die besagen, dass ein Befehlsparameter nicht bekannt ist. Hier kann es helfen, die aktuellste Version der Powershell zu installieren. Informationen zur aktuellen Version und Installationsanweisungen erhalten Sie hier: https://learn.microsoft.com/de-de/powershell/

Problem mit dem Trusted Platform Module (TPM)

Uns wurde eine Windows-Fehlermeldung gemeldet, die beim Ausführen der Befehle in der Powershell auftritt. Das Problem kann für die Durchführung der Konfiguration ignoriert werden - die Postfächer lassen sich trotz der Meldung einrichten. Für weiterführende Informationen zu dieser Fehlermeldung wenden Sie sich bitte an Microsoft.

Fehlermeldung im Browser beim Anlegen der Unternehmensanwendung in Entra ID

Funktionen nicht vorhanden oder nicht aufrufbar

Falls in Ihrem Browser Funktionen des Entra ID Portals nicht vorhanden sind, oder sich nicht aufrufen lassen (weil z. B. eine Fehlermeldung angezeigt wird), können Sie folgende Dinge versuchen:

• die Seite im Browser neu laden
• prüfen, ob die aktuelle Version des Browsers eingesetzt wird
• einen Browser eines anderen Herstellers verwenden