Updated: January 30, 2020
For a while, when using Graph API and PowerShell I have been using my own implementations of communicating with Graph API as outlined in the following posts:
- Getting started with Microsoft Graph and PowerShell
- Authenticating with Graph API Using a Device Code
However, at Ignite 2019, it was announced there is a Graph API PowerShell SDK in the works. Even better, its available on GitHub today! For a heavy PowerShell user like me, this is great news.
Some of the key benefits of the SDK are:
- Supports PowerShell 5.1+ (Windows and Core)
- No requirement to create an Azure AD Application, the SDK will use it’s own baked-in application (once permissions are granted to your tenant, you can use it again on multuple scripts)
- Supports device code auth, so not reliant on Windows Forms or WPF to display sign-in/MFA prompts
- It uses AutoRest to ensure any new additions to Graph API are automatically provisioned in to the module
- Has built in authentication methods such as refreshing OAuth tokens automatically etc.
In this post I am going to walk you through obtaining the SDK/Module and how to use it.
Note: This SDK is in APLHA, so there will be bugs or features you expect to see missing. It is being actively worked on so bear that in mind
I have created a video which covers most of the below in video form:
Installing the SDK
When the SDK initially launched it was published at GitHub and required you to install it from a temporary repository. With release 0.1.0 it is now part of the PowerShell Gallery, so you can simply run
If you previously installed this SDK from the temporary repository, you need to un-install this module first by running the following (taken from here):
# Uninstalling the old preview version, before installing the new # Remove the main meta module Uninstall-Module Microsoft.Graph.Beta # Remove all the dependent modules Get-InstalledModule Microsoft.Graph.Beta.* | uninstall-module # Update the authentication module from 0.1.4 to 0.1.5 Install-Module Microsoft.Graph.Authentication -Repository PSGallery -force
Note: Currently, only Graph Beta APIs are used in the module
Using the SDK
Connecting to Graph
This is very simple, you just need to run Connect-Graph with the scopes (permissions) you require separated by a comma:
Connect-Graph -Scopes "User.Read.All", "Group.Read.All"
If it is the first time you are requesting these permissions with the SDK in your tenant, you will get prompted to grant consent:
With the code provided go to the page https://microsoft.com/devicelogin and enter the code, followed by signing in
Note: If you need to revoke or review permissions, these can be found under Enterprise Applications in Azure AD:
Running a command
Once connected, to run a command that matches a Graph API call, for example:
|Graph API Action||SDK cmd-let|
Example: Get User - Get a particular user
Get-MgUser -UserId "<User ID/UPN>"
Note: In some cases when retrieving data, you will want to format a list or select the properties you require otherwise all properties are returned in a table, which isn’t always useful
Example: Get Group - Get all groups
Example: New User - Create a user
New-MgUser -DisplayName "Joe Bloggs" -AccountEnabled -PasswordProfilePassword "Passw0rd123!" -MailNickname "Joe.Bloggs" -UserPrincipalName "[email protected]"
This SDK is still very early, so likely to change. As it changes, I hope to keep this article and FAQ up-to-date.
I need additional permissions after connection do I need to disconnect to and reconnect?
In my experience, you are able to re-run Connect-Graph with the new permissions added to the existing scope.
Does this support pagination automatically?
Not currently, no. One possible workaround is to run a command with a -Top
Do I need to reconnect after an hour to get a new session?
Nope, it should automatically use the refresh token