Microsoft 365 / Microsoft Graph PowerShell : exporter les utilisateurs vers CSV et gérer les licences
Microsoft Graph PowerShell vous permet d'interroger les utilisateurs de Microsoft 365 et d'automatiser l'administration des comptes et des licences. Commencez par installer les modules requis → vous connecter avec des autorisations de lecture → confirmer l'organisation cible → exporter les utilisateurs vers un fichier CSV (valeurs séparées par des virgules). L'exercice en lecture seule et les exemples de modification de compte ou de licence ci-dessous nécessitent des autorisations différentes et ont des effets différents, donc exécutez-les séparément.
Qu'est-ce que Microsoft Graph PowerShell ?
Microsoft Graph est une API (Interface de Programmation d'Applications, une interface de communication entre programmes) qui gère les données de Microsoft Entra ID, Teams, SharePoint, et plus encore. Le SDK Graph PowerShell (Kit de Développement Logiciel) vous permet d’utiliser cette API via des commandes PowerShell. Le nom actuel du service d'annuaire, précédemment appelé Azure Active Directory ou Azure AD dans les documents anciens, est Microsoft Entra ID.
Installer Graph ne signifie pas que vous pouvez utiliser toutes les commandes de gestion de Microsoft 365. Certaines tâches, telles que les commandes de gestion spécifiques à Exchange Online, nécessitent des modules et des connexions séparés. Cet article couvre l'Authentification Déléguée Interactive en utilisant le module Microsoft Graph v1.0. L'authentification uniquement par application pour les tâches planifiées sans surveillance nécessite des considérations de conception séparées telles que les autorisations d'application et les certificats, et est différente de l'exécution de tâches planifiées en utilisant les exemples de connexion utilisateur identiques.
Exigences et Installation du Module
Microsoft recommande PowerShell 7 ou une version ultérieure. Effectuez les exercices suivants dans un environnement PowerShell 7 pris en charge. Windows PowerShell 5.1 nécessite des prérequis distincts comme .NET Framework, PowerShellGet, et d'autres, et les modules installés dans une version ne sont pas automatiquement installés dans une autre version. Tout d'abord, vérifiez les exigences d'installation du SDK.
- Ouvrez PowerShell sur un PC d'administration approuvé par l'organisation. Vérifiez sa version avec
$PSVersionTable.PSVersion. - Dans le centre d'administration Microsoft Entra, vérifiez l'ID du locataire cible sous Entra ID → Overview. Ceci est particulièrement important si votre compte a accès à plusieurs organisations.
- Confirmez le consentement de l'administrateur pour les autorisations Graph et votre propre rôle administratif. Utilisez le compte d'entreprise ou scolaire de votre organisation plutôt qu'un compte personnel Microsoft classique.
- Créez un dossier restreint pour stocker les fichiers de résultat. Comme la liste des utilisateurs contient des noms et des adresses de compte, n'utilisez pas de stockage public ni de dossiers web publics.
Pour n'installer que les modules nécessaires pour la portée de l'utilisateur actuel, exécutez comme suit. Si un message de confirmation d'installation apparaît, vérifiez le dépôt et les packages. Il est également possible d'installer le module complet Microsoft.Graph, mais pour cet exercice, les sous-modules ci-dessous sont suffisants.
Install-Module -Name Microsoft.Graph.Authentication,Microsoft.Graph.Users,Microsoft.Graph.Identity.DirectoryManagement,Microsoft.Graph.Users.Actions -Scope CurrentUser -Repository PSGallery
Après l'installation, vérifiez les versions disponibles et les noms des commandes en utilisant la commande suivante. À cette étape, elle ne se connecte pas aux données de l'organisation.
Get-Module -ListAvailable Microsoft.Graph.Authentication,Microsoft.Graph.Users,Microsoft.Graph.Identity.DirectoryManagement,Microsoft.Graph.Users.Actions | Select-Object Name,Version
Get-Command Connect-MgGraph,Get-MgUser,Get-MgSubscribedSku,Set-MgUserLicense
Si des modules ou des scripts sont bloqués en raison de la politique d'exécution, vérifiez d'abord la section de la politique d'exécution. Ne considérez pas une erreur de politique comme un problème tel qu'une erreur de permission 403.
Distinction entre les permissions de connexion et les rôles d'administrateur
L'authentification déléguée est une méthode qui fonctionne au nom de l'utilisateur connecté. -Scopes est la portée des autorisations Graph demandée par l'application, et elle doit également respecter le rôle/la portée cible de l'administrateur connecté ainsi que son consentement. Le simple fait d'écrire un nom dans -Scopes n'approuve pas automatiquement cette autorisation et ne crée pas un rôle d'administrateur.
| Tâches | Autorisations Graph demandées dans l'exemple | Vérifications supplémentaires |
|---|---|---|
| Afficher la liste des utilisateurs et les attributs spécifiés | User.Read.All |
Consentement de l'administrateur et limitation des attributs à interroger |
| Consulter les abonnements SKUs et les licences des utilisateurs | LicenseAssignment.Read.All |
Rôles pris en charge par l'API, tels que les Lecteurs d'annuaire |
| Créer des utilisateurs cloud | User.Create |
Consentement de l'administrateur et autorisations et cibles de gestion des utilisateurs |
| Attribuer et révoquer des licences | LicenseAssignment.ReadWrite.All |
Rôles pris en charge, tels que l'Administrateur de licences |
Pour la pratique de lecture, il n'est pas nécessaire de demander des autorisations de modification de groupe ou des autorisations complètes d'écriture dans l'annuaire ensemble. Les autorisations déléguées versus d'application et les exigences de consentement de l'administrateur peuvent être vérifiées dans Référence des autorisations Microsoft Graph.
Pour tester les commandes de requête individuelles, connectez-vous comme indiqué ci-dessous. L'ID de locataire que vous entrez doit être la valeur réelle confirmée dans votre organisation, et après vous être connecté, vérifiez Account·TenantId·Scopes. La méthode de connexion peut utiliser un navigateur ou la fenêtre d'authentification Windows selon la version installée et l'environnement.
$tenantId = Read-Host 'ID du locataire cible'
Connect-MgGraph -TenantId $tenantId -Scopes 'User.Read.All' -ContextScope Process
Get-MgContext | Select-Object Account,TenantId,AuthType,Scopes
-ContextScope Process limite le contexte d’authentification au processus PowerShell en cours. Si Connect-MgGraph est appelé sans étendues explicites, vérifiez le contexte obtenu au lieu de supposer que son autorisation est toujours User.Read. Pour changer de compte ou d’étendues, exécutez Disconnect-MgGraph, puis reconnectez-vous avec les étendues nécessaires. Consultez le guide d’authentification de Graph PowerShell.
Exemple complet de recherche d'utilisateur et de sauvegarde au format CSV
Get-MgUser -All récupère continuellement des listes d'utilisateurs renvoyées en pages. Cependant, cela ne signifie pas qu'il reçoit automatiquement toutes les propriétés. Select-Object * n'élargit que les propriétés des objets déjà reçus, et les valeurs non incluses dans le retour par défaut doivent être demandées au serveur avec -Property. Cette différence est expliquée dans Description de Get-MgUser.
Enregistrez le code complet suivant en UTF-8 avec m365-users-report.ps1. Le script lit les informations des utilisateurs, crée un CSV avec des horodatages dans le même dossier, et déconnecte la session. Il ne change pas de comptes ni de licences. Si vous avez déjà effectué une pratique de connexion précédente, terminez-la d'abord avec Disconnect-MgGraph puis exécutez ceci.
param(
[Parameter(Mandatory)]
[Guid]$TenantId
)
$ErrorActionPreference = 'Stop'
$connected = $false
$file = Join-Path $PSScriptRoot ("m365-users-{0}.csv" -f (Get-Date -Format 'yyyyMMdd-HHmmss'))
try {
Connect-MgGraph -TenantId $TenantId.ToString() -Scopes 'User.Read.All' -ContextScope Process -NoWelcome
$connected = $true
$context = Get-MgContext
if ($context.TenantId -ne $TenantId.ToString()) {
throw 'Le locataire connecté ne correspond pas au locataire demandé.'
}
$properties = 'Id','DisplayName','UserPrincipalName','Mail','AccountEnabled','UsageLocation','AssignedLicenses'
$users = @(Get-MgUser -All -Property $properties)
if ($users.Count -eq 0) {
throw 'Aucun utilisateur renvoyé. Vérifiez la connexion et les autorisations.'
}
$report = @($users | Select-Object Id,DisplayName,UserPrincipalName,Mail,AccountEnabled,UsageLocation,
@{Name='AssignedSkuCount';Expression={ @($_.AssignedLicenses | Where-Object { $null -ne $_ }).Count }})
$report | Export-Csv -Path $file -NoTypeInformation -Encoding utf8BOM -NoClobber
Write-Host ("Enregistré : {0} / Nombre de comptes : {1}" -f $file, $report.Count)
$report | Select-Object -First 5 | Format-Table DisplayName,UserPrincipalName,AssignedSkuCount -AutoSize
}
finally {
if ($connected) {
Disconnect-MgGraph -ErrorAction SilentlyContinue | Out-Null
}
}
Après vous être déplacé dans le dossier où le fichier est situé dans PowerShell, exécutez comme suit. Ajustez le chemin du fichier à l'emplacement réel où il est enregistré, et collez l'ID de locataire de votre organisation dans le champ de saisie.
$targetTenant = Read-Host 'ID du locataire cible'
.\m365-users-report.ps1 -TenantId $targetTenant
Si l'opération réussit, le chemin du CSV et le nombre d'utilisateurs seront affichés, et les cinq premiers utilisateurs seront montrés à l'écran. Comparez le nombre de lignes du fichier avec le nombre d'utilisateurs à l'écran, et vérifiez le nom d'affichage, l'adresse de connexion, le lieu d'utilisation et la licence d'un compte test connu par rapport au centre d'administration. AssignedSkuCount représente le nombre de SKUs de produit attribués, et non le nombre de services individuels ou de licences achetées.
Même s'il y a des utilisateurs avec un Mail vide, ne supposez pas immédiatement une défaillance de la requête. Le nom de connexion, UserPrincipalName, et l'adresse e-mail sont des attributs différents. Même si AccountEnabled est vrai, la connexion réelle ou l'utilisation du service peut être restreinte en raison de licences, de politiques ou d'évaluations de risque. Ne concluez pas à partir de ce rapport seul qu'un utilisateur s'est récemment connecté ou effectue son travail normalement.
Si aucun résultat n'est retourné ou si la génération du CSV échoue, ne le marquez pas comme terminé. Vérifiez les autorisations pour le chemin de sortie, les fichiers portant le même nom, les verrouillages de fichiers et les messages d'erreur. Puisque le rapport reflète les résultats de la requête au moment de l'exécution, si les comptes ont changé, exécutez-le à nouveau pour comparaison, et gérez les fichiers précédents selon la politique de conservation de votre organisation.
Interrogation des produits sous licence et des affectations des utilisateurs
SKU (Stock Keeping Unit, identifiant de produit) est l'unité utilisée ici pour distinguer les produits sous licence. SkuPartNumber est la chaîne d'identification du produit, et SkuId est l'identifiant global unique du produit (GUID) utilisé dans les commandes Graph. Lors de la modification de l'affectation d'un utilisateur, faites la distinction afin de ne pas saisir l'ID de l'objet abonnement ou l'ID du plan de service à la place de l'ID SKU.
L'ensemble du script CSV se déconnecte à la fin, donc lors de l'exécution des commandes individuelles ci-dessous, reconnectez-vous à chaque fois. En plus des autorisations de lecture, le rôle pris en charge par cette opération est requis pour interroger les SKU d'abonnement. Consultez Rôles et Autorisations pour l'API de requête des SKU d'abonnement.
$tenantId = Read-Host 'ID du locataire cible'
Connect-MgGraph -TenantId $tenantId -Scopes 'User.Read.All','LicenseAssignment.Read.All' -ContextScope Process
Get-MgContext | Select-Object Account,TenantId,Scopes
Get-MgSubscribedSku -All | Select-Object SkuPartNumber,SkuId,CapabilityStatus,ConsumedUnits,@{Name='EnabledUnits';Expression={$_.PrepaidUnits.Enabled}}
$userId = Read-Host 'Nom UPN ou identifiant du compte à consulter'
Get-MgUserLicenseDetail -UserId $userId -All | Select-Object SkuPartNumber,SkuId,ServicePlans
ConsumedUnits est le nombre de licences consommées, et PrepaidUnits.Enabled est le nombre d’unités disponibles. Étant donné qu’il peut y avoir des états suspendus, d’avertissement ou des conditions de produit, il ne faut pas interpréter immédiatement la simple différence comme la quantité facturée ou les licences disponibles pour tous les produits. Les détails réels d’achat et de facturation doivent être confirmés séparément via Procédure de réconciliation des abonnements, de facturation et de quantité de licences.
Get-MgUserLicenseDetail inclut les licences assignées directement et héritées des groupes. Vous ne pouvez pas déterminer la cause de l’assignation uniquement à partir de ce résultat. Pour les assignations basées sur les groupes, vérifiez également le centre d’administration ou les informations sur le statut de l’assignation. Dans Détails des licences utilisateur API , vous pouvez également vérifier les permissions déléguées et les rôles pris en charge.
Exécutez séparément les opérations de modification des utilisateurs et des licences.
L'exemple suivant montre une opération qui modifie les données organisationnelles. Ne l'exécutez pas en batch immédiatement après le rapport de lecture ; reconnectez-vous avec les autorisations nécessaires après avoir préparé un utilisateur test approuvé et des enregistrements avant les modifications. L'option -WhatIf ci-dessous vous permet de prévisualiser l'opération que vous souhaitez exécuter et n'est pas un test fictif qui vérifie toutes les validations du serveur, les autorisations et les conditions de licence.
Créez un utilisateur test dans le cloud.
Utilisez cette méthode pour les utilisateurs gérés directement dans le cloud. Dans une organisation synchronisée, vérifiez d’abord si les comptes doivent être créés dans l’annuaire source. Choisissez un nom principal d’utilisateur (UPN, le nom de connexion) unique dans un domaine vérifié du locataire et un mot de passe temporaire conforme à sa politique. Créer un membre diffère d’inviter un collaborateur externe. Consultez les exigences et autorisations de création des utilisateurs, dont l’autorisation minimale User.Create, et confirmez le rôle administratif et son périmètre.
Disconnect-MgGraph
$tenantId = Read-Host 'ID du locataire cible'
Connect-MgGraph -TenantId $tenantId -Scopes 'User.Create','User.Read.All' -ContextScope Process
Get-MgContext | Select-Object Account,TenantId,Scopes
$upn = Read-Host 'UPN du compte de test à créer (domaine vérifié)'
$nickname = Read-Host 'Alias de messagerie (par exemple, graph-test01)'
$securePassword = Read-Host 'Mot de passe temporaire conforme à la politique' -AsSecureString
$params = @{
AccountEnabled = $true
DisplayName = 'Utilisateur de test Graph'
UserPrincipalName = $upn
MailNickname = $nickname
PasswordProfile = @{
Password = [System.Net.NetworkCredential]::new('', $securePassword).Password
ForceChangePasswordNextSignIn = $true
}
}
try {
New-MgUser -BodyParameter $params -WhatIf
}
finally {
$params.PasswordProfile.Password = $null
Remove-Variable securePassword
}
Après avoir vérifié les entrées et les cibles, pour créer réellement l'utilisateur, supprimez -WhatIf du code et exécutez-le à nouveau. Ne codez pas les mots de passe en dur dans les chaînes de ligne de commande ou dans les fichiers de script. Étant donné que les demandes SDK nécessitent des valeurs de mot de passe en texte clair, n'utilisez pas la sortie de débogage ni la journalisation du corps de la demande pour cette tâche, et transmettez les mots de passe temporaires par les canaux approuvés de l'organisation.
Après la création, vérifiez à nouveau le compte en utilisant Get-MgUser -UserId $upn -Property Id,DisplayName,UserPrincipalName,AccountEnabled. La simple création d'un utilisateur ne complète pas automatiquement les licences d'application, les boîtes aux lettres ou les appartenances à des groupes. La suppression d'un compte de test nécessite également un examen des données similaire à celui de la suppression d'un compte professionnel. Consultez procédures de départ et de transfert des données, puis examinez et organisez les comptes ciblés et les possibilités de restauration dans le centre d'administration.
Retirer les licences attribuées directement
Avant de retirer une licence, vérifiez l'utilisateur, le produit, s'il a été assigné directement ou via un groupe, et les exigences en matière de conservation des données. Dans cet exemple, -RemoveLicenses transmet à un tableau de chaînes d'ID SKU, mais n'inclut pas de table de hachage au format @{SkuId=...}. Utilisez -AddLicenses @() en même temps lorsqu'il n'y a pas de produits supplémentaires à ajouter. Vérifiez syntaxe de Set-MgUserLicense.
Disconnect-MgGraph
$tenantId = Read-Host 'ID du locataire cible'
Connect-MgGraph -TenantId $tenantId -Scopes 'LicenseAssignment.ReadWrite.All' -ContextScope Process
Get-MgContext | Select-Object Account,TenantId,Scopes
$userId = Read-Host 'UPN ou identifiant du compte de test dont retirer la licence'
$skuId = [Guid](Read-Host 'SkuId vérifié de la licence à retirer')
Set-MgUserLicense -UserId $userId -AddLicenses @() -RemoveLicenses @($skuId.ToString()) -WhatIf
Effectuez les changements après approbation et vérification de la cible, en retirant -WhatIf. Il faut à la fois le consentement pour LicenseAssignment.ReadWrite.All et un rôle pris en charge, par exemple Administrateur de licences. Pour une licence héritée d’un groupe, examinez son attribution au groupe ; la retirer directement de l’utilisateur ne suffit pas. Consultez les autorisations, rôles et format de requête de l’API d’attribution des licences.
Après le changement, reconnectez-vous avec les autorisations de lecture nécessaires et comparez les détails de la licence avec le centre de gestion. Lors du retour en arrière, vous devez vérifier les licences disponibles, les emplacements d'utilisation, et les plans de service précédemment désactivés afin de les réaffecter à la configuration originale. Ne supposez pas que la réactivation de la licence annulera toutes les suppressions de données effectuées précédemment. Il est important de assurer la conservation et le transfert des données avant le retrait de la licence.
Vérifiez la politique d'exécution de Windows et effectuez le retour en arrière
Les politiques d'exécution sont des conditions pour l'exécution de scripts et de modules. Si une erreur de blocage se produit sous Windows, vérifiez la politique effective et les valeurs par portée.
Get-ExecutionPolicy
Get-ExecutionPolicy -List
Seulement si la politique organisationnelle le permet et que le périmètre utilisateur actuel nécessite des modifications, enregistrez les valeurs précédentes et consultez RemoteSigned. Si les paramètres sont déjà autorisés, ne les modifiez pas simplement pour correspondre au format. Si MachinePolicy et UserPolicy de la politique de groupe organisationnelle ont la priorité, vérifiez avec la personne responsable et ne contournez pas.
$previousUserPolicy = Get-ExecutionPolicy -Scope CurrentUser
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
Get-ExecutionPolicy -List
Pour restaurer la valeur initiale, exécutez la commande suivante dans la même session. Dans une nouvelle fenêtre, utilisez la valeur réelle enregistrée auparavant. RemoteSigned ne signifie pas que tout code reçu d’Internet est fiable. Consultez les périmètres et priorités des stratégies d’exécution.
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy $previousUserPolicy
Erreurs courantes et terminaison des tâches
| Symptômes | Séquence de Vérification |
|---|---|
| Commande non reconnue | Vérifiez la version de PowerShell en cours d'exécution et l'emplacement d'installation du module. Get-MgUser se trouve dans Microsoft.Graph.Users. Utilisez Get-Command pour localiser la commande et distinguer les erreurs d'installation des erreurs d'importation. |
| 403 ou Privilèges insuffisants | Vérifiez le compte connecté, le locataire, les étendues, le consentement de l'administrateur et les rôles pris en charge pour l'API. N'ajoutez pas par défaut des autorisations complètes en écriture. |
| Impossible de trouver l'utilisateur ou l'objet | Vérifiez l'organisation et l'UPN/ID d'objet, ainsi que le statut de suppression/synchronisation. Assurez-vous que le nom du compte ne provient pas d'un autre locataire. |
| La propriété est vide | Distinguez si la propriété a été demandée avec -Property, si le compte a réellement une valeur et si la propriété nécessite des autorisations séparées. |
| Connexion bloquée | Enregistrez les codes d'erreur et les horodatages, et vérifiez l'accès conditionnel, l'authentification multifactorielle (MFA), les méthodes d'authentification autorisées et les journaux de connexion. Ne désactivez pas les politiques de sécurité pour une connexion réussie. |
Enregistrer la version d'installation, les erreurs détaillées des commandes, l'ID de la requête et le moment de l'occurrence ensemble peut aider à la reproduction et aux demandes de support. Même en utilisant la méthode dans diagnostic des erreurs Graph PowerShell, ne partagez pas les journaux contenant des jetons, mots de passe ou informations personnelles tels quels.
Après avoir terminé les exercices de commandes individuelles, déconnectez-vous et vérifiez le lieu de stockage des fichiers de résultats. Se déconnecter est différent d'annuler des modifications de compte ou de licence déjà effectuées.
Disconnect-MgGraph




