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:

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 parameter

Do I need to reconnect after an hour to get a new session?

Nope, it should automatically use the refresh token