PowerShell : comment se connecter à Microsoft Graph API ?

I. Présentation

Dans ce tutoriel, nous allons voir comment utiliser le module Microsoft Graph PowerShell pour s'authentifier sur son environnement Azure AD, Microsoft 365 ou Office 365.

À partir du 30 juin 2022, Microsoft ne supportera plus l'Active Directory Authentication Library (ADAL) et l'Azure Active Directory Graph API, deux composants utilisés pour s'authentifier sur Azure Active Directory. Autrement dit, ils permettent de s'authentifier sur Azure AD et Office 365 afin de réaliser toutes les opérations d'administration une fois la connexion établie, comme la création, la suppression et la modification de comptes sur Office 365. Les applications qui s'appuient sur ADAL ne pourront plus s'authentifier du tout, tandis que de façon générale il n'y aura plus de support et donc plus de mises à jour de sécurité.

Microsoft souhaite que les entreprises s'appuient sur le SDK Microsoft Graph qui permet de s'authentifier sur les services Cloud et les tenants Office 365 via Microsoft Graph API. Cette API est développée par Microsoft depuis plusieurs années et elle permet l'administration de l'ensemble des services Cloud, de façon un peu plus moderne.

Afin de préparer l'avenir, dans ce premier article je vais vous expliquer comment établir une connexion à Azure AD ou Office 365 via le module Microsoft Graph. Nous verrons les deux méthodes de connexion, ainsi que quelques astuces pour bien débuter avec ce module que moi-même je continue de découvrir.

II. PowerShell : l'avenir des modules AzureAD et MSOnline

Allons droit au but : si vous utilisez des scripts PowerShell qui s'appuient sur les modules AzureAD pour l'Azure Active Directory et MSOnline pour la partie Office 365, il va falloir mettre à jour ces scripts pour basculer sur Microsoft Graph. C'est indispensable, si vous ne souhaitez pas que vos scripts arrêtent de fonctionner à partir du 30 juin 2022.

À terme, ces deux modules vont être remplacés par Microsoft Graph, et le nom du module c'est "Microsoft.Graph" pour être précis. Puisque ce nouveau module est déjà disponible, cela vous permet de commencer ce travail de mise à jour de vos scripts et outils.

Toutes les commandes PowerShell vont évoluer puisque ce module contient son propre jeu de commandes. Par exemple, la commande New-MsolUser qui permet de créer un nouvel utilisateur Office 365 va être remplacée la commande New-MgUser.

Avant même de parler des commandes pour interagir avec les objets (utilisateurs, groupes, etc...) de votre tenant, il faut savoir que la connexion aux services va évoluer aussi. Oubliez les deux commandes Connect-AzureAD et Connect-MsolService disponible via les deux modules AzureAD et MSOnline. La connexion à votre environnement avec le module Microsoft Graph s'appuie sur Connect-MgGraph. D'ailleurs, cette nouvelle commande fonctionne différemment, comme nous allons voir dans la suite de ce tutoriel.

Pour le moment, nous avons encore plusieurs mois devant nous pour mettre à jour nos scripts PowerShell, donc il n'est pas nécessaire de paniquer. De mon côté, je vais travailler sur l'actualisation de mes articles PowerShell qui parlent Office 365 et Azure pour vous aider également.

II. Microsoft Graph : les deux modes de connexion

Lors de l'utilisation du module Microsoft Graph et du cmdlet Connect-MgGraph pour établir une connexion à votre tenant, vous avez le choix entre deux modes de connexion :

• Une connexion avec un accès délégué

Avec le mode "accès délégué", il faut préciser les permissions dont vous avez besoin au moment de la connexion au tenant, et c'est en se connectant avec un compte qui a les droits que vous allez pouvoir créer cette délégation et permettre l'accès aux ressources.

• Une connexion avec un accès application

Avec le mode "accès application", il est nécessaire d'inscrire une nouvelle application dans Azure Active Directory afin de créer un point de connexion. Ensuite, il faudra accorder des autorisations à cette application pour que les scripts qui l'utilisent soient en mesure d'effectuer les actions déclarées dans votre code PowerShell. Pour se connecter via cette méthode, il faudra spécifier plusieurs informations : ID du tenant, ID de l'application et un nom de certificat ou une empreinte de certificat (qu'il faudra générer en amont).

Il faut savoir qu'au-delà du mode de connexion, il y a deux points de terminaison disponibles côté Microsoft : Microsoft Graph v1.0 et Microsoft Graph Beta. Sans surprise, le point de terminaison permet de bénéficier des dernières fonctionnalités en avant-première.

Avant d'établir la connexion à Microsoft Graph, vous pouvez choisir le point de terminaison que vous souhaitez utiliser. Par défaut, Microsoft Graph v1.0 est utilisé.

Pour basculer sur le profil bêta, il faudra exécuter cette commande :

Select-MgProfile -Name "beta"

À l'inverse, pour sélectionner de nouveau la V1.0, il faudra exécuter :

Select-MgProfile -Name "v1.0"

Pour ce tutoriel, je vais utiliser Microsoft Graph v1.0 comme point de terminaison.

Il est temps de passer à la pratique, en commençant par l'installation du module.

III. Installer le module PowerShell Microsoft Graph

Le module Microsoft Graph est disponible sur la PowerShell Gallery (voir ici) et il s'installe avec la commande "Install-Module" comme les autres modules.

Si vous souhaitez l'installer uniquement pour l'utilisateur en cours, utilisez le scope "CurrentUser" et pour l'installer au niveau de la machine précisez "AllUsers" (droits administrateur requis).

Ce qui donne :

Install-Module Microsoft.Graph -Scope CurrentUser
Install-Module Microsoft.Graph -Scope AllUsers

L'installation de ce module global prend généralement plusieurs minutes car il installe tous les sous-modules. Une fois que c'est fait, vous pouvez vérifier avec cette commande que le module est installé :

Get-InstalledModule Microsoft.Graph

Pour ma part et à titre indicatif, c'est la version 1.9.1 qui est installée (dernière en date).

IV. PowerShell : Microsoft Graph via l'accès délégué

Commençons par étudier le principe de connexion via l'accès délégué, à partir de la commande Connect-MgGraph. Je vous rappelle que cette commande sert à établir une connexion à Microsoft Graph via PowerShell.

Lors de la connexion à Microsoft Graph, il faut spécifier un ou plusieurs scopes (étendues) en fonction de ce que vous cherchez à effectuer. Afin de pouvoir utiliser les étendues sélectionnées, une délégation d'accès sera créée au moment de la connexion.

Par exemple, si l'on souhaite récupérer la liste des utilisateurs de notre tenant, on a besoin d'un accès en lecture aux utilisateurs. Cela se traduit par le nom d'étendue suivant :

User.Read.All

Dans le cas où l'on aurait besoin de créer un nouvel utilisateur, l'étendue serait différente puisqu'il faudrait des droits d'écriture. L'étendue à utiliser serait :

User.ReadWrite.All

Je vais vous donner quelques astuces par la suite pour identifier les étendues. Il faut savoir que l'on peut sélectionner plusieurs étendues, et que ce n'est pas anormal d'en sélectionner entre 5 et 10.

Continuons sur l'idée suivante : récupérer la liste des utilisateurs, à partir de l'étendue "User.Read.All". La commande Connect-MgGraph à exécuter sera :

Connect-MgGraph -Scopes "User.Read.All"

Cette commande va ouvrir un navigateur sur votre machine afin d'effectuer la connexion et d'accorder l'accès à l'application "Microsoft Graph PowerShell". Cela nécessite un accès avec des droits administrateur. Il faudra accepter la requête, comme sur l'exemple ci-dessous.

Ensuite, un message s'affiche pour indiquer que la fenêtre peut être fermée : Authentication complete. You can return to the application. Feel free to close this browser tab.

Retour dans la console PowerShell. Un message "Welcome To Microsoft Graph!" doit être visible !

Pour lister les utilisateurs, on va tout simplement utiliser cette commande :

Get-MgUser

Comme le montre l'image ci-dessous, la liste des utilisateurs est retournée. Parfait !

Si l'on essaie de lister les groupes, on peut voir que l'on obtient un message d'erreur : Insufficient privileges to complete the operation. En bref, nous n'avons pas les droits, ce qui est normal puisque l'on a pas précisé l'étendue qui permet de lire les groupes au moment de la connexion !

Get-MgGroup

Dans la console PowerShell en cours, on peut exécuter une seconde fois Connect-MgGraph pour ajouter l'étendue "Group.Read.All" qui permettra de lire les informations des groupes.

Connect-MgGraph -Scopes "Group.Read.All"

Cela va venir s'ajouter à la session déjà ouverte et donc conserver l'étendue "User.Read.All". Suite à l'exécution de cette commande, il faut de nouveau approuver la connexion via le navigateur. Désormais, on peut récupérer la liste des groupes.

La prochaine fois, vous pouvez appeler directement les deux étendues :

Connect-MgGraph -Scopes "User.Read.All","Group.Read.All"

Du fait que cette méthode nécessite une interaction et une validation via le navigateur, elle n'est pas faite pour être utilisée dans des scripts. La seconde méthode que nous allons voir dès maintenant sera plus adaptée.

Juste avant cela, on va se déconnecter proprement de Microsoft Graph :

Disconnect-MgGraph

V. PowerShell : Microsoft Graph via l'accès application

Nous devons inscrire une nouvelle application au sein d'Azure Active Directory, puis ensuite lui accorder des autorisations. Cette application sera notre point d'entrée avec PowerShell.

À partir du portail Azure, dans Azure Active Directory, cliquez sur "Inscriptions d'applications" à gauche puis sur le bouton "Nouvelle inscription".

Donnez un nom à cette application, par exemple "Script-PowerShell-Graph". Conserver l'option "Comptes dans cet annuaire d'organisation uniquement" pour l'option "Types de comptes pris en charge" et pour l'URI de redirection, laissez vide.

Cliquez sur le bouton "S'inscrire".

L'application est inscrite. Il y a deux informations qu'il faudra récupérer par la suite, car nous en aurons besoin lors de la connexion avec PowerShell : ID d'applications (client) et ID de l'annuaire (locataire).

Désormais, nous devons accorder des autorisations à notre application.

B. Attribuer des autorisations Microsoft Graph à l'application

Toujours sur le portail Azure, au sein de notre application, cliquez sur "API autorisées" à gauche puis au centre sur "Ajouter une autorisation".

Nous souhaitons ajouter une autorisation "Microsoft Graph" et cela tombe bien c'est proposé directement.

Cliquez sur "Autorisations de l'application".

Ensuite, il faut rechercher les autorisations. Cela fonctionne sur le même principe que les étendues de la première méthode de connexion étudiée. Pour trouver l'autorisation qui permet de consulter la liste des groupes, il suffit de rechercher "group" et de cocher l'option "Group.Read.All". Pour les utilisateurs, suivez le même principe.

Cliquez sur "Ajouter des autorisations" pour ajouter toutes les autorisations sélectionnées.

Il faut que l'on accorde un consentement administration au niveau de l'organisation pour pouvoir bénéficier de ces droits dans notre application, à savoir notre script PowerShell. Cliquez sur le bouton "Accorder un consentement d'administrateur pour IT-Connect" et validez.

Tous les feux sont au vert :

Passons à la troisième étape : la gestion du certificat.

C. Générer un certificat auto-signé avec PowerShell

Nous allons créer un certificat auto-signé puis l'exporter au format CER puis PFX.

Le format PFX est intéressant pour transférer le certificat et sa clé privée sur un autre serveur : une étape indispensable si vous souhaitez vous authentifier auprès de votre application depuis plusieurs serveurs différents. Le certificat (et sa clé privée) devra être déployé sur chaque machine devant se connecter à l'application.

Grâce à la commande ci-dessous, nous allons créer un certificat auto-signé et le stocker dans le magasin de certificat personnel local. Remplacez seulement "IT-Connect" par le nom de votre organisation.

$cert = New-SelfSignedCertificate -Subject "CN=IT-Connect" -CertStoreLocation "Cert:\CurrentUser\My" -KeyExportPolicy Exportable -KeySpec Signature -KeyLength 2048 -KeyAlgorithm RSA -HashAlgorithm SHA256

Ensuite, il faut exporter ce certificat sur notre machine, car il va falloir le charger sur Azure AD. En PowerShell toujours, c'est faisable avec la commande "Export-Certificate". Pour ma part, je l'exporte dans "C:\TEMP" mais adaptez le chemin dans la commande ci-dessous.

Export-Certificate -Cert $cert -FilePath "C:\TEMP\IT-Connect.cer"

Si vous avez besoin d'utiliser ce certificat sur d'autres serveurs (ce qui sera le cas si un autre serveur doit s'authentifier sur Microsoft Graph via PowerShell), vous devez l'exporter au format PFX. Si vous n'avez pas ce besoin, vous pouvez ignorer les deux commandes qui suivent.

Commençons par créer un mot de passe pour la clé privée associée à notre certificat :

$mdp = ConvertTo-SecureString -String "MotDePasse" -Force -AsPlainText

Ensuite, on exporte au format PFX avec Export-PfxCertificate en précisant le certificat via $cert, le mot de passe via $mdp et le chemin vers le fichier de sortie au format PFX.

Export-PfxCertificate -Cert $cert -FilePath "C:\temp\IT-Connect.pfx" -Password $mdp

Une fois que c'est fait, il suffira de copier le PFX sur les autres serveurs et de l'importer. Pensez à stocker le mot de passe de la clé privée dans votre gestionnaire de mots de passe préféré...

Retournez sur l'interface Azure AD, toujours dans notre application, et cliquez sur "Certificats & secrets" sur la gauche. Ensuite, cliquez sur "Télécharger le certificat" et chargez le fichier CER. Validez et il va apparaître dans la liste des certificats comme ceci :

Copiez la valeur "Empreinte numérique" (Thumbprint), car nous allons en avoir besoin pour la suite.

D. Connexion à Microsoft Graph avec le certificat

Voilà, la configuration est prête : nous allons pouvoir nous connecter à Microsoft Graph via PowerShell. Pour cela, il nous faut trois informations :

• L'ID d'applications (client) pour le paramètre -ClientID
• L'ID de l'annuaire (locataire) pour le paramètre -TenantId
• L'empreinte numérique du certificat pour le paramètre -CertificateThumbprint

Ce qui donne la commande Connect-MgGraph suivante :

Connect-MgGraph -ClientID a8615473-xxxx-yyyy-zzzz-123456789123 -TenantId 806d3d28-aaaa-bbbb-cccc-123456789123 -CertificateThumbprint A3FA9DEE117D49EC8F2A1CFF4567FABC3

Exécutez cette commande, et là, c'est magique on est directement authentifié ! Aucune action n’est nécessaire, c'est la combinaison de ces trois valeurs (et la présence du certificat sur la machine) qui permet de s'authentifier sur Microsoft Graph.

En termes de droits, on est limité à ce qui est déterminé au niveau des autorisations de l'application. Si l'on ajoute des droits à notre application via le portail Azure, il faudra se déconnecter et se reconnecter pour que ce soit pris en compte.

Disconnect-MgGraph
Connect-MgGraph -ClientID a8615473-xxxx-yyyy-zzzz-123456789123 -TenantId 806d3d28-aaaa-bbbb-cccc-123456789123 -CertificateThumbprint A3FA9DEE117D49EC8F2A1CFF4567FABC3

Il ne reste plus qu'à interagir avec notre environnement Microsoft ! Cette méthode d'authentification est idéale pour vos scripts PowerShell.

VI. Microsoft Graph : comment identifier les permissions ?

Sur le principe, Microsoft Graph est prometteur notamment sur la gestion très fine des permissions, mais cela peut rapidement devenir un casse-tête pour trouver les bonnes permissions. Je crois que chez Microsoft ils en ont conscience, car il y a un cmdlet qui permet de rechercher plus facilement des permissions : Find-MgGraphPermission.

Si l'on souhaite obtenir toutes les permissions Microsoft Graph relatives à Microsoft Teams, on pourra exécuter la requête suivante (cela ne nécessite pas d'être authentifié auprès de Microsoft Graph).

Find-MgGraphPermission teams

Vous allez voir que cette commande retourne deux sections : Delegated pour l'accès délégué et Application pour l'accès application. En fonction de ce que vous recherchez, précisez le type de permissions, car le nom peut varier :

Find-MgGraphPermission teams -PermissionType Delegated

ou

Find-MgGraphPermission teams -PermissionType Application

Grâce à la sortie de cette commande et le filtre, on peut trouver plus facilement le nom des permissions. Pour les groupes, les utilisateurs, etc... On peut rechercher.

Find-MgGraphPermission groups
Find-MgGraphPermission user

En complément, vous pouvez retrouver des informations sur cette page qui référence l'ensemble des permissions (un CTRL+F sera inévitable pour rechercher dans la page) :

• Microsoft Docs - Référentiel des permissions

Les permissions c'est une chose, mais ensuite il faut trouver la bonne commande, ou en tout cas la commande de remplacement vis-à-vis de ce que l'on connait avec les modules MSOnline et AzureAD. Pour cela, on peut s'aider de Get-Command avec un filtre sur un mot clé. Par exemple :

Get-Command -Module Microsoft.Graph* *team*

À vous de jouer ! Pour ma part, cet article d'introduction me servira de point de départ pour les prochains d'articles qui parleront de cas particuliers : création d'utilisateurs, manipulation d'équipes Teams, de boites aux lettres, etc... N'hésitez pas à partager votre retour d'expérience avec Microsoft Graph en postant un commentaire.

• Découvrir le module Microsoft Graph V2 pour PowerShell