Microsoft Entra ID (formerly Azure AD) is an enterprise access management and identity system for Microsoft cloud services. This enterprise identity system gives you access to rights to your application, manages user identities, and much more. With PowerShell automation, you can automate tasks, filter, and query data, generate reports, and access features that aren’t offered in the Microsoft Entra admin center portal.
In this comprehensive guide, we will look at how to get started with Microsoft Graph PowerShell SDK for Microsoft Entra ID which replaces the legacy MSOL PowerShell and AzureAD PowerShell modules moving forward.
Table of Contents
Introduction
Before the introduction of Azure Active Directory PowerShell (AzureAD PowerShell), we used to manage Microsoft Entra ID (formerly Azure AD) directory objects using the Microsoft Online (MSOL) PowerShell module.
Then Microsoft introduced a newer Azure Active Directory V2 PowerShell module instead of the MSOL module. IT Professionals often use the AzureAD PowerShell module to manage their Azure Active Directory. With the cmdlets provided in this module, you can easily retrieve data from the directory, create new objects, update existing objects, remove objects, and configure the directory and its features.
Microsoft announced that AzureAD Powershell is planned for deprecation on March 30, 2024. It’s strongly recommended to move to Microsoft Graph PowerShell SDK if you access Azure AD through the AzureAD PowerShell or MSOnline PowerShell module, which enables you to access all MS Graph APIs and supports PowerShell Core, external identities, and modern authentication.
Microsoft Graph PowerShell SDK is the way moving forward which is a PowerShell module that you can use to interact with Microsoft Entra ID and other Microsoft online services (SharePoint, Exchange, and Teams) and it replaces the legacy Microsoft Online (MSOL) and AzureAD PowerShell modules.
One of the drawbacks of using the legacy MSOL and AzureAD PowerShell modules is that they are dependent on Windows PowerShell, so you cannot run it on PowerShell Core and this also means that you cannot run it on macOS, Linux, and even you cannot run it in Azure Functions, and a lot of other scenarios. So, moving to Microsoft Graph PowerShell SDK and PowerShell Core opens up a lot of multi-platform and serverless scenarios.
Related: Mastering Microsoft Entra ID – A Comprehensive Guide.
Microsoft Graph PowerShell SDK
In this section, we will discuss and show you how to install, update, and work with the Microsoft Graph PowerShell module.
Install Microsoft Graph PowerShell
The install command is quite simple. First, you need to install the module and the name is “Microsoft.Graph“, you can either install it as your current user or you can install it for all users, which in turn will require admin privileges.
# Install Graph module for Current User
Install-Module -Name Microsoft.Graph -Scope CurrentUser
# Install Graph module for All Users (Admin privilege)
Install-Module -Name Microsoft.Graph -Scope AllUsers
Now with the new Graph PowerShell SDK version 2, the beta commands have been moved to a different module. So, if you want to run beta commands against the MS Graph Beta endpoint, then you need to install a separate module because, in the first version of the SDK, you could switch the scope from beta to version 1.0 in the same module.
So, this has changed now, there are two separate modules and it makes sense on several levels, but it’s something you might need to think of to rewrite your scripts and plan.
# Install Graph Beta module
Install-Module -Name Microsoft.Graph.BetaIt’s recommended to use Microsoft Graph v1.0 for scripting purposes. However, in some cases, the beta endpoint may be required for testing or early adoption of features that are not yet available in v1.0. It’s important to note that the Microsoft Graph beta endpoint is still in preview and subject to change.
If you want to install the latest Graph module version and you want to run it side-by-side with an older version, you can run the same “Install-Module” command and add the “-Force” parameter.
# Install Graph module for Current User side-by-side
Install-Module -Name Microsoft.Graph -Scope CurrentUser -ForceIf you want to update the Graph PowerShell module to the latest version, you can run the “Update-Module” command below:
# Update Graph module for Current User
Update-Module -Name Microsoft.Graph -Scope CurrentUserYou can use the same commands above for the Graph PowerShell SDK version 1 and the beta version.
Verify Microsoft Graph Modules
There are some commands you can use to check what kind of modules you have installed, version management, which is always a good practice. You can run the “Get-Module“, the name “Microsoft.Graph“, and “-listAvailable -All“, you will get all the installed different versions of the Graph module.
# Verify Graph Module
Get-Module -Name Microsoft.Graph -ListAvailable -AllAs shown in the figure below, we are running the latest version 2.6.1 side-by-side with an older version 2.4.0 of the Microsoft Graph PowerShell module.
You can also look at each submodule by running the command below, “Get-InstalledModule” name “Microsoft.Graph” append with an asterisk (*), and you can see what kind of submodules you have installed.
# Verify Microsoft Graph submodules
Get-InstalledModule -Name Microsoft.Graph.*
For example, there are modules for managing users, applications, devices, authentication, etc… There are different sub-modules for those as well.
To uninstall the main “Microsoft.Graph” PowerShell module, you can run the following command:
# Uninstall Microsoft Graph SDK
Uninstall-Module Microsoft.Graph -AllVersionsYou can also remove and uninstall a specific Microsoft Graph version by running the “Uninstall-Module” command.
# Remove Graph versions that you had previously installed
Uninstall-Module -name Microsoft.Graph -RequiredVersion 2.4.0 -ForceThen, you can remove all of the dependency modules and submodules by running the following command:
# Uninstall all Microsoft Graph submodules
Get-InstalledModule Microsoft.Graph.* | `
? Name -ne "Microsoft.Graph.Authentication" | `
Uninstall-Module Microsoft.Graph.AuthenticationConnect to Microsoft Graph PowerShell
The connection part to Microsoft Graph is of course very important. You can connect interactively and you can log on as yourself or with an admin user you have access to.
You connect to Microsoft Graph by running the following command and then it will just take you through the authentication process.
# Interactive authentication to Microsoft Graph
Connect-MgGraphYou can also connect to Microsoft Graph by specifying the Tenant ID.
# Interactive authentication to Microsoft Graph with specified Tenant
Connect-MgGraph -TenantId tenantname.onmicrosoft.comYou can also use device authentication which will make sense if you need to log on to a device that doesn’t have a browser or you don’t have the opportunity to log on interactively on that device, but you can do it via another device. So, when you use the device authentication you will get the device code, then you can go to another device and type in that device code and authenticate with another user.
Device authentication is useful for IoT devices, for example, or other devices that just don’t support interactive logon. Please note that device authentication will time out after 120 seconds (2 minutes) if you don’t authenticate.
# Microsoft Graph Device authentication
Connect-MgGraph -UseDeviceAuthentication
Once you are connected to Microsoft Graph, you will be greeted with a welcome message. You can add the “-NoWelcome” parameter to suppress the Welcome to Microsoft Graph message.
You can also connect with an access token, so if you already have an access token it can be acquired in different ways. You can log in with that by using the “-AccessToken” parameter.
# Connect to Microsoft Graph using Access token
Connect-MgGraph -AccessToken $AccessTokenNow for application scenarios where you can connect as an application. First, you need to register an app in your Microsoft Entra Tenant and with that, you can either connect with a certificate-based authentication (CBA) or with a client ID and client secret for example.
# Connect to Microsoft Graph using Application
Connect-MgGraph -ClientId "YOUR_APP_ID" `
-TenantId "YOUR_TENANT_ID" `
-CertificateThumbprint "YOUR_CERT_THUMBPRINT"More importantly, you can also connect to Microsoft Graph using Managed Identity, but then you need to run from an actual Azure service that has connected as Managed Identity. For example, you can have a Managed Identity connect it to an Azure Function app, and then you can connect to the Microsoft Graph in that way.
# Connect to Microsoft Graph using Managed Identity
Connect-MgGraph -IdentityReference: Authentication module cmdlets in Microsoft Graph PowerShell.
After signing in, you will stay signed in until “Disconnect-MgGraph” command is invoked. Microsoft Graph PowerShell securely caches the token, and the access token is automatically refreshed, so sign-in persists across PowerShell sessions.
To disconnect from Microsoft Graph, you need to run the “Disconnect-MgGraph” command to sign out.
Microsoft Graph Permissions Scopes
If you just connect to Microsoft Graph as described in the previous section without specifying scopes, you will have some default access and the user can do that. But you might not be able to do anything with the default access. For example, you cannot change users, or modify users, you cannot change groups, you cannot add the authentication methods, etc. You need to specify what kind of information you’re looking for. So, if you’re running without scopes, you can only check your user account.
For example, if you run “Connect-MgGraph” and you specify the scope “User.Read.All“, then it will let you look up and read user information.
# Connect with Scopes Read all Users
Connect-MgGraph -Scopes User.Read.AllYou can add and specify several scopes to the same “Connect-MgGraph” command as shown below.
# Connect with Scopes Read and Write all Users
Connect-MgGraph -Scopes User.Read.All, User.ReadWrite.All
Now for some scenarios, you need more delegated permissions. For example, if you want to look up device information for users, you might need to have been assigned a role as an Intune Administrator in addition to the scope device management configuration.
# Connect with Scopes Read for Intune device management
Connect-MgGraph -Scopes `
User.Read.All, `
DeviceManagementConfiguration.Read.AllIf you want to change, add, create, update, or delete users. You need to have the Microsoft Entra ID (User Administrator) built-in role in addition to specifying the scope when connecting to Microsoft Graph. So, that’s the delegated scenario, where you log on and run queries as yourself.
Another example, you want to create groups and read all group properties and memberships, you need the scope “Group.ReadWrite.All” delegated permission. This will also allow you to read and write calendars, conversations, files, and other group content for all groups the signed-in user can access.
# Connect with Scopes Read/Write all Groups
Connect-MgGraph -Scopes `
User.Read.All, `
Group.ReadWrite.All In this case, you will be asked for additional permissions: Read all users’ full profiles, which is the “User.Read.All” scope, and then we have read and write all groups, which is the “Group.ReadWrite.All” scope. As shown in the figure below, you need to consent to that.
These are permissions that users might not be able to consent to themselves because these are specific kinds of permissions “ReadWrite.All” and they require admin consent. So you might encounter some issues here. If you don’t have the appropriate permissions to approve admin consent-based personal permissions yourself, then you need assistance from the Global Admin.
A very good tip to find the necessary permissions is to use something called the “Find-MgGraphCommand“, follow by the desired command, “Get-MgUser” for example, then you add the pipe “|” and select first “1” expand property permissions.
# Find necessary Microsoft Graph permissions
Find-MgGraphCommand -command Get-MgUser | `
Select -First 1 -ExpandProperty Permissions | `
Sort IsAdminThe “Find-MgGraphCommand” will show you the list of one the required permissions that you need to run the “Get-MgUser” command. In this example, the least privileged scope permission that you need to run the “Get-MgUser” command is “User.Read“.
The “True” and “False” listed under the “IsAdmin” column dictates if you need an admin privilege (True) or least privilege (False).
But if you are looking for full user profile information then you need the “User.Read.All” scope to look up other users, otherwise, you can only look up for yourself. So, if you don’t have admin permissions, then you need to work with the Global Admin to help you with the consent.
To automate the admin consent, you can set up and configure the admin consent requests workflow, so you can make requests that require admin approval, otherwise, you will be blocked.
Azure AD Compatibility Adapter
The Microsoft Graph PowerShell Compatibility for AzureAD is in preview at the time of this writing. This module was developed by Microsoft to make the bridge between running the old Azure AD commands and the new Microsoft Graph commands a little bit closer.
You can install the Microsoft Graph PowerShell Compatibility module from the PowerShell gallery by running the following command. You specify “-AllowPrerelease” because it’s not released yet.
# Install Microsoft Graph Compatibility Module
Install-Module Microsoft.Graph.Compatibility.AzureAD -AllowPrerelease
# Import Microsoft Graph Compatibility Module
Import-Module Microsoft.Graph.Compatibility.AzureAD -Force -Verbose
Then you can go and run commands by just replacing the word “*AzureAD*” with “*CompatAD*” as if you were running the old commands using the AzureAD PowerShell module for example.
Once the Microsoft Graph Compatibility module is installed, you need to connect first to Microsoft Graph and then run the “Get-CompatADUser” for example. The “Compat” command will run against the Microsoft Graph endpoint, and you can run these commands in PowerShell Core as well.
# Connect to Microsoft Graph
Connect-MgGraph
# The old command with *AzureAD* Module
Get-AzureADUser -SearchString "Charbel Nemnom"
# The new command with *CompatAD* Module
Get-CompatADUser -SearchString "Charbel Nemnom"
With the Microsoft Graph Compatibility module, you provide the same commands that you did have in the old AzureAD module, and then you can run it similarly against the Microsoft Graph SDK.
As a best practice, you should uninstall all versions of the AzureAD PowerShell module or AzureAD preview module, because you might encounter some issues. Then you can run the “compat” commands and you can basically run the same commands you had before, so this is an easy way to convert your Azure AD scripts.
If you want to see the Graph calls for a specific command, then you can add the “-Debug” parameter to the command as follows:
# Run commands with -Debug to see the Graph calls
Get-CompatADUser -SearchString "Charbel Nemnom" -DebugThis command will show you more information about how the actual request is running against the Microsoft Graph endpoint, and you will even see how you can do this natively with Microsoft Graph PowerShell: “Get-MgUser“. This is a nice way to get more information and see the Graph output running the “Get-CompatADUser” by just adding the “-Debug” parameter.
So, if you want to convert all your existing Azure AD scripts to Graph PowerShell SDK, it makes sense to have the compatibility module installed and then run debug, you will get all the Graph extra information, and then it will help you find the correct commands moving forward.
Last, you can implement some aliasing in the compatibility module. First, you need to set and enable aliases by running the “Set-CompatADAlias” command which will activate the aliasing of your existing AzureAD module.
Once, you activate the aliases, you can then run the “Get-Alias -Name *AzureAD*” command and you will see all the active aliases for AzureAD commands.
What that means is that from now on, you can run the “Get-AzureADUser” command, even though we haven’t installed the AzureAD module. So, now you can run your old commands but against the new Graph endpoint as shown in the figure below.
If you have existing scripts, for example, you can continue running them by activating the aliasing part in the compatibility module. These are some ways you can use to get to the new PowerShell Graph SDK if you have existing scripts and these are helpful tools.
There you have it. Happy identity management with Microsoft Graph PowerShell!
Wrapping Up
In this article, you learned how to install, connect, and work with the Microsoft Graph PowerShell SDK for Microsoft Entra ID.
Remember to update the MS Graph module to the latest version, create an application, and assign API permissions if you connect with a client secret or certificate-based authentication (CBA). With CBA, there are no more user interactions, usernames, passwords, or MFA involved in running automated scripts.
By following the steps outlined in this guide, you can effectively use the Microsoft Graph PowerShell SDK for Entra ID management and automation, unlocking endless possibilities while gaining knowledge and confidence.
__
Thank you for reading my blog.
If you have any questions or feedback, please leave a comment.
-Charbel Nemnom-
