Microsoft 365: App-only OAuth IMAP für eine automatisierte Migration vorbereiten

Bei der Migration einer großen Anzahl von Microsoft-365-Postfächern zu einer anderen Mailplattform ist die IMAP-Authentifizierung per Passwort in der Regel blockiert. Der richtige Ansatz besteht darin, eine Microsoft-Entra-ID-Anwendung mit einer Exchange-Online-Anwendungsberechtigung zu erstellen und ihr anschließend explizit Zugriff auf die zu migrierenden Postfächer zu geben. Diese Anleitung beschreibt die Schritte, die auf Kundenseite auszuführen sind.

Funktionsprinzip

Es gibt zwei Möglichkeiten, OAuth2 mit Microsoft 365 IMAP zu verwenden:

• Delegiertes OAuth: Ein Benutzer meldet sich an und autorisiert die Anwendung für sein eigenes Postfach. Dieser Modus eignet sich nicht für eine Massenmigration.
• Anwendungs-OAuth, auch app-only genannt: Die Anwendung authentifiziert sich mit einem eigenen Secret oder Zertifikat. Das ist der passende Modus, um die Migration vieler Postfächer zu automatisieren.

Für eine Massenmigration verwenden Sie daher den Modus app-only. Der Microsoft-365-Administrator erstellt eine Anwendung, erteilt ihr die Berechtigung IMAP.AccessAsApp und autorisiert diese Anwendung anschließend ausdrücklich für den Zugriff auf die betreffenden Postfächer in Exchange Online.

Vorbereitung

Stellen Sie vor Beginn sicher, dass Sie Folgendes haben:

• ein Microsoft-365-Administratorkonto mit Zugriff auf Microsoft Entra ID;
• Administratorzugriff auf Exchange Online PowerShell;
• die Liste der zu migrierenden Postfächer;
• die Möglichkeit, eine App-Registrierung zu erstellen und eine Administratorzustimmung zu erteilen.

Schritt 1: Anwendung in Microsoft Entra ID erstellen

1. Öffnen Sie das Microsoft-Entra-Admin-Center unter entra.microsoft.com.
2. Gehen Sie zu Microsoft Entra ID → App-Registrierungen.
3. Klicken Sie auf Neue Registrierung.
4. Name: InfoSwitch Migration IMAP oder ein gleichwertiger Name.
5. Unterstützte Kontotypen: Nur Konten in diesem Organisationsverzeichnis.
6. Umleitungs-URI: für den app-only-Modus nicht erforderlich.
7. Bestätigen Sie die Erstellung.

Nachdem die Anwendung erstellt wurde, notieren Sie die folgenden zwei Werte:

• Anwendungs-ID (Client)
• Verzeichnis-ID (Mandant)

Schritt 2: IMAP-Anwendungsberechtigung hinzufügen

1. Öffnen Sie in der erstellten Anwendung API-Berechtigungen.
2. Klicken Sie auf Berechtigung hinzufügen.
3. Wählen Sie APIs, die meine Organisation verwendet.
4. Suchen Sie nach Office 365 Exchange Online.
5. Auf dem nächsten Bildschirm fragt Microsoft Entra nach dem Berechtigungstyp: Wählen Sie Anwendungsberechtigungen, nicht Delegierte Berechtigungen.
6. Aktivieren Sie IMAP.AccessAsApp.
7. Fügen Sie die Berechtigung hinzu.
8. Klicken Sie auf Administratorzustimmung erteilen.

Schritt 3: Client Secret erstellen

1. Öffnen Sie in der Anwendung Zertifikate & Geheimnisse.
2. Klicken Sie auf Neuer geheimer Clientschlüssel.
3. Wählen Sie eine Ablaufdauer von 90 Tagen. Das reicht für den Migrationszeitraum und begrenzt gleichzeitig die Gültigkeitsdauer des Secrets.
4. Kopieren Sie sofort den Wert des Secrets.

Speichern Sie den Wert des Client Secrets an einem sicheren Ort. Er ist später in Microsoft Entra ID nicht mehr sichtbar. Wenn Sie ihn verlieren, müssen Sie ein neues Secret erstellen.

Schritt 4: Object ID der Unternehmensanwendung abrufen

Dieser Schritt ist wichtig: Exchange Online verwendet nicht die Object ID, die in der App-Registrierung sichtbar ist. Sie müssen die Object ID der Unternehmensanwendung abrufen, also des Service Principals, der in Ihrem Tenant erstellt wurde.

1. Öffnen Sie in Microsoft Entra ID Unternehmensanwendungen.
2. Suchen Sie nach der Anwendung InfoSwitch Migration IMAP.
3. Öffnen Sie deren Detailseite.
4. Kopieren Sie die Objekt-ID.

In den folgenden Befehlen wird dieser Wert ENTERPRISE_OBJECT_ID genannt.

Schritt 5: Service Principal in Exchange Online registrieren

Öffnen Sie PowerShell als Administrator und stellen Sie eine Verbindung zu Exchange Online her:

# Exchange-Online-Modul installieren und laden
Install-Module ExchangeOnlineManagement -Scope CurrentUser
Import-Module ExchangeOnlineManagement
Connect-ExchangeOnline

Definieren Sie die folgenden Variablen:

# Werte durch die in Entra abgerufenen Angaben ersetzen
$ApplicationId = "ANWENDUNGS_CLIENT_ID"
$EnterpriseObjectId = "ENTERPRISE_OBJECT_ID"
$DisplayName = "InfoSwitch Migration IMAP"

Registrieren Sie anschließend den Service Principal in Exchange Online:

# Entra-Anwendung in Exchange Online registrieren
New-ServicePrincipal -AppId $ApplicationId -ServiceId $EnterpriseObjectId

Falls erforderlich, geben Sie ihm einen lesbaren Namen:

# Optional: lesbaren Namen definieren
Set-ServicePrincipal -Identity $EnterpriseObjectId -DisplayName $DisplayName

Prüfen Sie, ob Exchange Online den Service Principal kennt:

# Prüfen, ob der Service Principal in Exchange Online bekannt ist
Get-ServicePrincipal | Where-Object {$_.AppId -eq $ApplicationId}

Schritt 6: Zu migrierende Postfächer autorisieren

Microsoft gewährt nicht automatisch Zugriff auf alle Postfächer des Tenants. Der Zugriff muss für die betroffenen Postfächer erteilt werden. Damit Konten nicht einzeln bearbeitet werden müssen, bereiten Sie eine CSV-Datei mit allen zu migrierenden Adressen vor.

So generieren Sie aus Exchange Online eine CSV-Datei mit Benutzerpostfächern und freigegebenen Postfächern:

# mailboxes.csv mit Benutzerpostfächern und freigegebenen Postfächern erzeugen
Get-Mailbox -ResultSize Unlimited -RecipientTypeDetails UserMailbox,SharedMailbox |
    Select-Object @{Name="Email";Expression={$_.PrimarySmtpAddress.ToString()}} |
    Export-Csv .\mailboxes.csv -NoTypeInformation -Encoding UTF8

Freigegebene Postfächer, einschließlich nicht lizenzierter freigegebener Postfächer, können mit diesem app-only-Modus migriert werden, wenn sie in der CSV-Datei enthalten sind, wenn die Anwendung FullAccess erhält und wenn IMAP aktiviert ist.

Email
vorname.nachname@domain.de
kontakt@domain.de
support@domain.de

Um alle Postfächer aus der Datei mailboxes.csv mit einem einzigen Befehl zu autorisieren:

# Alle in mailboxes.csv aufgeführten Postfächer autorisieren
Import-Csv .\mailboxes.csv | ForEach-Object {
    Add-MailboxPermission -Identity $_.Email -User $EnterpriseObjectId -AccessRights FullAccess
}

Sie können die Berechtigungen für alle in der CSV-Datei aufgeführten Postfächer prüfen:

# Berechtigungen für alle in mailboxes.csv aufgeführten Postfächer prüfen
Import-Csv .\mailboxes.csv | ForEach-Object {
    Get-MailboxPermission -Identity $_.Email | Where-Object {
        $_.User -like "*$EnterpriseObjectId*"
    } | Select-Object @{Name="Mailbox";Expression={$_.Identity}},User,AccessRights
}

Schritt 7: Prüfen, ob IMAP aktiviert ist

OAuth-Zugriff reicht nicht aus, wenn IMAP auf den Postfächern deaktiviert ist. Prüfen Sie den IMAP-Status der in der CSV-Datei aufgeführten Postfächer:

# Prüfen, ob IMAP für alle in mailboxes.csv aufgeführten Postfächer aktiviert ist
Import-Csv .\mailboxes.csv | ForEach-Object {
    Get-CASMailbox -Identity $_.Email | Select-Object PrimarySmtpAddress,ImapEnabled
}

Um IMAP für alle Postfächer in der Datei mailboxes.csv zu aktivieren:

# IMAP für alle in mailboxes.csv aufgeführten Postfächer aktivieren
Import-Csv .\mailboxes.csv | ForEach-Object {
    Set-CASMailbox -Identity $_.Email -ImapEnabled $true
}

Häufige Fehler

Ungültiger Scope oder Token ohne IMAP-Berechtigung

Prüfen Sie, ob für den app-only-Token der folgende Scope verwendet wird:

https://outlook.office365.com/.default

Prüfen Sie außerdem, ob die Anwendung die Anwendungsberechtigung IMAP.AccessAsApp für Office 365 Exchange Online besitzt und die Administratorzustimmung erteilt wurde.

IMAP-Authentifizierung trotz gültigem Token verweigert

Die häufigsten Ursachen sind:

• Der Service Principal wurde nicht mit New-ServicePrincipal in Exchange Online registriert;
• die verwendete Object ID ist nicht die Object ID der Unternehmensanwendung;
• das Postfach hat für diesen Service Principal keine FullAccess-Berechtigung erhalten;
• IMAP ist auf dem Postfach deaktiviert;
• die Berechtigungen wurden gerade erst hinzugefügt und sind noch nicht verteilt;
• die IMAP-Verbindung wird mit einer anderen Postfachadresse versucht als der autorisierten.

Blockierung durch Conditional Access

Einige Organisationen wenden Conditional-Access-Richtlinien auf Workload-Identitäten, Unternehmensanwendungen oder Service Principals an. Wenn der app-only-Token abgerufen wird, IMAP-Verbindungen aber im gesamten Tenant systematisch verweigert werden, prüfen Sie, ob keine Conditional-Access-Richtlinie diese Anwendung oder app-only-Verbindungen zu Exchange Online blockiert.

Wird ein Refresh Token benötigt?

Nein, nicht im app-only-Modus. Der Server kann jederzeit mit client_id, tenant_id und client_secret einen neuen Access Token anfordern. Der erhaltene Token läuft in der Regel nach einer begrenzten Zeit ab, kann aber automatisch ohne Benutzerinteraktion erneuert werden.

Informationen, die an InfoSwitch zu übermitteln sind

Nach Abschluss der Konfiguration übermitteln Sie ausschließlich über einen sicheren Kanal:

• die Anwendungs-ID (Client);
• die Verzeichnis-ID (Mandant);
• den Wert des Client Secrets;
• die Bestätigung, dass der Service Principal in Exchange Online registriert wurde;
• die Bestätigung, dass die zu migrierenden Postfächer die Berechtigung FullAccess für diesen Service Principal erhalten haben;
• die Bestätigung, dass IMAP auf den betreffenden Postfächern aktiviert ist;
• die CSV-Liste der zu migrierenden Postfächer, falls sie noch nicht bereitgestellt wurde.