The Microsoft Graph PowerShell SDK is made up of a set of modules that enable you to interact with the Microsoft Graph API using PowerShell commands. The modules consist of commands that act as wrappers for the API, allowing you to access all the features and functionality of the API through PowerShell.

Modules | Getting Started | API Version | Notes | Troubleshooting | Known Issues | Feedback | License

This repository publishes complete bundle modules, the authentication module, and scenario-specific modules for the Microsoft Graph v1.0 and beta endpoints. For faster installation and import, prefer the scenario-specific modules you need instead of the complete Microsoft.Graph and Microsoft.Graph.Beta bundle modules. The bundle modules install all their respective scenario-specific modules as dependencies.

Module	Latest	Preview
Microsoft.Graph		-
Microsoft.Graph.Beta		-
Microsoft.Graph.Authentication		-
Microsoft.Graph.Applications		-
Microsoft.Graph.Bookings		-
Microsoft.Graph.Calendar		-
Microsoft.Graph.ChangeNotifications		-
Microsoft.Graph.CloudCommunications		-
Microsoft.Graph.Compliance		-
Microsoft.Graph.CrossDeviceExperiences		-
Microsoft.Graph.DeviceManagement		-
Microsoft.Graph.DeviceManagement.Administration		-
Microsoft.Graph.DeviceManagement.Enrollment		-
Microsoft.Graph.DeviceManagement.Functions		-
Microsoft.Graph.Devices.CloudPrint		-
Microsoft.Graph.Devices.CorporateManagement		-
Microsoft.Graph.Devices.ServiceAnnouncement		-
Microsoft.Graph.DirectoryObjects		-
Microsoft.Graph.Education		-
Microsoft.Graph.Files		-
Microsoft.Graph.Groups		-
Microsoft.Graph.Identity.DirectoryManagement		-
Microsoft.Graph.Identity.Governance		-
Microsoft.Graph.Identity.SignIns		-
Microsoft.Graph.Mail		-
Microsoft.Graph.Notes		-
Microsoft.Graph.People		-
Microsoft.Graph.PersonalContacts		-
Microsoft.Graph.Planner		-
Microsoft.Graph.Reports		-
Microsoft.Graph.SchemaExtensions		-
Microsoft.Graph.Search		-
Microsoft.Graph.Security		-
Microsoft.Graph.Sites		-
Microsoft.Graph.Teams		-
Microsoft.Graph.Users		-
Microsoft.Graph.Users.Actions		-
Microsoft.Graph.Users.Functions		-
Microsoft.Graph.Beta.Applications		-
Microsoft.Graph.Beta.Bookings		-
Microsoft.Graph.Beta.Calendar		-
Microsoft.Graph.Beta.ChangeNotifications		-
Microsoft.Graph.Beta.CloudCommunications		-
Microsoft.Graph.Beta.Compliance		-
Microsoft.Graph.Beta.CrossDeviceExperiences		-
Microsoft.Graph.Beta.DeviceManagement		-
Microsoft.Graph.Beta.DeviceManagement.Administration		-
Microsoft.Graph.Beta.DeviceManagement.Enrollment		-
Microsoft.Graph.Beta.DeviceManagement.Functions		-
Microsoft.Graph.Beta.Devices.CloudPrint		-
Microsoft.Graph.Beta.Devices.CorporateManagement		-
Microsoft.Graph.Beta.Devices.ServiceAnnouncement		-
Microsoft.Graph.Beta.DirectoryObjects		-
Microsoft.Graph.Beta.Education		-
Microsoft.Graph.Beta.Files		-
Microsoft.Graph.Beta.Financials		-
Microsoft.Graph.Beta.Groups		-
Microsoft.Graph.Beta.Identity.DirectoryManagement		-
Microsoft.Graph.Beta.Identity.Governance		-
Microsoft.Graph.Beta.Identity.SignIns		-
Microsoft.Graph.Beta.Mail		-
Microsoft.Graph.Beta.ManagedTenants		-
Microsoft.Graph.Beta.Migrations		-
Microsoft.Graph.Beta.Notes		-
Microsoft.Graph.Beta.People		-
Microsoft.Graph.Beta.PersonalContacts		-
Microsoft.Graph.Beta.Planner		-
Microsoft.Graph.Beta.Reports		-
Microsoft.Graph.Beta.SchemaExtensions		-
Microsoft.Graph.Beta.Search		-
Microsoft.Graph.Beta.Security		-
Microsoft.Graph.Beta.Sites		-
Microsoft.Graph.Beta.Teams		-
Microsoft.Graph.Beta.Users		-
Microsoft.Graph.Beta.Users.Actions		-
Microsoft.Graph.Beta.Users.Functions		-
Microsoft.Graph.Beta.WindowsUpdates		-

Microsoft Graph PowerShell module is published on PowerShell Gallery. Installing is as simple as:

Install-Module Microsoft.Graph

Run Install-Module with -AllowClobber and -Force parameters if you run into command name conflicts when upgrading to older versions of the module. This may be the case when upgrading from v1.x to v2.x:

Install-Module Microsoft.Graph -AllowClobber -Force

See Install the Microsoft Graph PowerShell Module guide for detailed installation instructions.

The module supports two main types of authentication:

Get access to Microsoft Graph resources on behalf of a user.

# Using interactive authentication.
Connect-MgGraph -Scopes "User.ReadBasic.All", "Application.ReadWrite.All"

Get access to Microsoft Graph resources using the identity on an app and not on behalf of a user.

# Using -CertificateThumbprint
Connect-MgGraph -ClientId "YOUR_APP_ID" -TenantId "YOUR_TENANT_ID" -CertificateThumbprint "YOUR_CERT_THUMBPRINT"

See Authentication for more information on the usage of Connect-MgGraph.

Get-MgUser -Top 10 -Property Id, DisplayName, BusinessPhones | Format-Table Id, DisplayName, BusinessPhones

$User = Get-MgUser -Filter "displayName eq 'Megan Bowen'"

New-MgApplication -DisplayName "ScriptedGraphPSApp" `
                  -SignInAudience "AzureADMyOrg" `
                  -Web @{ RedirectUris = "https://localhost"}

Disconnect-MgGraph

Install Microsoft.Graph.Beta module to commands that call Microsoft Graph Beta API endpoint.

Install-Module Microsoft.Graph.Beta
# Consume Microsoft Graph beta resources.
Connect-MgGraph
$Users = Get-MgBetaUser

The Microsoft Graph PowerShell SDK is scheduled to be updated during the fourth week of each month

The following breaking changes have been introduced between v1.x and v2.x:

• Dropped profile support.
• Dropped support for -ForceRefresh on Connect-MgGraph.
• Renamed beta command names from <Verb>-Mg<Noun> to <Verb>-MgBeta<Noun>.
• Renamed DeviceManagement.Enrolment module to DeviceManagement.Enrollment.
• Moved directory role and entitlement management commands from DeviceManagement.Enrollment to Identity.Governance module.
• Changed beta namespace from Microsoft.Graph.PowerShell.Models.<Entity> to Microsoft.Graph.Beta.PowerShell.Models.<Entity>.
• Changed -AccessToken type on Connect-MgGraph from String to SecureString.

See the v2 upgrade guide for more details.

When working with various operations in the Graph, you may encounter an error such as "Insufficient privileges to complete the operation." For example, this particular error can occur when using the New-MgApplication command if the appropriate permissions are not granted.

If permission-related errors occur and the signed-in user/app has been granted the appropriate permissions to perform the operation, you can explicitly fetch a new access token by running Disconnect-MgGraph, then Connect-MgGraph. This will trigger a refresh of the access token in your cache. Microsoft Authentication Library (MSAL) will only refresh access tokens in your cache if they have expired (usually an hour).

See Microsoft Graph API Permissions Reference for more details.

See our troubleshooting guide for a detailed view of how to troubleshoot common errors when using Microsoft Graph.

• Using the -Property {PropertyName} parameter will not select the property as the output of the command. All commands return CLR objects, and customers should pipe the command outputs to Format-Table or Select-Object to return individual properties.

• Customers upgrading from previous versions of the SDK may encounter auth prompts on every command call. If this happens, one can use the following steps to reset their token cache:

  • Use Disconnect-MgGraph to sign out of the current session.
  • Run Remove-Item "$env:USERPROFILE\.mg" -Recurse -Force to delete your token cache.
  • Run Connect-MgGraph to reconstruct a clean token cache.

If you find any bugs when using the Microsoft Graph PowerShell modules, please file an issue on our GitHub issues page.

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Copyright (c) Microsoft Corporation. All Rights Reserved. Licensed under the MIT license.