Get up to speed with PowerShell and the Microsoft Graph API

Why the Microsoft Graph?

For last several years, Microsoft has developed the Microsoft Graph, which is a unified programmability model used to work with the data from Microsoft 365, Windows 10 and the Enterprise Mobility and Security services.

Microsoft Graph connects the data from users with the Microsoft 365 services that admins can then use to pull information or to make configuration changes. Microsoft Graph connects to the Azure Active Directory, which is the technology used to manage identities of users on Office 365/Microsoft 365.

Microsoft Graph is a single endpoint that gives API access that returns many objects for Microsoft 365. For example, organizations could build applications that access data across multiple Microsoft 365 services instead of manually accessing various applications such as Exchange Online email, SharePoint Online files, Planner tasks and user information. Microsoft's future investments for identity management will focus on enhancing Microsoft Graph PowerShell commands.

Microsoft links all services within the Microsoft Graph to make it the best option to query and update Microsoft 365 services. There are software development kits (SDKs) available for several languages, including a new Microsoft Graph PowerShell module. Microsoft's goal is to ensure that every current Azure Active Directory feature has a matching Microsoft Graph command.

What is the difference between the current and the Microsoft Graph commands?

A core difference between Azure Active Directory and Microsoft Online commands, and the Microsoft Graph is the required PowerShell modules. The Azure Active Directory module is called AzureAD and the Microsoft Online module is named MSOnline. For the Microsoft Graph, the module name is Microsoft.Graph.

Another difference is the connection method to the specific service. You install and import the required module in the current model, then call the service-specific Connect command. For example, the AzureAD module uses Connect-AzureAD and the MSOnline online module uses Connect-MsolService while the Microsoft Graph module uses Connect-MgGraph.

The commands in the AzureAD and MSOnline modules support browser, credential object and token access authentication. However, the Microsoft Graph commands support browser, token access, certificate authentication and a requirement to pass the permissions, referred to as scopes, as part of the connection. The scopes determine which commands can execute within Microsoft Graph.

The following commands show how to connect using the AzureAD PowerShell module:

$credentials = Get-Credential
 Connect-AzureAD -Credential $credentials

The following commands show how to connect using the MSOnline PowerShell module:

$credentials = Get-Credential
 Connect-MsolService -Credential $credentials

Lastly, this example shows how to connect with the Microsoft Graph PowerShell module with a browser authentication request:

Connect-MgGraph -Scopes `
 "User.ReadWrite.All", `
 "Group.ReadWrite.All", `
 "GroupMember.ReadWrite.All", `
 "Application.ReadWrite.All"

One advantage of the Microsoft Graph PowerShell method is to use a predefined Azure Active Directory app registration and certificate with the corresponding Graph API permissions as a connection method, which gives you a way to create different connection types. The following example shows how to connect with this method.

$certificate = "a904602dd82ae51433e6f83996b00d4277a32a7b"
 $appid = "b0771954-8594-4fe8-88ad-025f7074a89e"
 $tenantid = "3f4b41d2-b28b-49d6-b441-2615829bb51f"
Connect-MgGraph `
 -CertificateThumbprint $certificate`
 -ClientId $appid `
 -TenantId $tenantid

Unlike the other PowerShell modules, the Microsoft Graph commands require passing the permissions, or what the company calls scopes, for the connection.

How to migrate from AzureAD or MSOnline to Microsoft Graph

The process to migrate PowerShell scripts that use either the AzureAD or MSOnline modules is no small task. You need to review each script for the current commands and then match it to the new Microsoft Graph equivalents.

There are four main steps for the migration process:

1. update the import and install module commands;
2. choose the best connection approach;
3. review the required permissions for the connection; and
4. update scripts with new commands from the Microsoft Graph module.

The process to update the import and install module commands is relatively easy, but be aware there are two endpoints: the current or version 1 and the beta. The commands are similar, but the beta ones have new or enhanced functionality. The import and install commands require the module name and the profile to use. To use the beta endpoint, execute Select-MgProfile and pass beta as the name.

Install-Module Microsoft.Graph
 Select-MgProfile -Name "beta"
 Import-Module Microsoft.Graph

Choosing the connection approach is more complicated. If you create static or distributable scripts, you might select a standard browser prompt versus the app registration route to follow the model of least privilege for a more secure approach. For most scripts, simply swapping the connect commands will work. However, the user who executes the script will potentially experience a different approach based on the consent prompt.

After choosing the connection approach, you need to define the permissions. Microsoft Graph uses a resource.operation.constraint model.

Microsoft Graph has a command to check the permissions for a specific category. You can identify the permission category name within Azure Active Directory when you assign API permissions to an app registration.

For example, to see the available permissions for working with users, you can execute the following command:

Find-MgGraphPermission user -PermissionType Delegated

After executing the command, you can view the available permissions for everything within the Microsoft Graph related to Users. For example, you can see the permissions for reading and writing user information within Azure Active Directory, as well as the ability to manage Microsoft Teams tabs for users.

You might need multiple category permissions to replicate the current PowerShell module functionality. For example, you need all the permissions listed within the scopes to manage Users, Mail, Teams Chat, People, the Directory, Groups, Tasks and Sites.

Connect-MsGraph -Scopes `
 "User.Read", `
 "User.ReadWrite.All", `
 "Mail.ReadWrite", `
 "Directory.Read.All", `
 "Chat.ReadWrite", `
 "People.Read", `
 "Group.Read.All", `
 "Tasks.ReadWrite", `
 "Sites.Manage.All"

The benefit of this approach is, with any update to permissions, you append them to the command, reissue the connection and then complete the consent.

Connect-MsGraph -Scopes `
 "User.Read", `
 "User.ReadWrite.All", `
 "Mail.ReadWrite", `
 "Directory.Read.All", `
 "Chat.ReadWrite", `
 "People.Read", `
 "Group.Read.All", `
 "Tasks.ReadWrite", `
 "Sites.Manage.All" `
 "eDiscovery.ReadWrite.All"

After connecting to the Microsoft Graph, you can access all the commands within the category or categories specified within the scopes.

To modifying a script that uses either the AzureAD or MSOnline PowerShell modules, the most common scopes required are:

• User.ReadWrite.All
• Group.ReadWrite.All
• GroupMember.ReadWrite.All
• PrivilegedAccess.ReadWrite.AzureADGroup
• Application.ReadWrite.All
• AppRoleAssignment.ReadWrite.All
• Domain.ReadWrite.All
• RoleManagement.ReadWrite.Directory
• RoleManagementPolicy.ReadWrite.Directory
• RoleAssignmentSchedule.ReadWrite.Directory
• RoleEligibilitySchedule.ReadWrite.Directory
• Policy.ReadWrite.ApplicationConfiguration
• Policy.ReadWrite.PermissionGrant
• DelegatedPermissionGrant.ReadWrite.All
• Directory.ReadWrite.All
• Contacts.ReadWrite
• Contacts.ReadWrite.Shared
• AdministrativeUnit.ReadWrite.All
• EntitlementManagement.ReadWrite.All

These permissions grant full read/write capability for the specified categories, and allow the execution of the PowerShell commands without permission issues.

For example, if a script based on the AzureAD module searches for specific user accounts, it needs to change to the new Microsoft Graph command.

#  AzureAD PowerShell Command
Get-AzureADUser `
 -Filter "UserPrincipalName eq '[email protected]'"
# Microsoft Graph PowerShell Command
Get-MgUser `
 -Filter "UserPrincipalName eq '[email protected]'"

The following example shows how to create a new user account, assign a license and then add the user to a security group with the MSOnline module and the Microsoft Graph equivalent:

# MSOnline PowerShell Command
 $userprincipalname = [email protected]
 $firstname = "Firstname"
 $lastname = "Lastname"
 $location = "US"
 $licensename = "ENTERPRISEPACK"
 $license = Get-MsolAccountSku | `
 Where-Object { $_.skuPartNumber -eq "$licensename" }
 $user = New-MsolUser `
 -UserPrincipalName $userprincipalname `
 -DisplayName "$firstname $lastname" `
 -FirstName $firstname `
 -LastName $lastname `
 -UsageLocation $location `
 -LicenseAssignment $license.AccountSkuId
 $searchstring = "Contoso"
 $group = Get-MsolGroup `
 -SearchString $searchstring
 $membershiptype = "User"
 Add-MsolGroupMember `
 -GroupObjectId $group.ObjectId `
 -GroupMemberType $membershiptype `
 -GroupMemberObjectId $user.ObjectId
# Microsoft Graph PowerShell Command
 $userprincipalname = [email protected]
 $firstname = "Firstname"
 $lastname = "Lastname"
 $location = "US"
 $licensename = "ENTERPRISEPACK"
 $passwordprofile = @{
 Password = "P@ssw0rd1"
 }
$license = Get-MgSubscribedSku | `
 Where-Object { $_.skuPartNumber -eq "$licensename" }
 $user = New-MgUser `
 -DisplayName "$firstname $lastname" `
 -PasswordProfile $passwordprofile `
 -AccountEnabled `
 -MailNickName "$firstname.$lastname" `
 -GivenName $firstname `
 -Surname $lastname `
 -UsageLocation $location `
 -UserPrincipalName $userprincipalname 
 Set-MgUserLicense `
 -UserId $user.UserPrincipalName `
 -AddLicenses @{ SkuId = $license.SkuId } `
 -RemoveLicenses @()
 $searchstring = "Contoso"
 $group = Get-MgGroup `
 -Search "DisplayName:$searchstring" `
 -ConsistencyLevel:eventual
 New-MgGroupMember `
 -GroupId $group.Id `
 -DirectoryObjectId $user.Id

The process to remap existing MSOnline or AzureAD PowerShell commands to work with the Microsoft Graph is not too complicated. However, you will need to review the new commands and the current documentation. It might also be helpful to look at the Microsoft Graph calls with the Graph Explorer to review the data formats for passing.

To find out more about Microsoft Graph PowerShell, click on this link.