Using the Graph API Powershell SDK
Updated: January 30, 2020
Introduction
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 Install-Module Microsoft.Graph
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 |
|---|---|
| Get User | Get-MgUser |
| Get Group | Get-MgGroup |
| Create User | New-MgUser |
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
Get-MgGroup
Example: New User - Create a user
New-MgUser -DisplayName "Joe Bloggs" -AccountEnabled -PasswordProfilePassword "Passw0rd123!" -MailNickname "Joe.Bloggs" -UserPrincipalName "[email protected]"
FAQ
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
