Dans cet article nous verrons quelques bonnes pratiques à maitriser et connaître afin d’automatiser vos actions sur Intune avec PowerShell et Graph API.
Contexte
Vous réalisez différentes actions au travers du portail Intune.
Vous souhaitez les automatiser afin de gagner du temps ou par exemple permettre à des équipes de support de réaliser les mêmes actions sans passer par le portail Intune.
Vous souhaitez utiliser PowerShell pour ça et du coup Graph API, car pas de Graph API, pas de sucreries.
Il faut donc avant tout, comprendre ce qui est fait, en arrière-plan en Graph API, lorsque vous réalisez une action dans le portail Intune.
Le mode développeur du navigateur
Votre navigateur, Chrome ou Edge offre la possibilité de comprendre ce qui est fait lors d’un appel web sur un site. Cela peut se faire au travers du mode développeur. Celui-ci peut généralement s’ouvrir en tapant F12 dans votre navigateur, ce qui ouvrira un panneau de configuration.
Ce mode développeur vous permettra donc, en partant d’une action réalisée dans le portail, de voir ce qui est fait en Graph API.
Il vous sera alors possible de voir l’URL de la ressource utilisée, la méthode utilisée, le type de body à passer si besoin…
Il s’agit d’une de mes fonctionnalités préférées (pas assez connue) que j’utilise régulièrement lorsque Microsoft met en place une nouvelle fonctionnalité, afin de comprendre comment l’automatiser.
Pour accéder à ce mode développeur il faudra procéder comme ci-dessous :
1. Allez dans le portail Intune
2. Ouvrez le mode développeur avec F12
3. Allez dans l’onglet Network
4. Exécutez une action depuis le portail Intune
5. Stoppez l’enregistrement des logs depuis le mode dev
6. Accédez à l’URL Graph concernée pour comprendre ce qui est fait
Le mode développeur en action
Nous allons voir trois types d’actions que nous allons effectuer depuis le portail Intune en ouvrant le mode développeur en même temps afin de voir l’équivalence avec graph API.
– Lister les appareils
– Changer le nom d’un poste
– Redémarrer un poste
Lister les appareils
1. Allez dans Devices
2. Ouvrir le mode développeur avec F12
3. Allez dans l’onglet Network. Le bouton rouge indique que le mode développeur est en mode enregistrement. L’idée est donc d’effectuer l’action souhaitée afin de voir ce qui est fait derrière.
4. Allez dans All devices. En cliquant sur All devices, tout ce qui est fait en arrière plan sera affiché dans le mode développeur.
5. Cliquez sur l’icône rouge Stop recording network log. Nous voulons ici stopper l’enregistrement afin de ne pas être polluer par des actions supplémentaires.
6. Dans le mode développeur les différentes actions effectuées s’affichent (lorsque nous avons cliqué sur All devices)
7. Nous voyons une action nommée managedDevices
8. Cliquez dessus
9. L’URL de la ressource à utiliser est afficher
10. La méthode à utiliser ici est GET
11. Un clic droit vous permet de copier cela en PowerShell
Changer le nom d’un poste
1. Allez dans Devices
2. Allez dans All devices
3. Sélectionnez un appareil
4. Ouvrez le mode développeur avec F12
5. Allez dans l’onglet Network
6. Cliquez sur les …
7. Cliquez sur Rename device
8. Saisissez un nouveau nom comme POSTE-TEST
9. Cliquez sur Rename
10. Cliquez sur Stop recording network log
11. Dans le menu développeur la ressource sera affichée
12. Ici il s’agit setDeviceName qui est une action avec une méthode POST
13. Cliquez dessus
14. L’URL de la ressource est affichée
15. La méthode à utiliser est POST
16. Allez dans la partie Request Payload
17. Le JSON à utiliser est affiché (ci-dessus)
19. Il sera à insérer en format JSON dans la requête pour renommer l’appareil
Redémarrer un poste
1. Allez dans Devices
2. Allez dans All devices
3. Sélectionnez un appareil
4. Ouvrir le mode développeur avec F12
5. Allez dans l’onglet Network
6. Cliquez sur …
7. Cliquez sur Restart
8. Cliquez sur Stop recording network log
9. Dans le menu dev la ressource est affichée
10. Ici, il s’agit de rebootNow
11. Cliquez dessus
12. Le chemin de la ressource est affiché
13. La méthode à utiliser est POST
Graph X-Ray
Késako
Graph X-Ray est un super outil vous permettant de comprendre comment faire une action avec Graph API et PowerShell. Il s’agit d’une extension à intégrer dans votre navigateur.
Cet outil est développé par Merill Fernando, voir ici
Comment l’installer ?
Cela est dispo en tant qu’extension :
– Pour Chrome : ici
– Pour Edge : ici
Ou utilisez l’application depuis le MS Store.
Dans mon cas j’utilise l’extension pour Chrome.
Il faudra procéder comme ci-dessous :
1. Cliquez sur le lien
2. Cliquez sur Add to Chrome
3. Cliquez sur Add extension
Comment l’utiliser ?
Nous allons maintenant effectuer une action de listing des devices et voir l’équivalence au travers de Graph X-ray.
1. Allez dans le portail Intune
2. Allez dans Devices
3. Activez le mode développeur avec F12
4. Cliquez sur les >>>
5. Sélectionnez Graph X Ray
6. Dans le portail Intune, allez dans All devices
7. Graph X-Ray donne :
– La ressource utilisée
– Comment l’utiliser avec PowerShell
8. Vous pouvez ensuite sauvegarder le PowerShell en script
Trouver la bonne permission
Chaque action réalisée requiert une ou des permissions spécifiques. Redémarrer des appareils ne pourra bien entendu pas se faire avec la même permission que celle permettant de lister les postes.
Depuis la documentation Microsoft
Reprenons l’exemple précédent permettant de changer le nom d’un poste. Nous avons vu que le nom de l’action était setDeviceName.
Il suffira maintenant de saisir dans Google le nom de la ressource + Graph API : setDeviceName Graph API.
Nous arrivons ensuite sur la documentation Microsoft concernant cette ressource.
La partie permissions indiquera ensuite les permissions requises pour effectuer cette action:
Avec Find-MgGraphCommand
Il s’agit ici d’un module PowerShell permettant d’afficher la permission requise pour une ressource Graph.
La commande à utiliser est : Find-MgGraphCommand incluse dans le module Microsoft.graph.Authentication.
Reprenons l’exemple permettant de changer le nom du poste. L’URL de la ressource est la suivante :
Pour trouver la permission requise il suffira de saisir la commande suivante:
PS C:\Windows\System32> Find-MgGraphCommand -uri "/deviceManagement/managedDevices/{managedDeviceId}/setDeviceName"
APIVersion : beta
Command Module Method URI OutputType Permissions
------- ------ ------ --- ---------- -----------
Set-MgDeviceManagementManagedDeviceName DeviceManagement.Actions POST /deviceManagement/managedDevices/{managedDevice-id}/setDeviceName {DeviceManagementMa...L’affichage des permissions se fera comme ci-dessous:
PS C:\Windows\System32> Find-MgGraphCommand -uri "/deviceManagement/managedDevices/{managedDeviceId}/setDeviceName" | select Permissions
Permissions
-----------
{DeviceManagementManagedDevices.PrivilegedOperations.All}
Graph Explorer
Késako ?
Graph Explorer est un outil web vous permettant d’effectuer des requêtes Graph API sur votre tenant et votre environnement Intune ou autre.
Il vous sera alors possible de faire la même chose que depuis le portail Intune.
- Vous pouvez accéder à Graph Explorer via ce lien.
- Vous pouvez accéder à la documentation de Graph API via ce lien.
- Vous pouvez voir comment utiliser Graph API via ce lien.
A quoi ça ressemble ?
La partie principale de Graph Explorer se présente en cinq parties comme ci-dessous :
- Choix de la méthode
- Choix de la version de l’API Graph
- URL de la ressource Graph
- Body à insérer dans la requête
- Réponse de la requête
Les méthodes disponibles
Différentes méthodes permettent de gérer vos ressources (lister, modifier, créer/supprimer du contenu).
La liste déroulante ci-dessous vous permet de choisir la méthode à utiliser :
Ci-dessous les différentes méthodes et ce qu’elles font :
- GET : Lire les données à partir d’une ressource
- POST : Créer une nouvelle ressource ou effectuer une action
- PATCH : Mettre à jour une ressource avec de nouvelles valeurs
- PUT : Remplacer une ressource par une autre
- DELETE : Supprimer une ressource
Les versions de l’API
La seconde liste déroulante vous permet de choisir la version de l’API à utiliser. Deux versions sont disponibles : beta ou 1.0.
Ci-dessous une explication sur ces différentes versions de l’API :
La saisie de la ressource
Ce champ vous permet d’insérer le chemin de la ressource sur laquelle agir.
- Ce lien commence toujours par https://graph.microsoft.com
- Il faut ensuite ajouter la version de l’API puis le lien de la ressource (beta ou 1.0)
Le lien complet est composé comme ceci : Lien de Graph + Version de l’API + Lien de la ressource.
Partie Body et réponse
La première partie vous permet d’insérer le body permettant de créer ou modifier une ressource comme le nom d’un poste. Ce body doit être au format JSON.
La seconde partie permet d’afficher le retour de votre requête. La requête permettant de lister les appareils managés listera les devices dans un format JSON.
Graph Explorer en action
Dans l’exemple suivant nous allons lister les postes dans Intune.
Comme vu plus haut, la ressource à utiliser est la suivante : https://graph.microsoft.com/beta/deviceManagement/managedDevices
La méthode quant à elle, est GET.
Ci-dessous le retour de cette requête depuis Graph Explorer:
Les permissions
Comme mentionné précédemment, lorsque vous souhaitez gérer une ressource à l’aide de l’API Graph, des permissions sont requises.
Lorsqu’une permission est manquante, celle-ci est visible dans Graph Explorer dans la partie Modify permissions :
