Microsoft is retiring the Azure AD Graph endpoint by Dec 2022, it is high time that admins learn how to install & connect to Microsoft Graph PowerShell SDK and start to modify all the existing scripts with the new module. Out goes Get-AzureADUser and we need to get familiar with Get-MgUser.
The whole process starts with installing the Microsoft Graph PowerShell SDK on your machine. In this article, we will have a look at how to install the new SDK, connect to the Graph endpoint and get some output.
Why Microsoft Graph?
For once, because Microsoft says so! And they are pulling the plug on Azure AD & MSOL endpoints. Below are the main reasons why Microsoft moved to Graph API.
Graph API has a single endpoint (https://graph.microsoft.com) and we can connect to all the services in Microsoft 365 using that endpoint. Comparing that to the Azure AD & MSOL modules, you had to connect to various services one by one, say Exchange Online, SharePoint Online etc.
MS Graph will work with PowerShell, Power Automate, .NET etc & it is the ‘modern’ way to interact with Microsoft 365. The ability to set granular permissions is another big win.
Prerequisites for Graph SDK
It is recommended to have PowerShell 7 on the machine. Run the command below to install PS 7.
winget install --id Microsoft.PowerShell
You can confirm the version of the PowerShell by running $PSVersionTable
You also need to make sure that the PowerShell execution policy is set to RemoteSigned. The command below will achieve that.
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
You don’t need the scope parameter if you have admin rights on the machine.
How To Install Microsoft Graph PowerShell SDK?
Installing the main SDK module of Graph will also install all 38 sub modules. It is recommended that you only install the necessary modules, unless you work in a small to medium organization and is responsible for all things in the Microsoft cloud platform. The Microsoft.Graph.Authentication module is mandatory if you choose to install sub modules individually.
Launch PowerShell (as an admin if you want to install for all users) or Windows terminal (Windows 11).
Run the command below to install the SDK in PowerShell Core or PowerShell, if you don’t have local admin rights on the machine.
Install-Module Microsoft.Graph -Scope CurrentUser
You can change the scope in the command above so that all users on the machine can use the modules. Run the command below if you have local admin rights.
Install-Module Microsoft.Graph -Scope AllUsers
Accept the installation from the untrusted repository by typing ‘A’ & press the enter key.
It will take a few minutes for it to download all the modules.
You can run the command below if you want to verify the version of the SDK installed.
How To Connect To MS Graph API?
Connecting to Graph endpoint requires the API version you are trying to connect to (stable version or beta) and the required scope. The scope is the set of permissions that you will have in the session. For example, if you are trying to read the user information, you need the User.Read.All scope (permission).
If you want to connect to the beta endpoint (as you will have preview features, but not supported), run the command below.
Select-MgProfile -Name "Beta"
If you want to flip to the stable supported version, run
Select-MgProfile -Name "V1.0"
Now that we have picked the stable version, we need to define the scope. This depends on what we are trying to achieve. For example, If we are trying to get some information about the Azure AD groups (Get-MgGroup), we need to know what permissions are available. Running the command below lists the permission scopes.
Find-MgGraphCommand -command Get-MgGroup | Select -First 1 -ExpandProperty Permissions
So if you want to update a group, the scope we need is Group.ReadWrite.All, you get the idea.
The command we need to connect to the MS Graph API is Connect-MgGraph. If you want to read user data and read & write group information, you can define multiple scopes. Run the command below to achieve that.
Connect-MgGraph -Scopes "Group.ReadWrite.All", "User.Read.All"
You will be asked to login if you don’t already have a session with M365. Some scopes will need you to consent on behalf of the organization if you are connecting for the first time.
You can run a command like Get-MgGroup | select Id, GroupTypes to verify that everything is working as expected and that you have some output from your tenant. Yes, you can pipe the info like in PowerShell.
Figuring Out the Graph Commands
It is a bit of a challenge to find the correct command when you start using a new API like Graph. This is where the good old Get-Command comes in. If you want to know the commands that are available under the Microsoft.Graph.Users module, run the command below.
Get-Command -Module Microsoft.Graph.Users
The command below will give you a list of all cmdlets that you can use with Graph API. It will be a big list for sure, about 21,000+ at the time of writing.
Get-Command -Module Microsoft.Graph.*
Once you have finished with your work with Graph API, you can disconnect using the command below (you guessed it right)!.
If you manage multiple tenants and want to connect to the second tenant (after disconnecting from the first one), it is best to use the -TenantId parameter to avoid using the token cache from the previous session.
Connect-MgGraph -TenantId <tenantid>
In short, we have learned
- how to install PowerShell 7 & MS Graph PowerShell SDK,
- about API versions and how to find the scope,
- connect to the Graph endpoint using scopes & API version,
- how to find cmdlets available within a module and
- to disconnect & connect to a different tenant.
Let me know if you have any questions in the comment below.