The Microsoft Graph is the unified API for Microsoft cloud services that is REST-based. It is the solution to the problem of data silos in the various services, like Exchange Online, SharePoint Online, InTune, Azure AD, and more. What is really nice about the API is that you can easily move between nodes within the Graph to related nodes by intuitive relationships (Manager > Direct Reports, User > Group, User > File > File creator, etc.). The problem for non-developers is that it has been made for developers despite being marketed to everyone.
At its heart, it is just a wrapper that sits on top of existing APIs. The starting place is graph.microsoft.io. Here you can find documentation, sample code, and the Graph Explorer, which is a web interface to query the Graph; it is seeded with demo data, or you can sign in with your account and access your live tenant data. From a security perspective, it adheres to all existing security controls for the services. So, a user has permissions to read much of the data in Azure AD and can read that data; if more information is required, an account with the required permissions must be used or the permissions granted to the user.
Why PowerShell?
Much of what you can do with the Graph already exists for administrators. For instance, the AzureAD PowerShell module is a Graph-based module. However, not all of the funtionality is exposed. What has taken me down this path is seeking a means to provision and license users in Azure Active Directory. The commands allow some parameters to be filtered service-side, but not others. The Graph is different because everything can be filtered service-side which means less bandwidth and memory consumption; if your directory is 50k users strong, it would be a waste to pull down the entire user population into memory when you only need the newest 5 users.
Offering a PowerShell module makes the Graph more accessible to administrators. Plus, since it is a REST-based API, PowerShell already contains ample functionality to work with Microsoft Graph. I will walk you through the process of creating the module with the following requirements: Modern Authentication, allow for generic queries, and build out some basic functions that permit many of the normal functions. In addition, one of the very specific requirements that will be met is the ability to filter objects by attributes synchronized by custom attribute synchronization with Azure AD Connect. This will be released as open source and should ideally mature over time.
Clearing Up the Confusion, Maybe
Microsoft has been rather unclear with the various “Graphs” that is has released. During Microsoft Ignite 2017, some of this was cleared up and some of it was shoved to the side. First of all, there were (and still are) numerous Graph APIs within the Microsoft cloud services ecosystem. Second, the future is the Microsoft Graph. So, if you are searching for information on the Graph and it seems to not work, you might be looking at one of the earlier Graph APIs. The thing to be aware is the endpoint, which should be graph.microsoft.com. If documentation that you are referencing is looking at graph.windows.net, you’re looking at the wrong Graph. What is worse is that while the Microsoft Graph was labelled as “the future,” it was lacking capabilities from the other Graph APIs. This has largely been addressed, but it means that you must be aware of the version in which a particular capability exists (at this time: “v1.0” and “beta”).
Reviewing Documentation
Documentation for the Graph is aligned by version with allows you to see what is exposed to each version. For instance “/users” is available to both versions, but “/applications” is only available in the beta.
Repository
The module is named xMSGraph.PowerShell and is located on GitHub (currently version 0.1). I arrived at the name because this is a “community” module, so it starts with “x”, and then the rest is descriptive. The module depends on the Microsoft.ADAL.PowerShell module.
The Commands
Connect-Graph
Example: Connect-Graph -TenantDomain <TenantName>.onmicrosoft.com
This retrieves a Bearer token from Azure AD for use with the Microsoft Graph.
Get-GraphQuery
Example: Get-GraphQuery "users"
Example: Get-GraphQuery "me" -Raw
Example: Get-GraphQuery "applications" -GraphVersion beta -Filter "displayName eq 'Tenant Schema Extensions App'"
This is a basic query command that allows users to specify the node to query, the version of the Graph, and other options that use OData (Filter, Select, and Expand).
Get-GraphUser
Example: Get-GraphUser
Example: Get-GraphUser -UserPrincipalName <UserPrincipalName>
This command is more sophisticated than it let’s on. The Connect-Graph command establishes some overall metadata related to the tenant, including custom attributes synchronized with Azure AD Connect. This command has a dynamic parameter block that builds parameters for each custom attribute that is synchronized for user objects. For instance, I use extensionAttribute13.
Most of the commands are Advanced Functions, which means that they have the Common Parameters in PowerShell. I make use of Write-Verbose extensively for comments and functionality.
I will be posting some videos of the coding process as these might be useful to many that are learning PowerShell.
If you would like to support my continued efforts, consider getting a copy of Learn Windows PowerShell in a Month of Lunches
Dustin Dortch 