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. C'est utile pour tester une seule boîte, mais pas pour 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 portail Azure ou le centre d'administration Microsoft Entra.
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. Sélectionnez Autorisations d'application.
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 adaptée à la période de migration.
4. Copiez immédiatement la valeur du secret.

Transmettez à InfoSwitch :

• l'ID d'application client ;
• l'ID d'annuaire tenant ;
• la valeur du secret client ;
• une boîte de test autorisée, par exemple prenom.nom@domaine.ch.

Le secret client ne sera plus visible ensuite dans Microsoft Entra ID. Si vous le perdez, il faudra en créer un nouveau.

É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 :

Install-Module ExchangeOnlineManagement -Scope CurrentUser
Import-Module ExchangeOnlineManagement
Connect-ExchangeOnline

Définissez les variables suivantes :

$ApplicationId = "ID_APPLICATION_CLIENT"
$EnterpriseObjectId = "ENTERPRISE_OBJECT_ID"
$DisplayName = "InfoSwitch Migration IMAP"

Enregistrez ensuite le service principal dans Exchange Online :

New-ServicePrincipal -AppId $ApplicationId -ServiceId $EnterpriseObjectId

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

Set-ServicePrincipal -Identity $EnterpriseObjectId -DisplayName $DisplayName

Vérifiez qu'il est bien 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 une seule boîte de test :

Add-MailboxPermission -Identity "utilisateur@domaine.ch" -User $EnterpriseObjectId -AccessRights FullAccess

Pour une liste de boîtes dans un fichier CSV mailboxes.csv contenant une colonne Email :

Import-Csv .\mailboxes.csv | ForEach-Object {
    Add-MailboxPermission -Identity $_.Email -User $EnterpriseObjectId -AccessRights FullAccess
}

Vous pouvez vérifier les permissions sur une boîte :

Get-MailboxPermission -Identity "utilisateur@domaine.ch" | Where-Object {
    $_.User -like "*$EnterpriseObjectId*"
}

É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 une boîte :

Get-CASMailbox -Identity "utilisateur@domaine.ch" | Select-Object PrimarySmtpAddress,ImapEnabled

Pour activer IMAP sur une boîte :

Set-CASMailbox -Identity "utilisateur@domaine.ch" -ImapEnabled $true

Pour l'activer sur une liste CSV :

Import-Csv .\mailboxes.csv | ForEach-Object {
    Set-CASMailbox -Identity $_.Email -ImapEnabled $true
}

Étape 8 : tester le token dans InfoSwitch

Dans InfoSwitch, ouvrez l'outil d'administration de test IMAP :

1. Dans le bloc OAuth Microsoft 365, utilisez le mode app-only.
2. Renseignez l'ID d'application client.
3. Renseignez l'ID d'annuaire tenant.
4. Renseignez le secret client.
5. Renseignez une boîte de test déjà autorisée dans Exchange Online.
6. Laissez le scope sur https://outlook.office365.com/.default.
7. Cliquez sur Obtenir un token app-only.
8. Lancez ensuite le test IMAP OAuth2.

Les paramètres IMAP attendus sont :

• Serveur : outlook.office365.com
• Port : 993
• Chiffrement : SSL/TLS
• Authentification : OAuth2 / XOAUTH2
• Utilisateur : l'adresse de la boîte à migrer
• Token : access token généré avec le flux app-only

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 ;
• le test est lancé avec une adresse de boîte différente de celle autorisée.

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.

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 ;
• une boîte de test autorisée ;
• la liste CSV des boîtes à migrer, si elle n'a pas encore été fournie.