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
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 |
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 "joe.bloggs@domain.com"
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.
About the Author:
Hi – I’m Lee.
I’m a Microsoft MVP (Office Development) and Solution Architect for Symity based in Birmingham, UK. I predominantly work with Microsoft Teams but also work with other technologies such as Azure, PowerShell, Power Platform, and Microsoft 365.
You can follow me on Twitter at @lee_ford
Reference:
Ford, L. (2019). Using the Graph API Powershell SDK. Available at: https://www.lee-ford.co.uk/graph-api-powershell-sdk/ [Accessed: 3rd February 2020].
