Microsoft.Graph.API module for PowerShell

Microsoft.Graph.API module

WARNING: The module is still under construction. Please leave feedback @ Github or in a comment below the post.

Microsoft Graph REST API is much quicker than a standard module. Especially for bulk changes and reports, but you can also use it to see the properties of a user.

There are several modules available that will get in to the Microsoft Graph REST API, but almost all of these have each (Report) query custom made in a cmdlet.

With the module I created I wanted to create cmdlets where everything is the same except for the URL you’re querying to.

As soon as Microsoft came out with an API we started using this for bulk updates, or getting reports, but every time I had to use it, I’d just copy the function from a different script, made some updates and used it again. The biggest problem I had with this was that every function I used in scheduled scripts overtime was different.

I’ve added the functions into a module including login cmdlets to keep a session open with the API, so I can continue my work without constantly having to log back in after the oauth token expired.

Below you can read more about the cmdlets in the module. I will soon update Github.


Feedback

This is the first module I published. I’m looking for as much feedback as possible. Not only for the module specific, but also for my own development.

So please do not withhold critical feedback.


More about Microsoft Graph and PowerShell.

I am working on new blog posts related to Microsoft Graph with PowerShell. For more about this, it is best to read the blog: A Summary about Microsft Graph and PowerShell.

If you want to know how to start with Microsoft Grah REST API, please go to this blog post: How to start with Microsoft Graph reports in PowerShell.


Microsoft.Graph.API Cmdlets

Below I explain per cmdlet what it does and the prepared work that is needed before you can run the cmdlet this is including examples.


Connect-MSGraphCertificate

Logging in with a Certificate is safer than a ClientSecret.

With Connect-MSGraphCertificate you can log in to the Microsoft Graph API with a certificate.
You need to provide the ApplicationID, TenantID (Or Tenantdomain) and thumbprint. You can do that by using parameter -Thumbprint. It will pre-check if the thumbprint is correct and if the certificate is found on the device you’re calling Connect-MSGraphCertificate from.

You can create a custom Self Signed Certificate with this script.

It will use function Get-MSGraphOauthToken in the background to log on Microsoft Graph API.

With -Verbose you will see more logging and the steps it will go through to connect to Microsoft Graph API.


Connect-MSGraphCertificate Example

$params = @{
    ApplicationID = 'XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
    Thumbprint    = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
    TenantID      = 'XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
}
Connect-MSGraphCertificate @params -Verbose

Connect-MSGraphAppSecret

Logging in with a Certificate is safer than an AppSecret.

With Connect-MSGraphCertificate you can log in to the Microsoft Graph API with a certificate.
You need to provide the ApplicationID, TenantID (Or Tenantdomain) and ClientSecret. You can add these as a parameter: -ApplicationID etc..

It will use function Get-MSGraphOauthToken in the background to log on Microsoft Graph API.

With -Verbose you will see more logging and the steps it will go through to connect to Microsoft Graph API.


Connect-MSGraphAppSecret Example

$params = @{
    ApplicationID = 'XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
    ClientSecret  = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
    TenantID      = 'XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
}
Connect-MSGraphCertificate @params -Verbose

Output:

You successfully logged in with a Certificate. We will keep you logged in until you close your Session.

New-MSGraphGetRequest

Cmdlet New-MSGraphGetRequest is used to make ‘Get’ requests to Microsoft Graph API. For example when you want to get all users.

In the backend, this cmdlet checks if your oauthtoken is still active and if not, it logs in again with the last used data to make sure you don’t have to log in again. This all happens in the backend and you only see this when you use -verbose.


New-MSGraphGetRequest Example

New-MSGraphGETRequest -URL 'https://graph.microsoft.com/v1.0/users' -Verbose

Output:

businessPhones    : {}
displayName       : Test User Post MSGraph
givenName         :
jobTitle          :
mail              :
mobilePhone       :
officeLocation    :
preferredLanguage :
surname           : 
userPrincipalName : [email protected]
id                : eeddb434-3288-4862-aa6e-781430aea0dd

New-MSGraphPreGetRequest

The New-MSGraphPreGetRequest cmdlet is a wrapper around New-MSGraphGetRequest with predefined reports.

You only have to select the type of report and you will receive your data back.

Use switch -Beta if you want to use the Microsoft Graph BETA version.

Do you miss certain reports? Let me know in a comment or on Github.


New-MSGraphPreGetRequest Example

New-MSGraphPreGetRequest -Query ListUsers -beta

Output:

businessPhones    : {}
displayName       : Test User Post MSGraph
givenName         :
jobTitle          :
mail              :
mobilePhone       :
officeLocation    :
preferredLanguage :
surname           : 
userPrincipalName : [email protected]
id                : eeddb434-3288-4862-aa6e-781430aea0dd

New-MSGraphPostRequest

With New-MSGraphPostRequest you can ‘post’ queries to Microsoft Graph API.
For example, you use a post request when creating a new user.

You only have to provide the URL and data. The function checks in the background whether the data is already JSON. when this isn’t the case it will automatically format it to JSON.


New-MSGraphPostRequest Example

$json = @{
    accountEnabled    = 'true'
    displayName       = "Test User Post MSGraph"
    mailNickname      = "TestUserPostMSGrah"
    userPrincipalName = "[email protected]"
    passwordProfile   = @{
        forceChangePasswordNextSignIn = 'true'
        password                      = 'H78302ehpib'
    }
}

New-MSGraphPOSTRequest -URL 'https://graph.microsoft.com/v1.0/users' -data $JSON -Verbose

Output:

@odata.context    : https://graph.microsoft.com/v1.0/$metadata#users/$entity
id                : d2b70580-5459-4131-8edd-b4926602a8c3
businessPhones    : {}
displayName       : Test User Post MSGraph
givenName         :
jobTitle          :
mail              :
mobilePhone       :
officeLocation    :
preferredLanguage :
surname           :
userPrincipalName : [email protected]

New-MSGraphPatchRequest

With New-MSGraphPatchRequest you can for example update users, or you can add one or more users to a group and so on.

Unfortunately for now you will need to provide the data to be patched yourself. This is explained on every ‘Update’ posts from the Official Microsoft graph REST API blog.

The example below adds users to an AzureAD group.


New-MSGraphPatchRequest Example

$Users = "[email protected]"
$UserPostList = [System.Collections.Generic.List[Object]]::new() 

foreach ($User in $users)
{
    $Result = New-MSGraphGETRequest -URL "https://graph.microsoft.com/v1.0/users/$user" -Verbose
    $DirectoryObject = 'https://graph.microsoft.com/v1.0/directoryObjects/{0}' -f $Result.id
    $UserPostList.Add($DirectoryObject)
}
$PostBody = [PSCustomObject] @{
    "[email protected]" = $UserPostList
}

$JSON = ConvertTo-Json -InputObject $PostBody

New-MSGraphPATCHRequest -URL 'https://graph.microsoft.com/v1.0/groups/089025ff-fa7a-47d6-b9e5-6010ab0a0680' -data $JSON -Verbose

Output:

New-MSGraphPatchRequest on https://graph.microsoft.com/v1.0/groups/089025ff-fa7a-47d6-b9e5-6010ab0a0680 run successfully.

New-MSGraphDeleteRequest

A ‘delete query’ speaks for itself. With New-MSGraphDeleteRequest you delete the data on the URI you provide. This can be for example a user or group.


New-MSGraphDeleteRequest Example

$URL = 'https://graph.microsoft.com/v1.0/users/[email protected]' 
New-MsGraphDeleteRequest -URL $URL

Output:

New-MSGraphDeleteRequest on https://graph.microsoft.com/v1.0/users/[email protected] run successfully.

MSGRAPH in capital letters cmdlets.

This is used internally by the module and is not intended to be used as a cmdlet by the user.


Get-MSGraphOauthToken

Get-MSGraphOauthToken is a background cmdlet used by the Connect-MSGraph~ cmdlets to login to Microsoft Graph API.


Format-MSGRAPHPreGetRequest 

Format-MSGRAPHPreGetRequest will format the Pre-Get Requests to include BETA, v1.0, and -Once Parameter.