Zum Hauptinhalt springen

Azure-App-Registrierung für PowerShell-Postfachmigrationen einrichten

So richten Sie eine Azure-App-Registrierung ein, um PowerShell-Postfachmigrationen mit ShareGate Migrate ohne angemeldetes Benutzerkonto auszuführen.

Hinweis: Für die PowerShell-Integration ist ein ShareGate Migrate Pro- oder Enterprise-Abonnement erforderlich. Sie ist im Essentials-Plan nicht verfügbar.

Dieser Artikel gilt nur für die PowerShell-Integration von ShareGate Migrate. Mit der reinen Anwendungsauthentifizierung können Sie Postfachmigrationen über PowerShell ausführen, ohne dass ein Benutzer angemeldet sein muss. Anstelle von Benutzeranmeldeinformationen authentifiziert sich ShareGate Migrate über eine Azure-App-Registrierung. Dies eignet sich besonders für automatisierte oder geplante Migrationen in Unternehmensumgebungen.

Während der Einrichtung erfassen Sie zwei Werte, die Sie an die PowerShell-Befehle von ShareGate übergeben: die Application (client) ID und die Directory (tenant) ID.

Bevor Sie beginnen

  • ShareGate Migrate Pro- oder Enterprise-Abonnement

  • Zugriff als Globaler Administrator sowohl auf den Quell- als auch auf den Ziel-Microsoft 365-Mandanten, erforderlich zum Erstellen der App-Registrierung und zum Erteilen der Administratorzustimmung

Single-Tenant vs. Multi-Tenant

Wenn Sie den Unterschied zwischen diesen beiden Begriffen kennen, fällt es Ihnen leichter, die richtige Einrichtung zu wählen:

  • Eine App-Registrierung ist die Blaupause der Anwendung. Sie befindet sich im Home-Mandanten (dem Mandanten, in dem Sie sie erstellen) und definiert die Identität, die API-Berechtigungen und die Zertifikate der App.

  • Eine Unternehmensanwendung (auch Dienstprinzipal genannt) ist die lokale Instanz dieser App innerhalb eines bestimmten Mandanten. Ihr erteilen Sie die Administratorzustimmung und weisen ihr Rollen zu.

Wählen Sie je nach Anzahl der Mandanten, die Sie migrieren:

  • Single-Tenant: Die App wird nur in dem Mandanten verwendet, in dem Sie sie registrieren. Wählen Sie unter Supported account types die Option My organization only. Um zwischen zwei Mandanten zu migrieren, wiederholen Sie die vollständige Einrichtung in jedem Mandanten.

  • Multi-Tenant: Eine App-Registrierung in Ihrem Home-Mandanten, die in mehreren Mandanten wiederverwendet wird. Dies ist die gängige Wahl für Berater, Managed Service Provider und Quelle-zu-Ziel-Migrationen. Wählen Sie unter Supported account types die Option Multiple Entra ID tenants und lassen Sie Allow all tenants aktiviert. Anschließend stimmen Sie der App in jedem weiteren Mandanten zu und weisen dort die Rolle Exchange Administrator zu. Siehe Weitere Mandanten einrichten weiter unten.

Bei einer Multi-Tenant-App erstellen Sie das Anmeldeinformationsobjekt einmal und übergeben für jeden Mandanten eine andere -TenantId an Connect-MicrosoftOnline.

App-Registrierung einrichten

Führen Sie dies in Ihrem Home-Mandanten durch. Bei einer Single-Tenant-App wiederholen Sie dies in jedem Mandanten, zu dem oder von dem Sie migrieren. Bei einer Multi-Tenant-App führen Sie dies einmal durch und folgen anschließend den Schritten unter Weitere Mandanten einrichten weiter unten.

Option 1: Manuelle Einrichtung im Azure-Portal

Schritt 1: App-Registrierung erstellen

  1. Melden Sie sich als Globaler Administrator beim Microsoft Entra Admin Center an.

  2. Gehen Sie zu Entra ID > App registrations > New registration.

  3. Geben Sie der App einen Namen (zum Beispiel ShareGate Mailbox Migration).

  4. Wählen Sie unter Supported account types die Option, die Ihrem Szenario entspricht. Siehe Single-Tenant vs. Multi-Tenant weiter oben.

  5. Lassen Sie das Feld Redirect URI vorerst leer.

  6. Klicken Sie auf Register.

  7. Kopieren Sie auf der Seite Overview die Application (client) ID und die Directory (tenant) ID. Diese benötigen Sie für New-AzureApplication und Connect-MicrosoftOnline. Notieren Sie sich außerdem den Display name oder die Object ID für die Rollenzuweisung in Schritt 4.

Schritt 2: Antwort-URL hinzufügen

Hinweis: Dieser Schritt ist für Multi-Tenant-Apps erforderlich. Ohne mindestens eine Antwort-URL kann die Administratorzustimmung nicht abgeschlossen werden. https://go.sharegate.com/vmen ist eine ShareGate-Landingpage, die die erfolgreiche Zustimmung bestätigt.

  1. Gehen Sie in Ihrer App-Registrierung zu Authentication und klicken Sie auf + Add Redirect URI.

  2. Geben Sie im Bereich Web platform unter Redirect URI Folgendes ein: https://go.sharegate.com/vmen.

  3. Klicken Sie auf Configure.

Schritt 3: API-Berechtigungen hinzufügen

Wählen Sie eine der beiden folgenden Methoden.

Option A: Manuell über das Azure-Portal

  1. Gehen Sie zu API permissions > Add a permission.

  2. Fügen Sie jede der unten aufgeführten Application permissions hinzu (nicht Delegated). Die Microsoft Graph-Berechtigungen und die Office 365 Exchange Online-Berechtigungen fügen Sie getrennt hinzu.

  3. Klicken Sie auf Grant admin consent for [your tenant] und bestätigen Sie.

Microsoft Graph-Berechtigungen:

Mail.ReadWrite

E-Mail-Elemente

Calendars.ReadWrite

Kalenderereignisse

Contacts.ReadWrite

Kontakte

MailboxSettings.ReadWrite

Postfacheinstellungen

User.Read.All

Postfachauflistung, Benutzerprofile

Directory.Read.All

Lizenzvalidierung

Organization.Read.All

Domänenvalidierung

Office 365 Exchange Online-Berechtigungen:

Hinweis: Diese Berechtigungen finden Sie unter Office 365 Exchange Online, nicht unter Microsoft Graph. Verwenden Sie Exchange.ManageAsApp und nicht Exchange.ManageAsAppV2.

full_access_as_app

Archiv- und Gruppenpostfächer (EWS)

Exchange.ManageAsApp

Postfachverwaltung

Option B: Über das App-Manifest

So können Sie alle Berechtigungen auf einmal hinzufügen, indem Sie einen JSON-Codeausschnitt einfügen. Das vermeidet Fehler bei der manuellen Auswahl.

  1. Gehen Sie in Ihrer App-Registrierung zu Manifest.

  2. Suchen Sie das Array requiredResourceAccess und ersetzen Sie es durch Folgendes:

    "requiredResourceAccess": [
        {
            "resourceAppId": "00000002-0000-0ff1-ce00-000000000000",
            "resourceAccess": [
                { "id": "dc50a0fb-09a3-484d-be87-e023b12c6440", "type": "Role" },
                { "id": "dc890d15-9560-4a4c-9b7f-a736ec74ec40", "type": "Role" }
            ]
        },
        {
            "resourceAppId": "00000003-0000-0000-c000-000000000000",
            "resourceAccess": [
                { "id": "ef54d2bf-783f-4e0f-bca1-3210c0444d99", "type": "Role" },
                { "id": "6918b873-d17a-4dc1-b314-35f528134491", "type": "Role" },
                { "id": "7ab1d382-f21e-4acd-a863-ba3e13f7da61", "type": "Role" },
                { "id": "e2a3a72e-5f79-4c64-b1b1-878b674786c9", "type": "Role" },
                { "id": "6931bccd-447a-43d1-b442-00a195474933", "type": "Role" },
                { "id": "498476ce-e0fe-48b0-b801-37ba7e2685c6", "type": "Role" },
                { "id": "df021288-bdef-4463-88db-98f22de89214", "type": "Role" }
            ]
        }
    ]

  3. Klicken Sie auf Save.

  4. Gehen Sie zu API permissions, klicken Sie auf Grant admin consent for [your tenant] und bestätigen Sie.

Schritt 4: Rolle Exchange Administrator zuweisen

Hinweis: Dieser Schritt ist für die Archivverwaltung, Litigation Holds und Vorgänge im Zusammenhang mit der Postfachgröße erforderlich.

Exchange Administrator ist eine Rolle auf Verzeichnisebene und kann daher nicht direkt über die Seite Roles and administrators der App-Registrierung zugewiesen werden. Die folgenden Schritte führen Sie zur Zuweisungsansicht auf Verzeichnisebene.

  1. Gehen Sie in Ihrer App-Registrierung zu Roles and administrators.

  2. Klicken Sie in der Zeile mit dem Text „Directory-level roles have inherited access to this resource and can only be assigned at the directory level here" auf here, um die Rollenzuweisung auf Verzeichnisebene zu öffnen.

  3. Suchen Sie nach Exchange Administrator und wählen Sie die Rolle aus.

  4. Klicken Sie auf + Add assignments und dann auf Select member(s).

  5. Suchen Sie nach dem Display name oder der Object ID Ihrer App-Registrierung, wählen Sie sie aus und klicken Sie auf Select.

  6. Klicken Sie auf Next und dann auf Assign.

Option 2: Schnelle Einrichtung mit PowerShell (empfohlen)

Dieses Skript automatisiert alle Schritte aus Option 1: Es erstellt die App-Registrierung, fügt die Antwort-URL hinzu, erteilt alle erforderlichen Berechtigungen und weist die Rolle Exchange Administrator zu. Es erstellt keine Anmeldeinformationen. Dies erledigen Sie weiter unten unter Anmeldeinformationen hinzufügen.

Installieren Sie zunächst das Microsoft Graph PowerShell SDK (einmalig):

Install-Module Microsoft.Graph -Scope CurrentUser

Führen Sie anschließend Folgendes aus, während Sie als Globaler Administrator des Home-Mandanten angemeldet sind. Setzen Sie $multiTenant = $true für eine Multi-Tenant-App.

$ErrorActionPreference = 'Stop'
$displayName  = 'ShareGate Mailbox Migration'
$multiTenant  = $false   # set to $true to allow the app to be consented in other tenants
$replyUrl     = 'https://go.sharegate.com/vmen'

$signInAudience = if ($multiTenant) { 'AzureADMultipleOrgs' } else { 'AzureADMyOrg' }

# Well-known resource app IDs
$graphAppId = '00000003-0000-0000-c000-000000000000'   # Microsoft Graph
$exoAppId   = '00000002-0000-0ff1-ce00-000000000000'   # Office 365 Exchange Online

# Application permissions to grant
$graphRoleIds = @(
    'e2a3a72e-5f79-4c64-b1b1-878b674786c9',  # Mail.ReadWrite
    'ef54d2bf-783f-4e0f-bca1-3210c0444d99',  # Calendars.ReadWrite
    '6918b873-d17a-4dc1-b314-35f528134491',  # Contacts.ReadWrite
    '6931bccd-447a-43d1-b442-00a195474933',  # MailboxSettings.ReadWrite
    'df021288-bdef-4463-88db-98f22de89214',  # User.Read.All
    '7ab1d382-f21e-4acd-a863-ba3e13f7da61',  # Directory.Read.All
    '498476ce-e0fe-48b0-b801-37ba7e2685c6'   # Organization.Read.All
)
$exoRoleIds = @(
    'dc50a0fb-09a3-484d-be87-e023b12c6440',  # full_access_as_app
    'dc890d15-9560-4a4c-9b7f-a736ec74ec40'   # Exchange.ManageAsApp
)
$exchangeAdminRoleId = '29232cdf-9323-42fd-ade2-1d097af3e4de'  # Exchange Administrator (built-in)

# 1. Sign in
Connect-MgGraph -Scopes 'Application.ReadWrite.All','AppRoleAssignment.ReadWrite.All','RoleManagement.ReadWrite.Directory'

# 2. Create the app registration
$requiredResourceAccess = @(
    @{ ResourceAppId = $graphAppId; ResourceAccess = @($graphRoleIds | ForEach-Object { @{ Id = $_; Type = 'Role' } }) },
    @{ ResourceAppId = $exoAppId;   ResourceAccess = @($exoRoleIds   | ForEach-Object { @{ Id = $_; Type = 'Role' } }) }
)
$app = New-MgApplication -DisplayName $displayName -SignInAudience $signInAudience `
    -Web @{ RedirectUris = @($replyUrl) } `
    -RequiredResourceAccess $requiredResourceAccess

# 3. Create the service principal
$sp = New-MgServicePrincipal -AppId $app.AppId
Start-Sleep -Seconds 10   # let the service principal replicate

# 4. Grant admin consent
$graphSp = Get-MgServicePrincipal -Filter "appId eq '$graphAppId'"
$exoSp   = Get-MgServicePrincipal -Filter "appId eq '$exoAppId'"
foreach ($roleId in $graphRoleIds) {
    New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $sp.Id -PrincipalId $sp.Id -ResourceId $graphSp.Id -AppRoleId $roleId | Out-Null
}
foreach ($roleId in $exoRoleIds) {
    New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $sp.Id -PrincipalId $sp.Id -ResourceId $exoSp.Id -AppRoleId $roleId | Out-Null
}

# 5. Assign the Exchange Administrator role
New-MgRoleManagementDirectoryRoleAssignment -PrincipalId $sp.Id -RoleDefinitionId $exchangeAdminRoleId -DirectoryScopeId '/' | Out-Null

# 6. Output the values you'll use with ShareGate
[pscustomobject]@{
    DisplayName   = $displayName
    ApplicationId = $app.AppId
    TenantId      = (Get-MgContext).TenantId
} | Format-List

Kopieren Sie ApplicationId und TenantId aus der Ausgabe. Sie benötigen diese beim Verbinden. Bei einer Multi-Tenant-App wird damit nur Ihr Home-Mandant konfiguriert. Folgen Sie für jeden weiteren Mandanten den Schritten unter Weitere Mandanten einrichten weiter unten.

Weitere Mandanten einrichten

Hinweis: Dieser Abschnitt gilt nur für Multi-Tenant-Apps. Die App-Registrierung und die zugehörigen Anmeldeinformationen befinden sich in Ihrem Home-Mandanten. Damit die App in einem anderen Mandanten verwendet werden kann, muss ein Administrator dieses Mandanten ihr zustimmen und die Rolle Exchange Administrator zuweisen. Wiederholen Sie dies für jeden weiteren Mandanten.

Ein Administrator des weiteren Mandanten öffnet die folgende URL in einem Browser, ersetzt die Platzhalter und meldet sich als Globaler Administrator dieses Mandanten an:

https://login.microsoftonline.com/<additional-tenant-id-or-domain>/adminconsent?client_id=<application-client-id>

Nach der Überprüfung und Annahme der Berechtigungen leitet der Browser zur ShareGate-Bestätigungsseite weiter. Dadurch wird die Unternehmensanwendung (Dienstprinzipal) der App in diesem Mandanten bereitgestellt.

2. Rolle Exchange Administrator im weiteren Mandanten zuweisen

Führen Sie im weiteren Mandanten angemeldet Folgendes aus:

  1. Gehen Sie zu Entra ID > Roles & admins.

  2. Suchen Sie nach Exchange Administrator und wählen Sie die Rolle aus.

  3. Klicken Sie auf + Add assignments und dann auf Select member(s).

  4. Suchen Sie die App anhand ihres Display name oder ihrer Application (client) ID, wählen Sie sie aus und klicken Sie auf Select.

  5. Klicken Sie auf Next und dann auf Assign.

Anmeldeinformationen hinzufügen

New-AzureApplication unterstützt zwei zertifikatsbasierte Authentifizierungsmethoden. Wählen Sie eine davon aus.

Option A: Zertifikat (aus Datei)

  1. Gehen Sie zu Certificates & secrets > Certificates > Upload certificate.

  2. Laden Sie Ihre öffentliche Schlüsseldatei im Format .cer oder .pem hoch.

  3. Stellen Sie sicher, dass der private Schlüssel (.pfx) zur Laufzeit für PowerShell zugänglich ist.

Option B: Zertifikatfingerabdruck (Windows-Zertifikatspeicher)

  1. Installieren Sie das Zertifikat (mit privatem Schlüssel) im Windows-Zertifikatspeicher auf dem Computer, auf dem die Migration ausgeführt wird.

  2. Gehen Sie zu Certificates & secrets > Certificates > Upload certificate und laden Sie den öffentlichen Schlüssel hoch.

  3. Notieren Sie sich den Fingerabdruck. Sie übergeben ihn direkt an New-AzureApplication.

Hinweis: Laden Sie bei einer Multi-Tenant-App die Anmeldeinformationen einmalig zur App-Registrierung in Ihrem Home-Mandanten hoch. Dieselben Anmeldeinformationen funktionieren in jedem Mandanten, in dem der App zugestimmt wurde.

Verbindung von ShareGate herstellen

Erstellen Sie mit New-AzureApplication ein Anmeldeinformationsobjekt und stellen Sie anschließend mit Connect-MicrosoftOnline eine Verbindung her. Geben Sie den Zielmandanten mit -TenantId an.

# Build a credential object from a certificate thumbprint
$azureApp = New-AzureApplication -ClientId <application-client-id> -Thumbprint <certificate-thumbprint>

# Connect to a tenant
Connect-MicrosoftOnline -TenantId <directory-tenant-id> -AzureApplication $azureApp

Bei einer Multi-Tenant-App verwenden Sie dasselbe $azureApp-Objekt weiter und ändern für jeden Mandanten die -TenantId:

Connect-MicrosoftOnline -TenantId <source-tenant-id> -AzureApplication $azureApp
Connect-MicrosoftOnline -TenantId <destination-tenant-id> -AzureApplication $azureApp

Hinweis: Wenn Ihre Sicherheitsrichtlinie das Erteilen einer der erforderlichen Berechtigungen verhindert, fügen Sie -AllowMissingPermissions zu Connect-MicrosoftOnline hinzu, um die Verbindung trotzdem herzustellen. Vorgänge, die von der fehlenden Berechtigung abhängen, schlagen mit Forbidden-Fehlern fehl. Dieser Schalter lockert die Berechtigungsprüfung nur nach erfolgreicher Authentifizierung. Eine fehlgeschlagene Anmeldung wird dadurch nicht behoben.

Bekannte Einschränkungen

  • Gruppenkalender werden bei reiner Anwendungsauthentifizierung nicht unterstützt. Dies ist eine Einschränkung der Microsoft Graph API, die alle Migrationstools betrifft.

Dieser Artikel wurde mit künstlicher Intelligenz übersetzt. Bei Unklarheiten konsultieren Sie bitte die englische Originalversion.

Hat dies deine Frage beantwortet?