Graph PowerShell SDK – Part 1 of our Graph series

Users will encounter one or two hurdles when they start using Graph. Damian Scoles wrote three articles  provides help in three parts. Before the topics Teams and Exchange are covered, we will start with Graph SDK (Software Development Kit). 

A beginning

Where to start? As a long-time user of PowerShell (think Monad), this author finds Graph to be an interesting mix of security, mystery and power wrapped into one. From a security perspective, the least privileged model shows that Graph has very granular permissions that can be used to realistically keep a tighter running ship. On the other hand, those used to the less granular and more RBAC permission model may find this granularity daunting. Then there is the distinct lack of a completed Help system for all of the cmdlets available for Graph. Sometimes it can be either a treasure hunt or just sheer luck that a workable one-liner can be constructed. Then once we get past that we see the power that is available to us in the form of security, cmdlet availability and the tasks that can be performed from one module. In this article, we will explore Graph, the ways we can connect via PowerShell and guide you on how to use it in your test and production tenants (hopefully you have a test tenant?).

Connecting to Graph

Basic

To connect to the Graph API, we use one of these cmdlets:

Connect-MgGraph

Or

Connect-Graph

Realistically, there is no difference between the two, however Connect-MgGraph is a cmdlet, whereas Connect-Graph is an alias, that points to Connect-MgGraph.

Remember that Graph uses a least permission model and thus when we connect with no other parameters, no permissions or roles are assigned. Base permissions will not allow us to do much other than perhaps query some basic resources and objects in Graph. To get more out of Graph, we need the correct permissions. Let's walk through how to do that next.

Scoped permissions

Here is where connecting to graph can get complicated. Scoping permissions for your task may require some work and experimentation as a task may require more or less permissions that were initially provided. If connected via an Azure application, using Certificate Based Authentication, predefined permissions may also need to be adjusted. Let's walk through a sample scenario.

Finding permissions

For our scenario, we would like to get a list of applications that are registered in Azure for a tenant. The cmdlet to be used is:  

Find-MgGraphCommand Get-MgApplication 

Output

Output from the Find-MgGraphCommand cmdlet which provides us a connection URl as well as permissions required to run the cmdlet.

There is a column called permissions, which is a property of this cmdlet that stores the required permissions. Let's pull the full list of permissions for this cmdlet: 

Find-MgGraphCommand (Get-MgApplication).Permissions 

Permissions

Note that there are two sets of permissions and are based on the different URIs used for connection. If we want to list applications, we only need something like the Application.Read.All permissions. How do we use this?

Using permissions

Once we know what permissions are required, we can specify this on a new connection to Graph:

Connect-MgGraph -Scopes Application.Read.All

If this is the first time using this permission, a Permissions requested pop-up will ask to approve this change:

Make sure to read this pop-up to fully understand what permissions you are granting

To verify it was successful, we can run this cmdlet to pull our permissions:

(Get-MgContext).scopes

Our added permissions in the yellow rectangle 

Missing permissions?

If the correct permissions are not assigned, then we would get an error like this:

Notice the permissions missing are listed in the yellow bracket

Other connection methods

• Device code: Requires the use of a device to authenticate a PowerShell connection.
• Access token: Use your access token to access Graph, which can be found, for example, with Graph Explorer under the 'Access Token' tab.
• Azure app: A registered app in Azure can be used to grant permissions to your Graph PowerShell connections.
• Certificate based: Using an Azure App, we assigned a self-signed certificate to control access – see our blog article here for an example with Exchange Online. (How to connect to Exchange Online with certificate based authentication (CBA))
• Managed ID: Think Azure Automation using an Azure Managed Identity for access to Graph.

Executing cmdlets

Now that we are connected to Graph PowerShell, we have additional options for executing cmdlets in the shell:

• Graph PowerShell cmdlets: PowerShell cmdlets are wrappers for the underlying connections to the Graph API. Familiar to those who use other PowerShell modules for other Microsoft 365 workloads.
• Invoke‑RestMethod: Using this method directly connects to the various connection points in the Graph API.
  Makes sense? Well, let's make sure.

Graph PowerShell

Examples of this are:

Get-MgReportMailboxUsageDetail

Get-MgReportMailboxUsageMailboxCount

Get-MgReportMailboxUsageQuotaStatusMailboxCount

Get-MgReportMailboxUsageStorage 

Running any of these will generate output with the proper parameters or switches:

Get-MgReportMailboxUsageStorage -period 'D7' -OutFile c:\data\test.txt

Output for mailbox usage is placed in a text file for analysis/review.

Invoke-RestMethod

Like PowerShell cmdlets, these cmdlets are run after connecting to Microsoft Graph.

$Results = (Invoke-MGGraphRequest -Method get -Uri 'https://graph.microsoft.com/v1.0/applications/?$select=id,displayName' -OutputType PSObject -Headers @{'ConsistencyLevel' = 'eventual' }).Value

Notice the URL used for the connection, pointing to the Graph API URI for Applications. We also have a 'select' action and we are pulling the ID and Display Names for apps:  

• https://graph.microsoft.com/v1.0/applications/?$select=id,displayName 

When executed, we have this for output:

List of applications in a tenant with the ID and DisplayName properties as selected

URLs and Graph Explorer

A common question that occurs at this point is how do I find the right URL to use if I am new to using the Invoke‑RestMethod? We can use Microsoft Graph Explorer to discover and understand what can be retrieved. Make sure to log into your tenant first:

Sign into a tenant to explore Graph URI endpoints

Once logged in, we see the base URL at the top – https://graph.microsoft.com/v1.0/me – which is pointed to the logged in user's personal account. On the left we have a window that we can choose various endpoints to query.

On the left, in the red rectangle, we have some sample queries we can run to help learn the basics

If we were to select one of these options under Applications, we can then click on the 'Run query' button to execute this query. The URL provided for this query is:

• https://graph.microsoft.com/v1.0/applications?$count=true

which is similar to the query we ran before. Now, we could also get a list of groups in the tenant as well by connecting to this URL:

• https://graph.microsoft.com/v1.0/groups

GET, POST, UPDATE, DELETE

These four actions describe what action we would like to take when we connect to the various connection points (URLs). A quick summary for reference:

• GET: Like PowerShell Get-, we want to list objects in Graph.
• POST: Create a new object, so similar to a PowerShell New verb-cmdlet.
• UPDATE: Make a change, similarly to a Set-cmdlet, to an object in Graph.
• DELETE: This action would remove an object from Graph, which could be equivalent to Remove- in PowerShell.

Considerations for Graph PowerShell

When using Graph PowerShell, it is good to know about possible limitations or just generally quirks/features compared to other PowerShell modules. In this section we will briefly explore these.

• Pagination: This is one item that is not necessarily limited to Graph, but it is something to be aware of. When a cmdlet is run, not all data will be returned at once. Instead, only one section (a page) is shown in the output even if more results could be returned. Pages are returned as a matter of efficiency and to reduce resource load in the service. To get more results we can specify a page size (varies based on cmdlet) and what page to show data from. Some cmdlets have a -All switch to show all results. If a query has 11,000 results and the page size is 1,000, then there are eleven pages (0 – 10) to reference. This will require some extra code but should be easy to handle.
• Permissions: As discussed before, Graph PowerShell is a least privilege model which is unlike most other PowerShell modules where a role is assigned, and we are able to execute PowerShell cmdlets based on that access. In Graph we need to assign specific rights and then execute our cmdlets.
• Updates: The Graph PowerShell module is being constantly updated and changed. Make sure to keep your local module up to date to get the most out of it.
• Filters: Use filters for quicker results and skip using Where-Object if possible.
• Module consolidation: Microsoft recently deprecated MSOL and Azure AD modules and Graph is taking over those functions. This may lead to other modules also being deprecated and assimilated into Graph, so be on the lookout for that.
• Object GUIDs: Graph tends to reference objects by their GUID and not so much by their Name or other attributes. Although a UPN will also work, GUIDs tend to be the way to go.

What's next?

Now that we've gone through and reviewed the foundation for Graph PowerShell, where should we explore next? Well, in this series of blog articles, we will cover what we can use Graph for in terms of different workloads in Microsoft 365. First, we will start with Exchange and then move on to Teams. The focus for the articles will be on how practical it is to use Graph PowerShell to manage these workloads, what tasks can be performed in Graph and if the original module is still needed for efficient management. The end goal is to provide practical, useful advice for which method to use for either workload. Hopefully this will help administrators who may be struggling with the deprecation of the MSOL and Azure AD modules. Thanks again for reading this article.

Related links

• ScriptRunner Graph ActionPacks
• Microsoft Graph Explorer 
• Are you ready for Destination Graph? – Deprecated by March 2024 (ScriptRunner | Blog)
• Part 2, Graph und Exchange – Part 3, Graph and Teams (ScriptRunner | Blog)
• Try out ScriptRunner here
• ScriptRunner: Book a demo with our product experts