Microsoft Graph V2 – PowerShell : Nouveautés, migration V1/V2 et avenir des modules AzureAD/MSOnline

I. Présentation

Nous en parlions il y a déjà un peu plus d'un an pour la première fois, le SDK Microsoft Graph pour PowerShell est désormais disponible en V2 (2.0.0) depuis le 5 juillet 2023.

Il est temps de revenir sur certaines annonces et évoquer les améliorations et changements de cette nouvelle version.

II. Avenir des modules AzureAD, AzureADPreview et MSOnline ?

Comme évoqué dans notre article de 2022, Microsoft souhaite que vous migrez vos scripts sur la technologie Microsoft Graph si vous utilisez encore les modules "AzureAD", "AzureADPreview" ou "MSOnline" !

En effet, suite aux dernières annonces, Microsoft rendra ces anciens modules obsolètes à partir du 30 mars 2024.

Certaines commandes de ces anciens modules sont d'ailleurs déjà dépréciées ! C'est le cas par exemple de Set-AzureADUserLicense et Set-MsolUserLicense qui permettent la gestion des licences sur les utilisateurs. Ces commandes peuvent être remplacées (non sans effort...) par l'équivalent Microsoft Graph : Set-MgUserLicense.

Il n'existe malheureusement pas à ce jour d'outil permettant de convertir vos anciens scripts directement, cependant, Microsoft vous propose un guide, ainsi qu'une carte des cmdlets afin de vous aider à migrer les commandes AzureAD/MSOnline les plus utilisées vers Graph.

Cependant, et parce que c'est vous, voici quelques outils non officiels qui pourront vous être utile :

• Graph PowerShell Conversion Analyzer
• Module PSAzureMigrationAdvisor
• Graph PowerShell Samples Community

III. Installation de Microsoft Graph

A. Première installation

Si vous souhaitez installer l'ensemble des modules pour la première fois, je vous recommande simplement d'exécuter la ligne ci-dessous :

Install-Module Microsoft.Graph -Scope CurrentUser

Facultativement, vous pouvez également installer les modules "Beta" :

Install-Module Microsoft.Graph.Beta -Scope CurrentUser -AllowClobber

Attention, "Beta" ne veut pas dire ici que les modules sont en "pré-version", mais que ces modules fonctionnent en utilisant l'API Graph version "Beta".

Plus de détails dans le chapitre Séparation des modules API "v1.0" et "Beta" de cet article.

B. Upgrade des modules V1 vers V2

Si vous avez déjà les anciens modules d'installés, vous seriez tenté d'utiliser la commande suivante :

Update-Module Microsoft.Graph

Cependant... Vous remarquerez sûrement quelques modules qui, étrangement, ne se mettent pas à jour, par exemple Microsoft.Graph.Financials. Tout simplement, ces modules n'existent plus dans la version V2 classique, mais sont uniquement en version "Beta".

Pour éviter de tout mélanger, le mieux reste de supprimer proprement tous les anciens modules.

Il suffit de lister les modules "Microsoft.Graph.xxxx" et de les supprimer. Puis de supprimer le module principal "Microsoft.Graph".

Fermez toutes vos fenêtres PowerShell puis exécutez ce qui suit dans une nouvelle console pour effectuer cette opération :

Get-Module Microsoft.Graph.* -ListAvailable | Uninstall-Module -Force 
Get-Module Microsoft.Graph -ListAvailable | Uninstall-Module -Force

Si nécessaire, exécutez les commandes précédentes dans une fenêtre "en tant qu'administrateur".

Vérifiez bien que tous les modules sont supprimés, le résultat doit être vide :

Get-Module Microsoft.Graph* -ListAvailable

Si tout est bien supprimé, il ne reste plus qu'à installer les modules, comme indiqué dans le chapitre Première installation :

Install-Module Microsoft.Graph 
# Facultatif 
Install-Module Microsoft.Graph.Beta -Scope CurrentUser -AllowClobber

IV. Nouveautés et changements

Via cette nouvelle version, Microsoft promet des modules beaucoup plus légers et performants, une meilleure gestion des erreurs... Mais également beaucoup d'autres nouveautés à prendre en compte si vous souhaitez continuer d'utiliser vos scripts V1.

Pour les plus curieux, voici le changelog complet : What's Changed

A. Séparation des modules API "v1.0" et "Beta"

Le plus gros changement, vous avez pu le voir lors de l'installation, Microsoft a décidé de diviser l'intégralité des modules en deux parties.

Les modules n'ayant pas "Beta" dans le nom, utilisent simplement l'API Graph en version v1.0, les modules "Beta" eux en revanche utilisent le endpoint "Beta".

La commande Select-MgProfile n'est donc plus d'actualité !

Pour utiliser l'API Graph en version Beta, il suffit d'ajouter "Beta" après '*-Mg' dans toutes les cmdlets. Par exemple :  Get-MgGroup -> Get-MgBetaGroup.

Autre exemple, ce code auparavant :

Connect-MgGraph 
Select-MgProfile "v1.0" 
$V1Users = Get-MgUser 
Select-MgProfile "beta" 
$BetaUsers = Get-MgUser

Devient désormais plus simple et plus clair via les nouveaux modules :

Connect-MgGraph 
$V1Users = Get-MgUser 
$BetaUsers = Get-MgBetaUser

Il faudra en revanche penser à installer les modules nécessaires, par exemple pour les cmdlets ci-dessous :

Les modules nécessaires sont logiquement :

Les modules "Microsoft.Graph" & "Microsoft.Graph.Beta" étant systématiquement indispensables.

C. Client Secret Credentials

Il est désormais possible de s'authentifier facilement en tant qu'application de manière interactive en utilisant le "Client_ID" de votre application et son secret :

$ClientCredential = Get-Credential -Username "Client_ID" 
# Coller ensuite le secret dans la fenêtre qui s'affiche 
Connect-MgGraph -TenantId "Tenant_ID" -ClientSecretCredential $ClientCredential

Cette méthode peut également être utilisée sans interaction, pour planifier des scripts en utilisant simplement le Client_ID + Secret. Pour cela, il faudra créer un objet "credential", par exemple :

$ClientSecretCredential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $Client_ID, $SecuredPassword 
Connect-MgGraph -TenantId "Tenant_ID" -ClientSecretCredential $ClientSecretCredential

D. Connect-MgGraph -AccessToken : Désormais "SecureString"

Si vous utilisiez ce type de code pour générer un jeton afin de vous connecter :

$tenantID = "MyTenantID" 

$ReqTokenBody = @{ 
   Grant_Type = "client_credentials" 
   Scope = "https://graph.microsoft.com/.default" 
   Client_Id = "ClientID" 
   Client_Secret = "SECRET"
} 

$TokenResponse = Invoke-RestMethod -Uri "https://login.microsoftonline.com/$tenantID/oauth2/v2.0/token" -Method POST -Body $ReqTokenBody 

# Connexion 
Connect-MgGraph -AccessToken $TokenResponse.access_token

Désormais, il sera nécessaire de modifier la dernière ligne tel que :

Connect-MgGraph -AccessToken (ConvertTo-SecureString -String $TokenResponse.access_token -AsPlainText)

Car le paramètre -AccessToken n'accepte plus de texte (string) directement, pour des raisons de sécurité.

E. Authentification via variables d'environnements

Enfin, il est également possible de s'authentifier via des variables d'environnement :

$Env:AZURE_CLIENT_ID = "Votre ClientID" 
$Env:AZURE_TENANT_ID = "Votre TenantID" 
$Env:AZURE_CLIENT_SECRET = "Votre SECRET" 

Connect-MgGraph -EnvironmentVariable

Voir toutes les variables existantes : Environment variables

V. V1 to V2 migration toolkit

Pour vous faciliter la tâche et vous aider à migrer vos scripts, Microsoft a mis à disposition ce guide : Microsoft Graph PowerShell V2 Changelog and Upgrade Guide

Celui-ci vous permettra de comprendre plus en détail tous les changements apportés par cette nouvelle version.

Cependant, Microsoft met également à disposition une nouvelle commande (New-MgMigrationPlan) qui vous permettra d'analyser et migrer vos scripts pour vous !

Vous pouvez par exemple simplement scanner un script et voir le résultat :

New-MgMigrationPlan -FilePath "C:\Chemin\Script.ps1"

Ou mieux, scanner votre script et exporter une version upgradée directement :

New-MgMigrationPlan -FilePath "C:\Chemin\Script.ps1" -UpdatedFilePath "C:\Chemin\NEW_ScriptV2.ps1"

Encore mieux... Vous pouvez mettre vos scripts dans un seul dossier et analyser/upgrader vos scripts d'un seul coup :

New-MgMigrationPlan -Directory "C:\Dossier_Scripts" -UpdatedFilePath "C:\Dossier_Scripts_V2"

J'espère que toutes ces informations vous seront utiles que ce soit pour faire vos premiers pas avec Microsoft Graph ou pour migrer vos scripts !

Adrien LECLEUZIAT Ingénieur Système

Ingénieur système - Passionné des solutions Microsoft et addict à PowerShell !

See Full Bio