Microsoft Graph V2 – PowerShell : Nouveautés, migration V1/V2 et avenir des modules AzureAD/MSOnline
jeudi 13 juillet 2023 à 08:21I. 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 :
| V1.0 | Beta |
|---|---|
| Get-MgUser | Get-MgBetaUser |
Les modules nécessaires sont logiquement :
| V1.0 | Beta |
|---|---|
| Microsoft.Graph | Microsoft.Graph.Beta |
| Microsoft.Graph.Users | Microsoft.Graph.Beta.Users |
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 !
The post Microsoft Graph V2 – PowerShell : Nouveautés, migration V1/V2 et avenir des modules AzureAD/MSOnline first appeared on IT-Connect.
