Remarque : L'intégration PowerShell nécessite un abonnement Pro ou Enterprise à ShareGate Migrate. Elle n'est pas disponible avec le plan Essentials.

Cet article concerne uniquement l'intégration PowerShell de ShareGate Migrate. L'authentification par application seule vous permet d'exécuter des migrations de boîtes aux lettres depuis PowerShell sans compte utilisateur connecté. Au lieu d'informations d'identification utilisateur, ShareGate Migrate s'authentifie à l'aide d'un enregistrement d'application Azure. Cette méthode convient particulièrement aux migrations automatisées ou planifiées dans les environnements d'entreprise.

Pendant la configuration, vous récupérerez deux valeurs à transmettre aux commandes PowerShell de ShareGate : l'Application (client) ID et le Directory (tenant) ID.

Avant de commencer

Abonnement ShareGate Migrate Pro ou Enterprise
Accès Global Administrator sur les locataires Microsoft 365 source et destination, nécessaire pour créer l'enregistrement d'application et accorder le consentement administrateur

Locataire unique ou multi-locataire

Comprendre la différence entre ces deux termes vous aidera à choisir la configuration adaptée :

Un app registration (enregistrement d'application) est le modèle de l'application. Il se trouve dans le locataire d'origine (le locataire où vous le créez) et définit l'identité de l'application, ses autorisations d'API et ses certificats.
Une enterprise application (aussi appelée principal de service) est l'instance locale de cette application dans un locataire spécifique. C'est sur cette instance que vous accordez le consentement administrateur et attribuez des rôles.

Faites votre choix selon le nombre de locataires que vous migrez :

Locataire unique : l'application est utilisée uniquement dans le locataire où vous l'enregistrez. Sous Supported account types, choisissez My organization only. Pour migrer entre deux locataires, répétez la configuration complète dans chaque locataire.
Multi-locataire : un seul enregistrement d'application dans votre locataire d'origine, réutilisé dans plusieurs locataires. C'est le choix habituel pour les consultants, les fournisseurs de services gérés et les migrations source-destination. Sous Supported account types, choisissez Multiple Entra ID tenants et laissez Allow all tenants sélectionné. Vous consentez ensuite à l'application dans chaque locataire supplémentaire et lui attribuez le rôle Exchange Administrator. Consultez Configurer des locataires supplémentaires ci-dessous.

Avec une application multi-locataire, vous créez l'objet d'informations d'identification une seule fois et transmettez un -TenantId différent à Connect-MicrosoftOnline pour chaque locataire.

Configurer l'enregistrement d'application

Effectuez cette opération dans votre locataire d'origine. Pour une application à locataire unique, répétez l'opération dans chaque locataire vers ou depuis lequel vous migrez. Pour une application multi-locataire, effectuez-la une seule fois, puis suivez Configurer des locataires supplémentaires ci-dessous.

Option 1 : configuration manuelle dans le portail Azure

Étape 1 : créer l'enregistrement d'application

Connectez-vous au Microsoft Entra admin center en tant que Global Administrator.
Accédez à Entra ID > App registrations > New registration.
Donnez un nom à l'application (par exemple, ShareGate Mailbox Migration).
Sous Supported account types, choisissez l'option correspondant à votre scénario. Consultez Locataire unique ou multi-locataire ci-dessus.
Laissez le champ Redirect URI vide pour le moment.
Cliquez sur Register.
Sur la page Overview, copiez l'Application (client) ID et le Directory (tenant) ID. Vous les utiliserez avec New-AzureApplication et Connect-MicrosoftOnline. Notez également le Display name ou l'Object ID pour l'attribution de rôle à l'étape 4.

Étape 2 : ajouter une URL de réponse

Remarque : Cette étape est requise pour les applications multi-locataires. Le consentement administrateur ne pourra pas être finalisé sans au moins une URL de réponse. https://go.sharegate.com/vmen est une page ShareGate qui confirme que le consentement a réussi.

Dans votre enregistrement d'application, accédez à Authentication et cliquez sur + Add Redirect URI.
Dans le volet Web platform, sous Redirect URI, saisissez https://go.sharegate.com/vmen.
Cliquez sur Configure.

Étape 3 : ajouter des autorisations API

Choisissez l'une des deux méthodes ci-dessous.

Option A : manuellement via le portail Azure

Accédez à API permissions > Add a permission.
Ajoutez chacune des Application permissions listées ci-dessous (et non Delegated). Vous ajoutez séparément les autorisations Microsoft Graph et les autorisations Office 365 Exchange Online.
Cliquez sur Grant admin consent for [your tenant] et confirmez.

Autorisations Microsoft Graph :

`Mail.ReadWrite`	Éléments de messagerie
`Calendars.ReadWrite`	Événements de calendrier
`Contacts.ReadWrite`	Contacts
`MailboxSettings.ReadWrite`	Paramètres de la boîte aux lettres
`User.Read.All`	Liste des boîtes aux lettres, profils utilisateur
`Directory.Read.All`	Validation des licences
`Organization.Read.All`	Validation des domaines

Autorisations Office 365 Exchange Online :

Remarque : Ces autorisations se trouvent sous Office 365 Exchange Online, et non sous Microsoft Graph. Utilisez Exchange.ManageAsApp, et non Exchange.ManageAsAppV2.

`full_access_as_app`	Boîtes aux lettres d'archive et de groupe (EWS)
`Exchange.ManageAsApp`	Gestion des boîtes aux lettres

Option B : via le manifeste de l'application

Cette méthode vous permet d'ajouter toutes les autorisations en une seule fois en collant un extrait JSON, ce qui évite les erreurs de sélection manuelle.

Dans votre enregistrement d'application, accédez à Manifest.

Repérez le tableau requiredResourceAccess et remplacez-le par ce qui suit :

"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" }
        ]
    }
]

Cliquez sur Save.
Accédez à API permissions, cliquez sur Grant admin consent for [your tenant], puis confirmez.

Étape 4 : attribuer le rôle Exchange Administrator

Remarque : Cette étape est requise pour la gestion des archives, les conservations légales et les opérations liées à la taille des boîtes aux lettres.

Exchange Administrator est un rôle au niveau de l'annuaire ; vous ne pouvez donc pas l'attribuer directement depuis la page Roles and administrators de l'enregistrement d'application. Les étapes ci-dessous vous amènent à la vue d'attribution au niveau de l'annuaire.

Dans votre enregistrement d'application, accédez à Roles and administrators.
Sur la ligne indiquant « Directory-level roles have inherited access to this resource and can only be assigned at the directory level here », cliquez sur here pour ouvrir l'attribution de rôle au niveau de l'annuaire.
Recherchez et sélectionnez Exchange Administrator.
Cliquez sur + Add assignments, puis sur Select member(s).
Recherchez le Display name ou l'Object ID de votre enregistrement d'application, sélectionnez-le, puis cliquez sur Select.
Cliquez sur Next, puis sur Assign.

Option 2 : configuration rapide avec PowerShell (recommandé)

Ce script automatise toutes les étapes de l'Option 1 : il crée l'enregistrement d'application, ajoute l'URL de réponse, accorde toutes les autorisations requises et attribue le rôle Exchange Administrator. Il ne crée pas d'informations d'identification ; vous le faites dans Ajouter des informations d'identification ci-dessous.

Installez d'abord le Microsoft Graph PowerShell SDK (une seule fois) :

Install-Module Microsoft.Graph -Scope CurrentUser

Exécutez ensuite ce qui suit, connecté en tant que Global Administrator du locataire d'origine. Définissez $multiTenant = $true pour une application multi-locataire.

$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

Copiez l'ApplicationId et le TenantId à partir de la sortie. Vous les utiliserez lors de la connexion. Pour une application multi-locataire, cette opération configure uniquement votre locataire d'origine. Suivez Configurer des locataires supplémentaires ci-dessous pour chaque locataire supplémentaire.

Configurer des locataires supplémentaires

Remarque : Cette section s'applique uniquement aux applications multi-locataires. L'enregistrement d'application et ses informations d'identification se trouvent dans votre locataire d'origine. Pour utiliser l'application dans un autre locataire, un administrateur de ce locataire doit y consentir et attribuer le rôle Exchange Administrator. Répétez l'opération pour chaque locataire supplémentaire.

Un administrateur du locataire supplémentaire ouvre l'URL suivante dans un navigateur, remplace les valeurs d'espace réservé et se connecte en tant que Global Administrator de ce locataire :

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

Après avoir consulté et accepté les autorisations, le navigateur redirige vers la page de confirmation ShareGate. Cette opération provisionne l'enterprise application (principal de service) de l'application dans ce locataire.

2. Attribuer le rôle Exchange Administrator dans le locataire supplémentaire

Une fois connecté au locataire supplémentaire :

Accédez à Entra ID > Roles & admins.
Recherchez et sélectionnez Exchange Administrator.
Cliquez sur + Add assignments, puis sur Select member(s).
Recherchez l'application par son Display name ou son Application (client) ID, sélectionnez-la, puis cliquez sur Select.
Cliquez sur Next, puis sur Assign.

Ajouter des informations d'identification

New-AzureApplication prend en charge deux méthodes d'authentification par certificat. Choisissez-en une.

Option A : certificat (à partir d'un fichier)

Accédez à Certificates & secrets > Certificates > Upload certificate.
Téléversez votre fichier de clé publique .cer ou .pem.
Gardez la clé privée (.pfx) accessible depuis PowerShell au moment de l'exécution.

Option B : empreinte numérique du certificat (magasin de certificats Windows)

Installez le certificat (avec la clé privée) dans le magasin de certificats Windows de la machine qui exécute la migration.
Accédez à Certificates & secrets > Certificates > Upload certificate, puis téléversez la clé publique.
Notez l'empreinte numérique. Vous la transmettrez directement à New-AzureApplication.

Remarque : Pour une application multi-locataire, téléversez les informations d'identification une seule fois vers l'enregistrement d'application de votre locataire d'origine. Les mêmes informations d'identification fonctionnent pour chaque locataire où l'application a reçu son consentement.

Se connecter depuis ShareGate

Créez un objet d'informations d'identification avec New-AzureApplication, puis connectez-vous avec Connect-MicrosoftOnline. Transmettez le locataire cible avec -TenantId.

# 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

Avec une application multi-locataire, réutilisez le même objet $azureApp et changez -TenantId pour chaque locataire :

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

Remarque : Si votre politique de sécurité empêche l'octroi d'une des autorisations requises, ajoutez -AllowMissingPermissions à Connect-MicrosoftOnline pour vous connecter malgré tout. Les opérations qui dépendent de l'autorisation manquante échoueront avec des erreurs Forbidden. Ce commutateur assouplit uniquement la vérification des autorisations après la réussite de l'authentification. Il ne résout pas un échec de connexion.

Limitations connues

Les Group calendars (calendriers de groupe) ne sont pas pris en charge avec l'authentification par application seule. Il s'agit d'une limitation de l'API Microsoft Graph qui touche tous les outils de migration.

Cet article a été traduit à l'aide de l'intelligence artificielle. En cas de doute, veuillez consulter la version originale en anglais.

Configurer un enregistrement d'application Azure pour les migrations de boîtes aux lettres par PowerShell