Convertir les IDs Exchange pour l'API Graph Microsoft 365

Introduction : le labyrinthe des identifiants Exchange

Les administrateurs Exchange Online et les développeurs qui travaillent avec Microsoft Graph se heurtent régulièrement à un même obstacle : la multiplicité des formats d'identifiants de dossiers de boîtes aux lettres. Chaque composant de l'écosystème Exchange utilise sa propre représentation interne, et naviguer entre ces formats sans documentation claire relève souvent du défi.

Cet article examine concrètement les conversions nécessaires pour passer du storeId, retourné par les cmdlets PowerShell Exchange Online, jusqu'au RestId exploitable par les méthodes de l'API Microsoft Graph. Nous abordons également la conversion vers le format attendu par les recherches eDiscovery ciblées (targeted collections).

Les différents types d'identifiants Exchange Online

Avant d'entrer dans le vif du sujet, il est utile de dresser un panorama des identifiants impliqués dans la chaîne de conversion :

• storeId : identifiant natif retourné par Get-ExOMailboxFolderStatistics, Get-MailboxFolderStatistics ou Get-MailboxFolder. C'est le point de départ systématique pour un profil administrateur.
• eDiscoveryId : format hexadécimal attendu par la fonctionnalité de targeted collection dans les recherches de contenu (Content Search / eDiscovery).
• entryId : identifiant utilisé par les clients MAPI. Sert d'intermédiaire obligatoire pour atteindre le RestId.
• RestId : identifiant consommé par les API Outlook/Graph (/me/mailFolders/{id}).
• OWAId : variante du RestId adaptée à la navigation directe dans Outlook Web App.

Étape 1 : récupérer le storeId via PowerShell

La première étape consiste à identifier le dossier cible et à récupérer son storeId via la propriété FolderId :

1Get-ExOMailboxFolderStatistics vasil | Where-Object { $_.Name -eq "Xbox" } | Select-Object Name, FolderId

Résultat attendu :

1Name  FolderId
2----  --------
3Xbox  LgAAAAChKSJAhlnUTIHtKSso30ThAQBIPfDMxyP/RYhY8M8xmAPVAAS8XYoAAAAB

Ce storeId encodé en Base64 est la matière première de toutes les conversions suivantes.

Étape 2 : convertir le storeId en eDiscoveryId

La fonctionnalité de targeted collection dans Microsoft Purview eDiscovery permet de restreindre une recherche de contenu à un dossier précis via le mot-clé KQL folderId. Cette approche est particulièrement efficace lors d'investigations ciblées.

Voici le bloc PowerShell permettant cette conversion :

1$folderId = [Convert]::FromBase64String($folderId)
2 
3$encoding = [System.Text.Encoding]::GetEncoding("us-ascii")
4$nibbler = $encoding.GetBytes("0123456789ABCDEF")
5 
6$indexIdBytes = New-Object byte[] 48; $indexIdIdx = 0
7$folderId | Select-Object -Skip 23 -First 24 | ForEach-Object {
8    $indexIdBytes[$indexIdIdx++] = $nibbler[$_ -shr 4]
9    $indexIdBytes[$indexIdIdx++] = $nibbler[$_ -band 0x0F]
10}
11 
12return $encoding.GetString($indexIdBytes)

Pour le dossier Xbox utilisé en exemple, la transformation produit :

1# storeId (Base64)
2LgAAAAChKSJAhlnUTIHtKSso30ThAQBIPfDMxyP/RYhY8M8xmAPVAAS8XYoAAAAB
3 
4# eDiscoveryId (hexadécimal)
5483DF0CCC723FF458858F0CF319803D50004BC5D8A000000

Ce format hexadécimal peut désormais être utilisé directement dans une requête KQL ciblée sur ce dossier.

Étape 3 : convertir le storeId en entryId (intermédiaire MAPI)

L'API Graph expose la méthode translateExchangeIds pour convertir des identifiants Exchange vers d'autres formats. Cependant, elle ne prend pas en charge le storeId comme entrée directe. Il est donc nécessaire de passer d'abord par l'entryId, format MAPI intermédiaire.

La fonction PowerShell suivante effectue la conversion storeId → entryId :

1function FolderIdToEntryId {
2 
3    param([Parameter(Mandatory=$true)]$folderId)
4 
5    # Décodage Base64 vers tableau d'octets
6    $folderIdBytes = [Convert]::FromBase64String($folderId)
7 
8    # Conversion en chaîne hexadécimale, suppression des tirets, premier octet ignoré
9    $folderIdHexString = [System.BitConverter]::ToString($folderIdBytes).Replace('-','')
10    $folderIdHexStringLength = $folderIdHexString.Length
11 
12    # Suppression du premier et du dernier octet
13    $entryIdHexString = $folderIdHexString.SubString(2, ($folderIdHexStringLength - 4))
14 
15    # Reconstruction du tableau d'octets (2 caractères = 1 octet)
16    $entryIdBytes = [byte[]]::new($entryIdHexString.Length / 2)
17    For ($i = 0; $i -lt $entryIdHexString.Length; $i += 2) {
18        $entryIdTwoChars = $entryIdHexString.Substring($i, 2)
19        $entryIdBytes[$i / 2] = [convert]::ToByte($entryIdTwoChars, 16)
20    }
21 
22    # Encodage en Base64 URL-safe
23    $entryIdBase64 = [Convert]::ToBase64String($entryIdBytes)
24    $equalCharCount = $entryIdBase64.Length - $entryIdBase64.Replace('=','').Length
25    $entryId = $entryIdBase64.TrimEnd('=').Replace('/','-').Replace('+','_') + $equalCharCount
26 
27    return $entryId
28}

Étape 4 : obtenir le RestId via translateExchangeIds

Une fois le entryId obtenu, il est possible d'appeler la méthode translateExchangeIds de Microsoft Graph pour obtenir le RestId. Ce dernier est l'identifiant attendu par toutes les opérations sur les dossiers via les API Graph (endpoints /me/mailFolders, /users/{id}/mailFolders, etc.).

Les dossiers système prédéfinis (Inbox, SentItems, RecoverableItemsDeletions, etc.) disposent de valeurs dites well-known qui peuvent être utilisées directement sans conversion. La conversion est nécessaire uniquement pour les dossiers créés par les utilisateurs.

Script complet : générer tous les identifiants d'une boîte aux lettres

En combinant les conversions décrites ci-dessus, il est possible de produire un inventaire complet des dossiers d'une boîte aux lettres avec l'ensemble de leurs identifiants.

Prérequis

• Module Exchange Online Management (pour Get-ExOMailboxFolderStatistics)
• Module Microsoft Graph SDK for PowerShell
• Permission déléguée : User.ReadBasic.All (côté Graph) et droits Exchange appropriés

Paramètres du script

Le script expose les paramètres suivants :

• -Mailbox (obligatoire) : adresse SMTP principale ou GUID ExternalDirectoryObjectId de la boîte cible.
• -IncludeNonIPM (optionnel) : inclut les dossiers hors de l'arborescence IPM (non visibles par l'utilisateur).

Exemples d'utilisation

1# Exécution sur une boîte identifiée par son adresse SMTP
2.\Mailbox_Folder_IDs.ps1 -Mailbox user@domain.com
3 
4# Exécution avec l'ExternalDirectoryObjectId (GUID)
5.\Mailbox_Folder_IDs.ps1 -Mailbox 4ebd5057-4d61-4ca0-beb7-df3f1ebd1aa7
6 
7# Inclure les dossiers hors de l'arborescence IPM
8.\Mailbox_Folder_IDs.ps1 -Mailbox user@domain.com -IncludeNonIPM

Traitement interne du script

Le script suit la séquence logique suivante :

Colonnes du rapport CSV

• Name : nom du dossier
• FolderType : type de dossier Exchange
• Identity : chemin complet du dossier dans la boîte
• FolderId : storeId (format Base64)
• eDiscoveryId : identifiant pour les targeted collections
• EntryId : identifiant MAPI
• RestId : identifiant pour l'API Microsoft Graph
• OWAId : identifiant pour la navigation OWA

Comportement des boutons dans le rapport HTML

• Open in Graph Explorer : fonctionne en mode délégué uniquement si la permission Mail.ReadBasic.Shared est accordée.
• Open in OWA : fonctionne exclusivement pour les dossiers de messagerie accessibles aux utilisateurs (pas les dossiers Calendrier, Contacts ou système). Requiert l'adresse UPN/SMTP comme identifiant de boîte.

Considérations opérationnelles

L'utilisation de permissions applicatives (application permissions) n'est pas encore implémentée dans la version actuelle du script. Pour les environnements nécessitant une automatisation sans interaction utilisateur, une adaptation du bloc de connexion sera nécessaire.

D'un point de vue gestion des identités M365, ces conversions illustrent bien la complexité inhérente à la coexistence des couches MAPI, EWS (en cours de dépréciation) et Graph dans Exchange Online. La migration progressive vers les API Graph impose de maîtriser ces transformations pour maintenir la parité fonctionnelle des outils d'administration.