Manage Intune with MS Graph and PowerShell

In this post I will show how to manage Intune resources using PowerShell and Graph.
In my previous post, I explained how to interact with Intune using the Graph API from Graph Explorer.

In this article, we will see the below points:
- Understand the query format
- Choose your method
- Intune and Resources
- Find the ID of a resource
- Graph, Intune and permissions
- List, create, update or delete 
- Manage Intune with PowerShell
- What is this module ?
- Install the module
- Connect to Intune
- Connect with saved credentials
- Find the appropriate cmdlet
- No cmdlet ? Use Invoke-MSGraphRequest
- How to list Deployment profiles
- How to modify a deployment profiles
- How to create a deployment profile
- How to delete a deployment profile

Understand the query
Microsoft Graph contains two versions of the API:
- v1.0: includes generally available APIs. Use the v1.0 version for all production apps.
- beta: includes APIs that are currently in preview. 

The query always with the Graph link: https://graph.microsoft.com
The full query is composed as below:
Graph link + API version + resource

This can be translated as below:
https://graph.microsoft.com/$APIVersion/$resource

To manage a specific resource, like a device, add id of this resource to the query link:
https://graph.microsoft.com/$APIVersion/$resource/$id

Choose your method
To manage a resource you first need the query to this resources, as we have seen before.
You will then have to choose the method to manage this resource, meaning what you want to do on it.

The Graph API is composed of five methods:
- GET: Read data from a resource.
- POST: Create a new resource, or perform an action.
- PATCH: Update a resource with new values.
- PUT: Replace a resource with a new one.
- DELETE: Remove a resource

Intune and Resources
Each part in Intune is called resource, for instance a device, a user, a deployment profile...
All those resources are accessible from intune as well as from PowerShell (using the Graph API).
It means if you want to access to a specific Intune resource through PowerShell, you have to find the equivalent using Graph.

Where to find the approriate Intune resource with Graph ?
The Microsoft Graph documentation is pretty cool.
You can access it on this link.
Now, let's find the equivalent resource from Intune to Graph.

Enrolled devices
All devices that are enrolled to your Intune organization are available from the Intune portal, as below:

If you want to access the same list using Graph and PowerShell, procced as below:
1. Open the MS Graph documentation
2. Select the API version (in our case Beta)

3. In the search bar, type managed device
4. Hey we are, click on managed device

5. You can find all that you can do to manage your devices
6. For instance, to list our devices, go to the Get part

7. The Http request part explains how to use the resource in the query. 
The resource link to use to manage device is: /deviceManagement/managedDevices

8. The full link will be: https://graph.microsoft.com/beta/deviceManagement/managedDevices 

Action on devices
There are many actions available to manage device.
See below some of them from the Intune portal:

We will check for instance how to reboot a device.
1. Open the MS Graph documentation
2. Select the API version (in our case Beta)
3. In the search bar, type reboot
4. Hey we are, click on rebootNow

5. You may notice that this is an action of our previous resource managed device meaning we will use the same link and add the specific action
6. The resource for reboot will be: /deviceManagement/managedDevices/{ID of the device}/rebootNow

7. The full query link will be: https://graph.microsoft.com/beta/deviceManagement/managedDevices/{ID of the device}/rebootNow

Deployment profiles
Autopilot Deployment profiles are available from the Intune portal as below:

To manage them using Graph proceed as below:
1. Open the MS Graph documentation
2. Select the API version (in our case Beta)
3. In the search bar, type deployment profile
4. Hey we are, click on Windows autopilot deployment profile

5. Click on the Get part

6. The Http request part explains how to use the resource in the query. The resource link to use to manage device is: /deviceManagement/windowsAutopilotDeploymentProfiles
7. The full query link will be: https://graph.microsoft.com/beta/deviceManagement/windowsAutopilotDeploymentProfiles

Find the ID of a resource
If you want to do an action, modify or delete a specific resource you have to add its ID to the Graph query.
You can find this ID from the Intune portal.
For instance, if you want to reboot a device:
1. Click on the device
2. In the address bar you will find its ID, as below:

Graph, Intune and permissions
By default you can't do what you want on Intune using Graph.
Indeed you have to add some permissions to your account to manage resources.

How to find those permissions ?
To find the permission to add to do a specific action, go to the Graph API doc, as we have done to find our resource.
The permission will be displayed in a Prerequisites part.
For instance, we will check the appropriate permissions to reboot a specific device.
1. Open the MS Graph documentation
2. In the search bar, type reboot
3. Click on rebootNow
4. The Prerequisites part indicates permissions to add to execute this action

List, create, update or delete 
As mentioned previously, there are five methods available to manage our resources.

Get: list resources
To get a list of resource, for instance device, we will use the Get method.
To list all properties of a specific resources, like a device, we will use the get method and add the ID of this resource to the query.

Delete: delete a resource
To remove a specific resource, the method to use is Delete. To use it you have to add the id of the resource to delete, for instance the deployment profile to remove.

Post: create a new resource
To create a new resource, like a new deployment profile, the method to use is Post.
This method is a bit different than the Get and Delete methods.
Indeed, you have to provide the resource informations with a JSON format.
You can find an overview in the JSON Representation part from the Graph API doc:

You don't need all the JSON, you can just add some parameters, as below:

Patch: change a resource 
To modify informations of a resource, use the Patch method.
This one works like the Post method, meaning you have to add the JSON information of the resource you want to modify.
The difference is that you have to add the ID of the resource to manage to the resource query.
For instance, if you want to add a description to the deployment profile we have previously created use the JSON below:
So far we have seen what is the Graph query and how to manage resources using available methods, now we will see how to proceed from PowerShell.



Manage Intune with PowerShell

What is this module ?
A cool and easy way to play with Intune is to use the module Microsoft.Graph.Intune
For now the module does not contain a cmdlet for each Intune part, we will see how to manage resource that don't have yet a cmdlet.
This module has been created by Microsoft.
You can find more informations here. 

Install the module
To install it, use the install-module command as it's available on the PSGallery, as below:
See below a function to install the module if needed

Once the module is installed you can list all available cmdlet as below:
See below the result:

Connect to Intune
We will search a command that will be useful to connect to Intune.
For that let's use the below line:
Yipi Kayyyyy, one match, the cmdlet: Connect-MSGraph

Let's test it basically without any customization. 
We will try to list Intune devices. 
To find the appropriate cmdlet type the below line:
We can find one cmdlet with get Verb: Get-DeviceManagement_ManagedDevices

Now let's see what it does if we type this cmdlet:
This error occurs because  we need to connect before to list Intune resources.

For that, proceed as below:
1. Type Connect-MSGraph
2. This will open a GUI to type your Intune credentials
3. Type your credentials and click on connect

4. Type again: Get-DeviceManagement_ManagedDevices
5. This will list devices

Connect with saved credentials
Now instead of prompting the user credentials, we will save them in order to use them automatically.
- The intune user account is saved in a variable $Intune_UDP
- The password will be saved in a text file: $Intune_PWD_File

1. In this part we will create an encrypted password and save it 
2. Then we will import the content of this file in a variable
3. Now we will create a PSCredential object to for our Intune account
4. Add a PSCredential parameter to the Connect cmdlet
5. See below the full script:

Find the appropriate cmdlet
The module contains a lot of cmdlets (1056) meaning it can be a bit difficult to find the appropriate cmdlet to find a specific ressource.

List devices 
For instance,we want to list devices located in Intune.
In the Intune portal those one are as below (as we have seen previously):
1. As seen before the cmdlet to use is: Get-DeviceManagement_ManagedDevices
2. Type Get-IntuneManagedDevice
3. Devices will be listed

To list properties of specific device add parameter managedDeviceId and its ID:

Action on device
As in the first part, we will check the cmdlet to reboot a computer.

The appropriate cmdlet is: 
Invoke-DeviceManagement_ManagedDevices_RebootNow
Let's see how to use it using the get-help cmdlet as below:

To reboot a specific device you have to specify id using the parameter: managedDeviceId
We will reboot the device with ID: 988bfcaf-15d7-403c-a1ba-9072677e254e
This one from the Intune portal

See below the cmdlet to reboot the device
See below the warning from the Intune portal:

A reboot warning will be displayed on the device:

No cmdlet ? Use Invoke-MSGraphRequest
If you don't find the cmdlet for your resource, use the cmdlet: Invoke-MSGraphRequest.
- Add the URL of your resources by adding the -url parameter
- Add the method to use, using the HttpMethod parameter
- Add a JSON, using the Content parameter

Now we will see for instance how to work with autopilot deployment profile.
If we search profile in the module cmdlet, we don't find nothing relative to deployment profile.

In this cas we will use the cmdlet Invoke-MSGraphRequest and search the appropriate resource on the Graph API doc.
As we have seen before, the resource to manage deployment profile is: deviceManagement/windowsAutopilotDeploymentProfiles

Now proceed as below:
1. We will use the method: Get
2. We will use the parameter HttpMethod with resource link below:
https://graph.microsoft.com/beta/deviceManagement/windowsAutopilotDeploymentProfiles
3. See below the full link to do this:
4. To list property and value, type the below cmd:
5. See below the result:

Create a deployment profile
To create a deployment profile we need four things:
- Cdmlet Invoke-MSGraphRequest
- Resource link
- Method POST
- JSON informations of the resource to create

1. See below the JSON informations we will use:
2. We will integrate it in a variable as below:
3. See below the full query:
4. See below the result:

Update a deployment profile
Now let's use the same cmdlet to update a deployment profile to add a description.
1. We will change the description of the device with the following ID:
2. We will use the method Patch
3. See below the JSON informations we will use:
4. See below the full query:

Remove a deployment profile
1. We will remove the device with the following ID
2. We will use the method Delete
3. See below the full query:

We will see another method to manage Intune with PowerShell without the module.



Manage Intune without the module
You can find on the MSGraph GitHub some ways to connect to Intune using PowerShell. 
One of them is to use a function Get-AuthToken then connect to Intune.

This method is composed in two functions:
- Get-AuthToken: Create the authentification process
- Connect-AutoPilotIntune: Connec to Intune

The functions
Get-AuthToken
Connect-AutoPilotIntune

Connect to Intune
1. Run both functions 
2. Type Connect-AutoPilotIntune
3. Type your Intune user mail 
4. A GUI will be opened to type your password

5. Your are now connected to your Intune tenant

Test a simple query
Now we are connected we will use the Graph API to list some Intune resoures.
For this example, we will list Intune devices.
To query Intune we will use the cmdlet: Invoke-RestMethod
1. The resource for Intune device is: deviceManagement/managedDevices
2. The full URL should be: https://graph.microsoft.com/beta/deviceManagement/managedDevices
3. Type the below command to list devices:
4. See below the result:

Modify a profile
1. Use the cmdlet Invoke-RestMethod 
2. Add the resource link: https://graph.microsoft.com/beta/deviceManagement/windowsAutopilotDeploymentProfiles
3. Add the ID of the deployment profile to modify
4. We will use the method: PATCH
5. We will copy the new JSON with modification in a variable
6. See below the full query: