Calling the Microsoft Graph with PnP PowerShell

In researching options for an upcoming project, I had a scenario in which I needed to use PnP PowerShell to connect to SharePoint using Azure AD App-Only with a certificate as well and make additional calls to the Microsoft Graph to determine if an Office 365 group is a Team or associated with a Yammer community, as an example - In this post, I walk you through the process of setting this up.

There is an existing PnP cmdlet called “Get-PnPUnifiedGroup” with the “-IncludeHasTeam” parameters that can also do this. However, I found this cmdlet to be relatively slow to run and just wanted to make a quick check - without having to load all the other group information. Finally, to provide some flexibility to explore the different areas of Graph API as part of my continuous personal development.

Setting up the App

Setting up the app requires the Global Administrator Role for the API permissions to have consented by the admin. You will also need to have the PnP PowerShell library installed for this example; we will be using version 1.5.0 or above to set this up.

For this process, we will use the PnP cmdlet “Register-PnPAzureADApp” to register the App in Azure AD, create the self-signed certificate either download as a file or add to your local certificate store - which is what we will do for this example. Finally, this will open the consent screen to grant the API permissions.

Register-PnPAzureADApp -ApplicationName CaPa.Reporting `
    -Tenant "tenant.co.uk" -Store CurrentUser -ValidYears 2 `
    -CertificatePassword (ConvertTo-SecureString -String "password" `
    -AsPlainText -Force)

# Output Example from PS:
#
#   AzureAppId                           Certificate Thumbprint
#   ----------                           ----------------------
#   c53eb8da-8bdf-44f9-8718-1fb1bbbbbb EC1E61510AEC35624AF78FEA763D00000000
#

# Example Test Connection 

Connect-PnPOnline -ClientId c53eb8da-8bdf-44f9-8718-1fb1bbbbbb `
        -Thumbprint EC1E61510AEC35624AF78FEA763D00000000 `
        -Tenant "tenant.co.uk" -Url "https://tenant.sharepoint.com"

Get-PnPSite

After this has been set up, please record the Azure App ID, and certificate thumbprint for later use.

By default, the app uses the following permissions:

• Microsoft Graph
  • Group.ReadWrite.All
  • User.Read.All
• SharePoint
  • Sites.FullControl.All
  • User.Read.All

The app is set up to allow App-only connections to the service via a certificate that was generated along with the App registration process. Keep these outputs in a secure location along with your password - at this point, this is a highly privileged app.

Exploring the Graph

The Microsoft Graph has an Explorer and documentation for the APIs you want to consume; this allows you to explore some of the API samples to see how to interact with them and understand the replies. Different APIs have different permission requirements; you may need to grant more permissions to the app to allow access to the resource.

You have the option to connect the Graph Explorer to your tenant and make calls against your live data - which can help you understand and provides context between the data you have in your tenant relates to the responses you get back.

Making a call to the Graph in PowerShell

For the example script, I use a combination of PnP PowerShell and calls to the Graph APIs using the Invoke-RestMethod cmdlet.

So let’s see this in action, using the Azure AD app, set up earlier, connecting the Graph to retrieve a list of groups that are associated with Microsoft Teams.

Connect-PnPOnline -ClientId c53eb8da-8bdf-44f9-8718-1fb1bbbbbb `
        -Thumbprint EC1E61510AEC35624AF78FEA763D00000000 `
        -Tenant "tenant.co.uk" -Url "https://tenant.sharepoint.com"

$token = Get-PnPGraphAccessToken

# Create header with the access token
$header = @{ Authorization = "Bearer $($token)" }

#v1.0/Beta
$uri = 'https://graph.microsoft.com/Beta/groups' + `
       '?$filter=resourceProvisioningOptions/Any(x:x eq ''Team'')' +
       '&select=id,displayName'

# Make a simple rest call
$response = Invoke-RestMethod -Uri $uri -Headers $header `
    -Method Get -ContentType "application/json"

# Lets see the result
$response.Value

The above example is a simple GET query to retrieve a list of groups only if they are part of a team ($filter) and choose to return ($select) the ID and DisplayName. Note this is using the beta endpoint, the filter query of this type is not supported yet in V1.0

From the example above, this shows the results of the sample script, retrieving data from the Graph, using this method, you able to explore the other API’s, for me, I use the Graph Explorer first to understand the query and results, then port over to PowerShell to parse the results as required.

Resources and references

There are several resources I used to understand the calls and support my learning of this approach:

• Microsoft Graph Explorer
• Register-PnPAzureADApp | Microsoft Docs
• Using the Microsoft Graph API with PowerShell | Adam The Automator
• Microsoft identity platform and the OAuth 2.0 client credentials flow

Update: This blog has been updated with the new cmdlets used in PnP PowerShell. For further information about updating cmdlets please visit: Upgrading from the Legacy version of PnP PowerShell)

Enjoy! If you would like to know more or have feedback, feel free to post in the comments :-)