Using the Microsoft Graph SDK for PowerShell with Azure Automation

From Runbooks to Email

In a previous article about using Azure Automation accounts and runbooks with the Exchange Online management PowerShell module, in that article, I also explained how to use Graph API queries in a PowerShell script executed in a runbook. The natural follow-on question is to ask if the Microsoft Graph PowerShell SDK supports runbooks. I can report that the SDK can be used with Azure Automation using certificate-based authentication or managed identities. Of course, a simple statement can hide a bunch of complexity, so let’s explore the details.

As a practical example of what’s possible, in this article I convert the script to send email to new mailboxes described here to execute in a runbook.

Azure Automation Setup

As discussed in the previous article, we’ll use an Azure Automation account (tied to an Azure subscription) to run the script on a sandbox server. Azure Automation supports managed identities, and I’ll dive into that topic in a future article. For now, the tried and tested technique does the job.

Update: Azure Automation no longer supports Runbook accounts. Use a managed identity instead. See this article for more information. The principals explained here of loading modules into an automation account and assigning Graph permissions to automation accounts are still valid.

Importing Graph Modules

The RunAs account has a service principal and a certificate managed by Azure. These are the key components used for authentication. However, authenticating is just the start. To make the Microsoft Graph PowerShell SDK available to a runbook, we must import its modules into the automation account as shared resources.

You might notice that I used modules and not module. When you download the Microsoft Graph PowerShell SDK from the PowerShell gallery and install it on a workstation, you don’t get a single module. Instead, the SDK splits into many different modules, each taking care of a small part of the overall Graph landscape. When you import the SDK into an automation account, you must import the modules needed by a script. The first task is to check the documentation for the cmdlets you plan to use to discover what module each cmdlet is in.

For example, let’s say that your script uses the Get-MgOrganization cmdlet to return details of your tenant. Microsoft’s documentation tells us that the cmdlet belongs to the Microsoft.Graph.Identity.DirectoryManagement module (Figure 1).

In passing, let me say that the documentation for the SDK cmdlets is a horrible example of why artificial intelligence sometimes doesn’t work so well when used to create documentation based on source code. Improving the documentation would help people understand the SDK cmdlets better and encourage their use. For now, substantial interpretation and a great deal of patience is needed.

Loading SDK Modules into the Azure Automation Account

After checking the script to find all the SDK cmdlets, I ended up importing four modules (Figure 2):

• Microsoft.Graph.Authentication: to authenticate against the Graph.
• Microsoft.Graph.Users.Action: to send a message.
• Microsoft.Graph.Mail: to access mail messages.
• Microsoft.Graph.Identity.Management: to get organization details.

Assigning Graph Permissions

Loading the SDK modules to interact with the Graph starts us off: having the permissions to do so completes the circle. When you connect using the Connect-MgGraph cmdlet, the session you create can use certain Graph permissions. This is the session scope. In this case, the script needs to access a user’s mailbox to create a message before sending it to the message recipients, so the entity used for authentication must hold the Graph application permission necessary to perform these actions. The entity is the service principal for the RunAs account. Before the script can send email, an administrator must grant consent to allow the service principal to have the Mail.Send and Mail.ReadWrite permissions.

Assigning permissions to the service principal for the RunAs account is the same as assigning permissions to a registered app. Go to the Azure AD admin center, find the service principal in the set of registered apps, add the necessary permissions, and grant consent on behalf of the organization. You should end up with something like Figure 3. Two extra Graph permissions are present because I used this service principal in the previous article.

Be careful not to create service principals with too many Graph permissions. Like the service principal used for interactive sessions with the Microsoft Graph PowerShell SDK, it’s easy for a service principal to accumulate permissions over time if it’s used for multiple tasks. In production, consider using separate automation accounts for different jobs.

Amending PowerShell Code

We now have a RunAs account with the correct permissions and access to the required modules, so it’s time to write some code. A working script is available as a starting point, but it needs adjustment to work in a runbook. Here’s what I did:

First, I added a new authentication section to get the certificate thumbprint from the automation account. The certificate then authenticates the connection to the Microsoft Graph.

$Connection = Get-AutomationConnection -Name AzureRunAsConnection
# Get certificate from the automation account
$Certificate = Get-AutomationCertificate -Name AzureRunAsCertificate
# Connect to the Graph SDK endpoint using the automation account
Connect-MgGraph -ClientID $Connection.ApplicationId -TenantId $Connection.TenantId -CertificateThumbprint $Connection.CertificateThumbprint

Next, I retrieved the tenant service domain and use it together with and the same certificate thumbprint to connect to Exchange Online (to fetch the set of mailboxes added recently).

$Organization = Get-MgOrganization
$TenantName = $Organization.DisplayName
$TenantDomain = $Organization.Verifieddomains | ? {$_.IsInitial -eq $True} | Select -ExpandProperty Name
# Connect to Exchange Online
Connect-ExchangeOnline –CertificateThumbprint $Connection.CertificateThumbprint –AppId $Connection.ApplicationID –ShowBanner:$false –Organization $TenantDomain

Remember that the automation account needs some permissions to connect to Exchange Online. Those permissions are described in my previous article.

I then defined who the message is from (the mailbox I want to use). When I run the script interactively, I fetch this information from the account currently connected to PowerShell, but this doesn’t work for a RunAs account, so we need to define the SMTP address of the account to use in a variable.

$MsgFrom = "WelcomeNewUsers@Office365itpros.com"

My script attaches a welcome letter stored on a local drive. Obviously, a script running in a sandbox doesn’t have access to my local drive, so instead I download the welcome letter from a web site and store it in a local folder. The script then encodes the content to allow the attachment of the file to a message.

$WebAttachmentFile = "https://office365itpros.com/wp-content/uploads/2022/02/WelcomeToOffice365ITPros.docx"
New-Item -Path c:\TempForScriptxxx -ItemType directory -ErrorAction SilentlyContinue
$AttachmentFile = "c:\TempForScriptxxx\WelcomeNewEmployeeToOffice365itpros.docx"
Invoke-WebRequest -uri $WebAttachmentFile -OutFile $AttachmentFile
$Attachment = (Get-Item -Path $AttachmentFile).Name
$EncodedAttachmentFile = [Convert]::ToBase64String([IO.File]::ReadAllBytes($AttachmentFile))

Finally. I removed any messages sent to the screen using Write-Host. There’s no point in issuing these messages because there’s no screen for them to display on when code executes in a runbook.

The Messages Arrive

And that’s it. The process is not difficult once the preparatory work is done. The code runs because all the necessary modules are available in the account and the account has the correct Graph permissions, so mail flows into the mailboxes of new users (Figure 4).

You can download a copy of the complete script I used from GitHub.

Automation is Nice

The nice thing about using Azure Automation is that you can publish the script and then schedule it to run weekly to send welcome messages to users who joined during the preceding week. With a couple of clicks, new joiners receive waves of happiness. And the same technique of creating and sending email can be used to distribute information generated by many other jobs. Isn’t that a nice thing?