Microsoft 365 : préparer OAuth IMAP app-only pour une migration automatisée

Pour migrer un grand nombre de boîtes Microsoft 365 vers une autre messagerie, l'authentification IMAP par mot de passe est généralement bloquée. La bonne méthode consiste à créer une application Microsoft Entra ID avec une autorisation applicative Exchange Online, puis à lui donner accès aux boîtes à migrer. Ce guide explique les étapes à réaliser côté client.

Principe de fonctionnement

Il existe deux façons d'utiliser OAuth2 avec IMAP Microsoft 365 :

• OAuth délégué : un utilisateur se connecte et autorise l'application pour sa propre boîte. Ce mode n'est pas adapté à une migration massive.
• OAuth applicatif, aussi appelé app-only : l'application s'authentifie avec son propre secret ou certificat. C'est le mode à utiliser pour automatiser une migration de nombreuses boîtes.

Pour une migration de masse, nous utilisons donc le mode app-only. L'administrateur Microsoft 365 crée une application, lui donne la permission IMAP.AccessAsApp, puis autorise explicitement cette application à accéder aux boîtes concernées dans Exchange Online.

Informations à préparer

Avant de commencer, assurez-vous d'avoir :

• un compte administrateur Microsoft 365 avec accès à Microsoft Entra ID ;
• un accès administrateur Exchange Online PowerShell ;
• la liste des boîtes à migrer ;
• la possibilité de créer une inscription d'application et d'accorder un consentement administrateur.

Étape 1 : créer l'application dans Microsoft Entra ID

1. Ouvrez le centre d'administration Microsoft Entra à l'adresse entra.microsoft.com.
2. Allez dans Microsoft Entra ID → Inscriptions d'applications.
3. Cliquez sur Nouvelle inscription.
4. Nom : InfoSwitch Migration IMAP ou un nom équivalent.
5. Types de comptes pris en charge : Comptes dans cet annuaire organisationnel uniquement.
6. URI de redirection : non nécessaire pour le mode app-only.
7. Validez la création.

Une fois l'application créée, notez les deux valeurs suivantes :

• ID d'application (client)
• ID d'annuaire (tenant)

Étape 2 : ajouter la permission IMAP applicative

1. Dans l'application créée, ouvrez Autorisations d'API.
2. Cliquez sur Ajouter une autorisation.
3. Choisissez APIs utilisées par mon organisation.
4. Recherchez Office 365 Exchange Online.
5. Sur l'écran suivant, Microsoft Entra vous demande de choisir le type d'autorisation : sélectionnez Autorisations d'application, et non Autorisations déléguées.
6. Cochez IMAP.AccessAsApp.
7. Ajoutez l'autorisation.
8. Cliquez sur Accorder le consentement administrateur.

Étape 3 : créer un secret client

1. Dans l'application, ouvrez Certificats et secrets.
2. Cliquez sur Nouveau secret client.
3. Choisissez une durée d'expiration de 90 jours, suffisante pour la période de migration tout en limitant la durée de validité du secret.
4. Copiez immédiatement la valeur du secret.

Conservez la valeur du secret client dans un emplacement sécurisé. Elle ne sera plus visible ensuite dans Microsoft Entra ID. Si vous la perdez, il faudra créer un nouveau secret.

Étape 4 : récupérer l'Object ID de l'application d'entreprise

Cette étape est importante : Exchange Online n'utilise pas l'Object ID visible dans l'inscription d'application. Il faut récupérer l'Object ID de l'application d'entreprise, c'est-à-dire le service principal créé dans votre tenant.

1. Dans Microsoft Entra ID, ouvrez Applications d'entreprise.
2. Recherchez l'application InfoSwitch Migration IMAP.
3. Ouvrez sa fiche.
4. Copiez l'ID d'objet.

Dans les commandes ci-dessous, cette valeur est appelée ENTERPRISE_OBJECT_ID.

Étape 5 : enregistrer le service principal dans Exchange Online

Ouvrez PowerShell en tant qu'administrateur, puis connectez-vous à Exchange Online :

# Installer et charger le module Exchange Online
Install-Module ExchangeOnlineManagement -Scope CurrentUser
Import-Module ExchangeOnlineManagement
Connect-ExchangeOnline

Définissez les variables suivantes :

# Remplacer les valeurs par celles récupérées dans Entra
$ApplicationId = "ID_APPLICATION_CLIENT"
$EnterpriseObjectId = "ENTERPRISE_OBJECT_ID"
$DisplayName = "InfoSwitch Migration IMAP"

Enregistrez ensuite le service principal dans Exchange Online :

# Enregistrer l'application Entra dans Exchange Online
New-ServicePrincipal -AppId $ApplicationId -ServiceId $EnterpriseObjectId

Si nécessaire, donnez-lui ensuite un nom lisible :

# Optionnel : définir un nom lisible
Set-ServicePrincipal -Identity $EnterpriseObjectId -DisplayName $DisplayName

Vérifiez qu'il est bien connu d'Exchange Online :

# Vérifier que le service principal est connu d'Exchange Online
Get-ServicePrincipal | Where-Object {$_.AppId -eq $ApplicationId}

Étape 6 : autoriser les boîtes à migrer

Microsoft ne donne pas automatiquement accès à toutes les boîtes du tenant. Il faut accorder l'accès aux boîtes concernées. Pour éviter de traiter les comptes un par un, préparez un fichier CSV avec toutes les adresses à migrer.

Pour générer un CSV depuis Exchange Online avec les boîtes utilisateur et les boîtes partagées :

# Générer mailboxes.csv avec les boîtes utilisateur et les boîtes partagées
Get-Mailbox -ResultSize Unlimited -RecipientTypeDetails UserMailbox,SharedMailbox |
    Select-Object @{Name="Email";Expression={$_.PrimarySmtpAddress.ToString()}} |
    Export-Csv .\mailboxes.csv -NoTypeInformation -Encoding UTF8

Les boîtes partagées, y compris les boîtes non licenciées, peuvent être migrées avec ce mode app-only si elles sont présentes dans le CSV, si l'application reçoit FullAccess et si IMAP est activé.

Email
prenom.nom@domaine.ch
contact@domaine.ch
support@domaine.ch

Pour autoriser toutes les boîtes du fichier mailboxes.csv en une seule commande :

# Autoriser toutes les boîtes listées dans mailboxes.csv
Import-Csv .\mailboxes.csv | ForEach-Object {
    Add-MailboxPermission -Identity $_.Email -User $EnterpriseObjectId -AccessRights FullAccess
}

Vous pouvez vérifier les permissions sur toutes les boîtes listées dans le CSV :

# Vérifier les permissions sur toutes les boîtes listées dans mailboxes.csv
Import-Csv .\mailboxes.csv | ForEach-Object {
    Get-MailboxPermission -Identity $_.Email | Where-Object {
        $_.User -like "*$EnterpriseObjectId*"
    } | Select-Object @{Name="Mailbox";Expression={$_.Identity}},User,AccessRights
}

Étape 7 : vérifier que l'IMAP est activé

L'accès OAuth ne suffit pas si IMAP est désactivé sur les boîtes. Vérifiez l'état IMAP des boîtes listées dans le CSV :

# Vérifier si IMAP est activé sur toutes les boîtes listées dans mailboxes.csv
Import-Csv .\mailboxes.csv | ForEach-Object {
    Get-CASMailbox -Identity $_.Email | Select-Object PrimarySmtpAddress,ImapEnabled
}

Pour activer IMAP sur toutes les boîtes du fichier mailboxes.csv :

# Activer IMAP sur toutes les boîtes listées dans mailboxes.csv
Import-Csv .\mailboxes.csv | ForEach-Object {
    Set-CASMailbox -Identity $_.Email -ImapEnabled $true
}

Erreurs fréquentes

Invalid scope ou token sans permission IMAP

Vérifiez que le scope utilisé pour le token app-only est bien :

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

Vérifiez aussi que l'application a bien la permission applicative IMAP.AccessAsApp sur Office 365 Exchange Online, avec consentement administrateur accordé.

Authentification IMAP refusée malgré un token valide

Les causes les plus courantes sont :

• le service principal n'a pas été enregistré dans Exchange Online avec New-ServicePrincipal ;
• l'Object ID utilisé n'est pas celui de l'application d'entreprise ;
• la boîte n'a pas reçu la permission FullAccess pour ce service principal ;
• IMAP est désactivé sur la boîte ;
• les permissions viennent d'être ajoutées et ne sont pas encore propagées ;
• la connexion IMAP est tentée avec une adresse de boîte différente de celle autorisée.

Blocage par accès conditionnel

Certaines organisations appliquent des politiques d'accès conditionnel aux identités de charge de travail, applications d'entreprise ou service principals. Si le token app-only est obtenu mais que les refus IMAP sont systématiques sur tout le tenant, vérifiez qu'aucune politique Conditional Access ne bloque cette application ou les connexions app-only vers Exchange Online.

Faut-il un refresh token ?

Non pour le mode app-only. Le serveur peut redemander un access token à tout moment avec client_id, tenant_id et client_secret. Le token obtenu expire généralement après une durée limitée, mais il peut être renouvelé automatiquement sans intervention utilisateur.

Option : ajouter l'accès aux agendas Microsoft 365

La configuration IMAP ci-dessus permet de lire les emails, mais pas les agendas. Microsoft ne publie pas les calendriers via IMAP : pour vérifier ou récupérer les agendas, il faut utiliser Microsoft Graph.

Il n'est pas nécessaire de créer une deuxième application Entra ID. Vous pouvez réutiliser l'application créée pour l'IMAP et lui ajouter une permission Graph calendrier.

1. Dans Microsoft Entra ID, ouvrez l'application utilisée pour la migration IMAP.
2. Allez dans Autorisations d'API.
3. Cliquez sur Ajouter une autorisation.
4. Choisissez Microsoft Graph.
5. Pour un accès automatisé serveur à serveur, choisissez Autorisations d'application.
6. Ajoutez Calendars.Read.
7. Cliquez sur Accorder le consentement administrateur.

L'application aura alors deux familles de permissions distinctes :

Office 365 Exchange Online
- IMAP.AccessAsApp

Microsoft Graph
- Calendars.Read

Une fois cette autorisation ajoutée et le consentement administrateur accordé, indiquez simplement à InfoSwitch que l'application peut aussi accéder aux agendas Microsoft 365. InfoSwitch se chargera ensuite de la vérification technique et de la récupération des calendriers si cette partie est prévue dans le périmètre de migration.

Informations à transmettre à InfoSwitch

Une fois la configuration terminée, transmettez uniquement par un canal sécurisé :

• l'ID d'application client ;
• l'ID d'annuaire tenant ;
• la valeur du secret client ;
• la confirmation que le service principal a été enregistré dans Exchange Online ;
• la confirmation que les boîtes à migrer ont reçu l'autorisation FullAccess pour ce service principal ;
• la confirmation que l'IMAP est activé sur les boîtes concernées ;
• si les agendas sont inclus, la confirmation que la permission Graph Calendars.Read a été ajoutée avec consentement administrateur ;
• la liste CSV des boîtes à migrer, si elle n'a pas encore été fournie.