Introduction
As promised in my blog post last week, this is the first of many blog posts on Microsoft Graph PowerShell and to start things out right we will first cover the How on connecting to Microsoft Graph PowerShell. Then over the coming weeks we will cover permissions, cmdlet discovery as well as some common use cases for Graph cmdlets. These articles are written for you, the reader, as much as they are for me, the author as Graph PowerShell is not currently my specialty and I am hoping to make it so in 2023.
Connection Types
Microsoft Graph provides a two PowerShell cmdlets to connect to the service, but in reality there is one cmdlet and one alias which points to that cmdlet:
Get-Command connect*graph
To illustrate the Alias concept:
If we need to get some examples on how to use the cmdlet, we see that the built-in help is empty:
get-help connect-mggraph -examples
No Online help can be pulled via PowerShell:
To find the cmdlet help online, we find that it is described in this article:
https://learn.microsoft.com/en-us/powershell/microsoftgraph/authentication-commands
This is the landing page for all cmdlets in the Microsoft.Graph.Authentication module.
Notice that this module is not listed in the Reference section, but it all the cmdlets from the module are included in the Authentication Commands link provided above.
Making a Connection to Graph
OK. So what does it really take to connect to Microsoft Graph PowerShell? Well, not much actually as we can just type in Connect-MgGraph and we will establish a connection to Graph:
However this does not necessarily give us the connection we want (explanation coming), but it does provide the most basic connection to the Microsoft Graph SDK there is.
One thing to watch out for is if Certificate Based Auth is configured and it is not used in the connection process, failures will occur:
Now, in order to perform certain actions in Graph we need to make sure we have the correct permissions assigned to the account that is executing the PowerShell code. Digging into the documentation a bit we see that permissions should be assigned when the connection is made so that the user connecting to Graph has permission to the resources and cmdlets in order to run the necessary PowerShell Code. One sample provided by Microsoft provides the user connecting with Read access to user accounts as well as Read/Write access to Groups:
Connect-MgGraph -Scopes "User.Read.All", "Group.ReadWrite.All"
The ‘-Scopes’ parameter is used to specify access rights to resources in Graph. Keep in mind if this is your first time connecting with these permissions, you may receive a pop-up about allowing this change.
Now there are a lot of permissions out there, and we will cover the relation between cmdlets and permissions in a separate article. For reference, we can find a list of permissions using PowerShell:
Find-MgGraphPermission
The above is a truncated list of permissions available in graph.
Connecting as a Different User
If a connection to Graph needs to be done with alternate credentials, say a service account or perhaps an admin login account, we can do this like so:
Connect-MgGraph -ContextScope Process -ForceRefresh
This will bring up a Modern Auth client prompt for login / credentials:
Additional Authentication Module Cmdlets
Above and beyond the two connection cmdlets, there are some other useful cmdlets available for use. One of these is the Get-MgContext cmdlet which provides information on your Microsoft Graph connection, including details like Scopes, User connect, tenant ID and Account Name (UPN of user connecting):
With the combination of Get-MgEnvironment and Get-MgPRofile, we can see where we are connecting in terms of Graph Endpoints as well:
We see from the above screenshot that there are different endpoints to connect to for different clouds. By using the table above, we can decern which endpoint we need to connect to depending on our own cloud. For example, if we had an account on the US Department of Defense cloud, we would connect to Graph like so:
Connect-MgGraph -Environment USGivDoD
Disconnecting
In an effort to keep our PowerShell connections limited and clean, when we are done with executing code in Microsoft Graph PowerShell, we should also disconnect those connections. This action can be performed with one of two cmdlets:
Disconnect-Graph Disconnect-MgGraph
Conclusion
As this is the first in a series of Graph Articles we covered just the beginning stages of using Graph PowerShell, from connecting to disconnecting as well as some of the other Authentication cmdlets that are part of the Graph module. What we see is that connecting to Graph can be a more complicated process as it requires permissions in order to access resources/cmdlets. Additionally, there are multiple ways to connect to the Graph service. In future articles we will cover cmdlet discovery, then discovering permissions needed to run cmdlets in Graph as well as how to handle more advanced queries like Active Directory actions which require some additional steps.
———————————————————————————————————–
Comments? Questions?
For more advanced Graph features, a new planned book on Microsoft Graph PowerShell will be coming out by the end of 2023. These articles are meant to be fillers until I can get the book written as well.
Feel free to leave your Comments below! Learn to more efficiently utilize PowerShell to manage Exchange Server, Exchange Online, Microsoft Defender for Office or Microsoft Purview Compliance portals by picking up frequently updated eBooks: