Using the Graph API Powershell SDK

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

Installing the SDK

As per the GitHub repo instructions, this module can be installed by adding the PowerShell repository in to your local machine and installing the module.

Add Repository to your machine:

Register-PSRepository -Name GraphPowerShell -SourceLocation https://graphpowershellrepository.azurewebsites.net/nuget

At some stage this module will be published within the PowerShell Gallery so this will no longer be required.

Note: If you try to install this module on Windows PowerShell with the Microsoft Teams module already installed, it will fail as there are clashes with cmd-lets such as Get-Team. There are plans to change this behaviour, but for now use PowerShell Core if you can

Install Graph API (Beta) SDK:

Install-Module Microsoft.Graph.Beta -Repository GraphPowerShell

Note: Currently, only the Graph API BETA module is available in the repository

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-User
Get Group Get-Group
Create User New-User

Example: Get User - Get a particular user

Get-User -UserId "<User ID/UPN>" | Select DisplayName, UsageLocation, JobTitle

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-Group | Select DisplayName

Example: Get Group - Get all groups

New-User -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


See also

comments powered by Disqus