The Microsoft Graph PowerShell SDK is a collection of PowerShell modules that contain cmdlets for calling Microsoft Graph.
The modules are now published on the PowerShell Gallery. Installing is as simple as:
Install-module Microsoft.Graph
There are a set of samples in the samples
folder to help getting started with the library. If you have an older version of these modules installed, there are uninstall instructions in the InstallModule script.
-
Download and install PowerShell Core.
-
Install AutoRest.
npm install -g "@autorest/autorest"
-
Create an Azure DevOps Artifacts Feed or host a local Nuget.Server, and register it as a local PowerShell repository using
Register-PSRepository
command. Once done, take note of theRepositoryName
andAPIKey
. You can always get the repository name by runningGet-PSRepository
. This will be used as a temporary repository to publish generated modules in order to specify them as dependencies forMicrosoft.Graph
roll-up module.N.B - Once we have a preview version of the modules in PowerShell Gallery, this step won't be needed.
-
Clone the msgraph-sdk-powershell repo locally.
git clone https://github.com/microsoftgraph/msgraph-sdk-powershell.git -b dev
-
Generate, pack and optionally publish
Microsoft.Graph.Authentication
module.. \msgraph-sdk-powershell\tools\GenerateAuthenticationModule.ps1 -RepositoryName {RepositoryName} -RepositoryApiKey {APIKey} -ModuleVersion {ModuleVersion} -Publish
-
Generate, pack and optionally publish Microsoft Graph service PowerShell modules by tags. For a complete list of tags, see OpenApiSplice.
Edit
.\config\ModulesMapping.jsonc
by adding key-value pairs of the tags you want to generate modules for. The key is the name of the module to be generated and the value is a regex expression that will be used to query OpenApiSplice for an OpenAPI document for your module.To generate v1.0 modules, run the following script:
. \msgraph-sdk-powershell\tools\GenerateModules.ps1 -RepositoryName {RepositoryName} -RepositoryApiKey {APIKey} -ModuleVersion {ModuleVersion} -Publish
To generate beta endpoint modules, add
-BetaGraphVersion
switch when runningGenerateModules.ps1
.This performs the following actions :
- Generates the modules specified in
.\config\ModulesMapping.jsonc
in.\msgraph-sdk-powershell\src\{GraphVersion}\{Module-Name}\{Module-Name}\
. - Adds appropriate dependencies to the generated modules.
- Packs and optionally publishes the modules to the specified repository as
.nupkg
files. The generatednupkg
can be found in.\msgraph-sdk-powershell\artifacts\{GraphVersion}\{Module-Name}\
.
- Generates the modules specified in
-
Generate, pack and optionally publish
Microsoft.Graph
roll-up module.. \msgraph-sdk-powershell\tools\GenerateRollUpModule.ps1 -RepositoryName {RepositoryName} -RepositoryApiKey {APIKey} -ModuleVersion {ModuleVersion} -Publish
To generate a roll-up module for Microsoft Graph beta modules, add
-BetaGraphVersion
switch when runningGenerateRollUpModule.ps1
.The above script generates a
Microsoft.Graph
module manifest with the generated Microsoft Graph service modules specified in.\config\ModulesMapping.jsonc
andMicrosoft.Graph.Authentication
module as its dependencies. -
Optionally, manually publish modules from an artifacts location.
. \msgraph-sdk-powershell\tools\PublishModule.ps1 -Modules "Graph", "Authentication", "Subscriptions", "Teams" -RepositoryName {RepositoryName} -RepositoryApiKey {APIKey} -ArtifactsLocation {ArtifactsLocation}
-ModuleVersion
: The version of the module to generate. This defaults to0.1.0
when not specified.-ModulePreviewNumber
: An optional preview number of the module(s) to generate. When not specified, the module is generated as a non preview module(s) of theModuleVersion
.-Publish
: An optional switch that publishes generated module(s) to the specifiedRepositoryName
. This used when module dependencies are not locally installed in your machine.-BetaGraphVersion
: A switch that indicates tells the generation scripts to generate beta modules of Microsoft Graph. If not specified, the generation scripts will generate v1.0 modules.
-
By default, the generated modules should already be installed on your PC in
%UserProfile%\Documents\PowerShell\Modules
as part of the generation process. If it's not present or you want to install the modules on another machine, then install them as such by specifying your repository name:Install-Module Microsoft.Graph -Repository {RepositoryName} # v1.0 modules or Install-Module Microsoft.Graph.Beta -Repository {RepositoryName} # beta modules
-
Authenticate to Microsoft Identity to get an access token to call Microsoft Graph modules.
-
Delegated access via Device Code Flow.
Connect-Graph -Scopes "User.Read.All"
-
App only access via Client Credential Flow with a certificate.
# Replace CN=DaemonConsoleCert with your certificate name. Connect-Graph -ClientId ClientId -TenantId TenantId -CertificateName "CN=DaemonConsoleCert"
-
-
Call
Get-User
command.# Authenticate for delegated access. Connect-Graph Get-User -Top 10 -Select Id, DisplayName, BusinessPhones | Format-Table Id, DisplayName, BusinessPhones
-
Call
Get-UserMessage
cmdlet.# Authenticate for app only access. Connect-Graph -ClientId ClientId -TenantId TenantId -CertificateName CertificateName Get-UserMessage -UserId UserId -Top 10 -Skip 10 -Select Id, Subject, CreatedDateTime | Format-Table CreatedDateTime, Subject, Id
-
Sign out of the current logged in context i.e. app only or delegated access.
Disconnect-Graph
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-Application
command if the appropriate permissions are not granted.
If permission related errors occur and the user you authenticated with in the popup has the appropriate permissions to peform the operation try these steps.
- You can try running
Disconnect-Graph
, thenConnect-Graph
. Then, run the code that encountered the permission issues to see if it works. - You can try running
Connect-Graph -ForceRefresh
. This will trigger a refresh of the access token in your cache. MSAL will only refresh the access token in your cache if it has expired (usually an hour), or if you explicitly refresh it via-ForceRefresh
. Then, run the code that encountered the permission issues to see if it works.