The Microsoft Graph API allows us to interact with all Microsoft services through a single source. To do this from PowerShell, we always had to install different modules and make different connections. This is no longer necessary with the Microsoft Graph SDK Module for PowerShell.
We could already use the Graph API with the help of Invoke-Webrequests calls, but that was not really easy to work with. The new Microsoft Graph Module comes with a lot of cmdlets to make interacting with the services a lot easier.
In this article, I will explain how to install the Microsoft Graph Module and how to connect to it using different permissions.
Microsoft Graph PowerShell SDK
The Graph module is actually called the Microsoft Graph PowerShell SDK and is a wrapper for all Microsoft Graph APIs. At the moment it only seems to replace the Azure AD module. The other modules that we use to interact with Microsoft 365 don’t seem to be replaced by it at the moment.
On June 30, 2022, the Azure AD Graph endpoint will be deprecated. This means that calls made with the Azure AD Module won’t get a response anymore. So it’s important to rewrite all your scripts that use the Azure AD Module to the Microsoft Graph module.
As mentioned, the Microsoft Graph PowerShell SDK allows us to interact with all APIs from Microsoft. This means that we could also use the module to interact with SharePoint, Exchange Online, Compliance, etc.
Another advantage of the module is that it supports PowerShell 7 and above. The Azure AD Module, for example, doesn’t work on PowerShell 7.
Installing the Microsoft Graph Module in PowerShell
The Microsoft Graph SDK Module exists, at the moment, out of 38 modules. We can install them all at once, but you might want to consider installing only the modules that you really need.
Note
Make sure that you install atleast the Microsoft.Graph.Authentication module when installing individual modules
You can view all available modules with the following command:
Find-Module Microsoft.Graph*
We are going to install the Microsoft Graph module only for the current user. It’s also possible to install it for all users, but then you will need to open PowerShell with elevated permissions.
- Open PowerShell or Windows Terminal
– Right-click on Start or press Windows Key + X
– Select Windows PowerShell or Windows Terminal (on Win 11) - Install the SDK
Enter the following command in PowerShell to install the module:Install-Module Microsoft.Graph -Scope CurrentUser
- Accept the Untrusted Repository
Type Y to install from the Untrusted Repository - Wait for the installation to finish
When installing all modules it can take a couple of minutes before the installation is completed
Connecting to Microsoft Graph from PowerShell
There are two things important when connecting to Microsoft Graph, you can specify the API version and you will need to define the scope. By default, the module will use the stable version of the API. But you can also change this to the Beta version of the API. This allows you to explore new features.
The other important step is that you will need to specify the scopes that you want to use. Graph offers access to all APIs from Microsoft. So when you want for example to export or view the Azure AD users, you only need to have User.Read.All permission.
Finding Microsoft Graph Scopes
Finding the right scope can be a bit challenging at the beginning. But there are two good sources that you can use to determine which scopes you will need to specify:
- Microsoft Graph Explorer
- Microsoft Graph Rest API Reference
The Microsoft Graph Explorer is a great tool to test out API calls to Microsoft Graph. It comes with a lot of example calls to help you get started. But it will also list the required permission for the call.
- Open the Graph Explorer
- Select a Sample Query on the left side
- Click Modify Permissions tab
You will need to at at least one of the scopes mentioned in the Permission tab when connecting to MS Graph in PowerShell.
The other option is to use the Rest API Reference. You can select in the left menu one of the entities that you want to work with and then view the required permissions. You don’t need to add all scope, they are listed from least to most privileged.
Connecting to MgGraph in PowerShell
We now know which profile we want to use and how to find the scope that we need. So let’s connect to Microsoft Graph.
First, we need to set the API version that we want to use. I am going to use the Beta version, but if you want to create a script for production, then you won’t need to select it.
Select-MgProfile -Name "beta" # To switch back to production use: Select-MgProfile -Name "v1.0"
Next, we want to connect to Graph with the scopes that we need:
Connect-MgGraph -Scopes "User.Read.All","Group.ReadWrite.All"
You will need to authenticate and grant permission. Some scopes require to grant permission on behalf of your organization.
You can now use the Graph API. When you are working with Graph in PowerShell you can add additional scopes to your session by simply using the Connect-MsGraph command
again with the new permissions.
Update Microsoft Graph Module
The Microsoft Graph module is still being developed with new features added regularly. So it’s important to keep your module up to date, so you can use the latest Graph cmdlets in your PowerShell scripts.
To update the module, we can use the Update-Module cmdlet in PowerShell, followed by the module name:
Update-Module Microsoft.Graph
Wrapping Up
It can be a bit challenging to find the correct cmdlets of the Microsoft Graph SDK Module, but it’s great that one module allows us to interact with all Microsoft services. At the moment of writing is the documentation still a bit thin, so it’s a lot of trial and error to write scripts with it.
I hope this article helped you to get started with the MgGraph module. If you have any questions, just drop a comment below.
Can the AzureAD module coexist with the Microsoft Graph module? Or do I need to rewrite scripts right after installing the MG Mod?
You can use them together on your machine.
Hi there,
So to confirm running this process will replace the connecting to Azure AD process that was used previously? When this process is run it will prompt for the tenant ID and the authenticated user to connect to in order to run the main script that will ultimately pull users from Azure AD.
Sorry for the question but I am home sick and just putting some documentation together to start trying to get permissions sorted out on building a script to do all this.
Just not 100% clear what is going to be needed when this is setup in Powershell to run the first time.
The plan is indeed for MgGraph to replace AzureAD. But the exact date is unknown yet.
Why do you start Windows Terminal as an administrator , while all you do is install Microsoft Graph module in the scope of the current user? That doesn’t make sense to me.
Correct, starting the terminal as an administrator is not needed in this case.