PowerShell – Microsoft Graph API

Alex Ø. T. Hansen

11/07/2018

PowerShell – Microsoft Graph API

Need to connect to Microsoft Graph with PowerShell? The following PowerShell script does just that (pretty easily)!

So what is Microsoft Graph API?

“Microsoft Graph is a Microsoft developer platform that connects multiple services and devices. Initially released 2015, the Microsoft Graph builds on Office 365 APIs and allows developers to integrate their services with Microsoft products, including Windows, Office 365, and Azure. At its Build 2017 conference, Microsoft announced it would use the Microsoft Graph to bring new functionality and connectivity between Windows and other OS platforms, including Android and iOS.” –Wikipedia

The following script have a function called “Get-GraphAPIAccessToken” (line 127 in the code below) which have two optional options available.

Credential
- If you don’t want to get an login prompt, when connecting to the API. Then use:
  -Credential (Create-PSCredential -Username “admin@contoso.onmicrosoft.com” -Password “AdminPasswordHere”)
ClientID
- If you need to use a registered application in Azure AD, specify the application id. Otherwise it will use a well-known value that are registered with Azure AD. An example would be:
  -ClientID 3b7e46ca-4495-410f-9691-f90793f0f666

There are some requirements before you can run the code, which is:

You need an valid internet connection (duuuh?!).
The script leverages AzureRM and the script will try to install it, but if it fails you can use “Install-Module AzureRM -SkipPublisherCheck -AllowClobber -Force -Confirm:$false;” to install it.

#Requires -Version 3.0
<#

    .SYNOPSIS
    Connect to Microsoft Graph API.

    .DESCRIPTION
    Get an access token from Microsoft Graph API.

    .PARAMETER

    .EXAMPLE

    .NOTES
    Author: Alex Ø. T. Hansen
    Date: 11-07-2018
    Last Updated: 11-07-2018

#>

################################################
<# Function - Start #>

#Create credentials.
Function Create-PSCredential
{
    [cmdletbinding()]	
		
    Param
    (
        [Parameter(Mandatory=$true, HelpMessage="Please provide a valid username, example 'user@contoso.onmicrosoft.com'.")]$Username,
        [Parameter(Mandatory=$true, HelpMessage="Please provide a valid password, example 'MyPassw0rd!'.")]$Password
    )

    #Convert the password to a secure string.
    $SecurePassword = $Password | ConvertTo-SecureString -AsPlainText -Force;

    #Convert $Username and $SecurePassword to a credential object.
    $Credential = New-Object "Microsoft.IdentityModel.Clients.ActiveDirectory.UserCredential" -ArgumentList $Username,$SecurePassword

    #Return the credential object.
    Return $Credential;
}

#Get Microsoft Graph API access token.
Function Get-GraphAPIAccessToken
{
    [cmdletbinding()]

    Param
    (        
        [Parameter(Mandatory=$false)][PSTypeName('Microsoft.IdentityModel.Clients.ActiveDirectory.UserCredential')]$Credential,
        [Parameter(Mandatory=$false)][string]$ClientID = "1950a258-227b-4e31-a9cf-717495945fc2",
        [Parameter(Mandatory=$true)][string]$RedirectURI,
        [Parameter(Mandatory=$true)][string]$ResourceURI,
        [Parameter(Mandatory=$true)][string]$Authority
    )

    #Retrieves authentication tokens from services and gets address of the authority to issue token.
    $AuthenticationContext = New-Object "Microsoft.IdentityModel.Clients.ActiveDirectory.AuthenticationContext" -ArgumentList $Authority;

    #If the credential is set.
    If($Credential)
    {
        #Get token with username and password in $Credential.
        $AuthenticationResult = $AuthenticationContext.AcquireToken($ResourceURI, $ClientID, $Credential);
    }
    Else 
    {     
        #Prompt user for credentials.
        $AuthenticationResult = $AuthenticationContext.AcquireToken($ResourceURI, $ClientID, $RedirectURI, [Microsoft.IdentityModel.Clients.ActiveDirectory.PromptBehavior]::Always)
    } 
    
    #Return the token.
    Return $AuthenticationResult.AccessToken;
}

#Check if the module is installed.
Function Check-Module
{
    [cmdletbinding()]

    Param
    (        
        [Parameter(Mandatory=$true)][string]$Name
    )

    #If the module exist.
    If(Get-Module -ListAvailable -Name $Name)
    {
        Return $true;
    }
    Else
    {
        Return $false;
    }
}

<# Functions - End #>
################################################
<# Input - Start #>

#URI.
$RedirectURI = "urn:ietf:wg:oauth:2.0:oob";
$ResourceURI = "https://graph.microsoft.com";
$Authority = "https://login.microsoftonline.com/common";

<# Input - End #>
################################################
<# Main - Start #>

#If the module AzureRM isn't installed.
If(!(Check-Module -Name AzureRM))
{
    Write-Output "Module: Installing 'AzureRM'";

    #Install the module.
    Install-Module AzureRM -SkipPublisherCheck -AllowClobber -Force -Confirm:$false;
}
Else
{
    Write-Output "Module: 'AzureRM' already installed.";
}

#Get access token.
Write-Output "Token: Getting Microsoft Graph API access token.";
$AccessToken = Get-GraphAPIAccessToken -RedirectURI $RedirectURI -ResourceURI $ResourceURI -Authority $Authority;

<# Main - End #>
################################################

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

#Requires -Version 3.0

.SYNOPSIS

Connect to Microsoft Graph API.

.DESCRIPTION

Get an access token from Microsoft Graph API.

.PARAMETER

.EXAMPLE

.NOTES

Author: Alex Ø. T. Hansen

Date: 11-07-2018

Last Updated: 11-07-2018

################################################

<# Function - Start #>

#Create credentials.

Function Create-PSCredential

{

[cmdletbinding()]

Param

(

[Parameter(Mandatory=$true, HelpMessage="Please provide a valid username, example 'user@contoso.onmicrosoft.com'.")]$Username,

[Parameter(Mandatory=$true, HelpMessage="Please provide a valid password, example 'MyPassw0rd!'.")]$Password

)

#Convert the password to a secure string.

$SecurePassword = $Password | ConvertTo-SecureString -AsPlainText -Force;

#Convert $Username and $SecurePassword to a credential object.

$Credential = New-Object "Microsoft.IdentityModel.Clients.ActiveDirectory.UserCredential" -ArgumentList $Username,$SecurePassword

#Return the credential object.

Return $Credential;

}

#Get Microsoft Graph API access token.

Function Get-GraphAPIAccessToken

{

[cmdletbinding()]

Param

(

[Parameter(Mandatory=$false)][PSTypeName('Microsoft.IdentityModel.Clients.ActiveDirectory.UserCredential')]$Credential,

[Parameter(Mandatory=$false)][string]$ClientID = "1950a258-227b-4e31-a9cf-717495945fc2",

[Parameter(Mandatory=$true)][string]$RedirectURI,

[Parameter(Mandatory=$true)][string]$ResourceURI,

[Parameter(Mandatory=$true)][string]$Authority

)

#Retrieves authentication tokens from services and gets address of the authority to issue token.

$AuthenticationContext = New-Object "Microsoft.IdentityModel.Clients.ActiveDirectory.AuthenticationContext" -ArgumentList $Authority;

#If the credential is set.

If($Credential)

{

#Get token with username and password in $Credential.

$AuthenticationResult = $AuthenticationContext.AcquireToken($ResourceURI, $ClientID, $Credential);

}

Else

{

#Prompt user for credentials.

$AuthenticationResult = $AuthenticationContext.AcquireToken($ResourceURI, $ClientID, $RedirectURI, [Microsoft.IdentityModel.Clients.ActiveDirectory.PromptBehavior]::Always)

}

#Return the token.

Return $AuthenticationResult.AccessToken;

}

#Check if the module is installed.

Function Check-Module

{

[cmdletbinding()]

Param

(

[Parameter(Mandatory=$true)][string]$Name

)

#If the module exist.

If(Get-Module -ListAvailable -Name $Name)

{

Return $true;

}

Else

{

Return $false;

}

<# Functions - End #>

################################################

<# Input - Start #>

#URI.

$RedirectURI = "urn:ietf:wg:oauth:2.0:oob";

$ResourceURI = "https://graph.microsoft.com";

$Authority = "https://login.microsoftonline.com/common";

<# Input - End #>

################################################

<# Main - Start #>

#If the module AzureRM isn't installed.

If(!(Check-Module -Name AzureRM))

{

Write-Output "Module: Installing 'AzureRM'";

#Install the module.

Install-Module AzureRM -SkipPublisherCheck -AllowClobber -Force -Confirm:$false;

}

Else

{

Write-Output "Module: 'AzureRM' already installed.";

}

#Get access token.

Write-Output "Token: Getting Microsoft Graph API access token.";

$AccessToken = Get-GraphAPIAccessToken -RedirectURI $RedirectURI -ResourceURI $ResourceURI -Authority $Authority;

<# Main - End #>

################################################

When you have an access token, you can use the following example which gets the current user profile details:

$ApiUrl = "https://graph.microsoft.com/v1.0/me";
$Response = (Invoke-RestMethod -Headers @{Authorization = "Bearer $AccessToken"} -Uri $ApiUrl -Method Get);

#Show reponse.
Return ($Response);

$ApiUrl = "https://graph.microsoft.com/v1.0/me";

$Response = (Invoke-RestMethod -Headers @{Authorization = "Bearer $AccessToken"} -Uri $ApiUrl -Method Get);

#Show reponse.

Return ($Response);

Get the Azure AD users:

$ApiUrl = "https://graph.microsoft.com/v1.0/users"
$Users = Invoke-RestMethod -Headers @{Authorization = "Bearer $AccessToken"} -Uri $ApiUrl -Method Get

#Show reponse.
Return ($Users).Value;

$ApiUrl = "https://graph.microsoft.com/v1.0/users"

$Users = Invoke-RestMethod -Headers @{Authorization = "Bearer $AccessToken"} -Uri $ApiUrl -Method Get

#Show reponse.

Return ($Users).Value;

Send an e-mail (need an Exchange license on the user):

$Recipient = "xyz@contoso.com";

$Body = @"
{
    "message" : {
       "subject": "E-mail through API",
       "body" : {
           "contentType": "Text",
           "content": "Pretty cool stuff, right?!"
           },
      "toRecipients": [
       {
       "emailAddress" : {
           "address" : "$Recipient"
           }
       }
       ]
    }
}
"@;

$ApiUrl = "https://graph.microsoft.com/v1.0/me/sendMail";
Invoke-RestMethod -Headers @{Authorization = "Bearer $AccessToken"} -Uri $ApiUrl -Method Post -Body $Body -ContentType application/json;

$Recipient = "xyz@contoso.com";

$Body = @"

{

"message" : {

"subject": "E-mail through API",

"body" : {

"contentType": "Text",

"content": "Pretty cool stuff, right?!"

"toRecipients": [

{

"emailAddress" : {

"address" : "$Recipient"

}

]

}

"@;

$ApiUrl = "https://graph.microsoft.com/v1.0/me/sendMail";

Invoke-RestMethod -Headers @{Authorization = "Bearer $AccessToken"} -Uri $ApiUrl -Method Post -Body $Body -ContentType application/json;

For more usage examples, Microsoft have create an repository on GitHub.

About Alex Ø. T. Hansen

Experienced advanced operations engineer with a demonstrated history of working in the information technology and services industry. Skilled in Windows Server, Azure, Ethical Hacking, Office 365, Exchange, Jenkins, SCCM, Octopus Deploy and PowerShell to name a few. Strong engineering professional with a big passion for knowledge.

4 Comments

Michael

31/01/2019 at 08:18

Hi Alex

Thanks for the very helpful post. Do you know if it is possible to send and get emailmessages without registering an application?

I can get messages in the graph explorer but not in my script.

1. Alex Ø. T. Hansen
  
  05/02/2019 at 15:54
  
  Your welcome 🙂
  I don’t think so currently.
  
Tim

19/03/2019 at 08:41

Does this script work with PowerShell 6.1.3?

1. Alex Ø. T. Hansen
  
  27/03/2019 at 12:43
  
  Should do, try it and report back?

PowerShell – Microsoft Graph API

4 Comments

Leave a Reply Cancel reply