Microsoft is working on a new set of PowerShell modules grouped under the umbrella of Microsoft.Graph that will (hopefully) cover all the Microsoft Graph resources available. I’ve already used some of them for my Conditional Access Documentation Script and thought they have some notable features worth sharing.
Advantages and changes
The Microsoft Graph modules use the new Microsoft Authentication Library (MSAL) instead of the old Azure AD Authentication Library (ADAL). The MSAL library in the modules implements a token cache which persists the access and refresh tokens.
MSAL caches a token after it has been acquired. Application code should try to get a token silently (from the cache), first, before acquiring a token by other means. - Microsoft docs
The token cache persists system reboots and re-opening PowerShell sessions. The module allows you to obtain tokens either for authentication via client credentials (certificate only) or device code flow.
Furthermore, the new modules support a really broad spectrum of available entities on the Graph API. From an EM+S perspective this means for example: groups, users, identity protection, conditional access, and some of the Intune app management commands are also starting to appear.
Just be aware that the modules are currently published as pre-release. If you encounter any issues share them with the development team on GitHub and submit issues or even better contribute directly to the project.
How to get the module(s)
The modules are available on the PowerShell Gallery. Install all modules with:
| |
You can also install individual modules like the module for group management “Microsoft.Graph.Group”. Whereas the “Microsoft.Graph.Authentication” is the minimal starting point in order to connect to Microsoft Graph.
Note that all the cmdlets are prefixed with Mg which produces cmdlets in the format of verb- Mg noun:
- Get-MgGroup
- Get-MgUser
- Get-MgConditionalAccessPolicy
Connecting to Graph
The Microsoft Graph modules support authentication via device code flow (accessing the API as user) or via client credentials (accessing the API as application).
Option 1 - Device code flow
- Start device code flow authentication & grant initial consent:
Connect-Graph -Scopes @("Group.Read.All")
- Navigate with your web brwoser to https://microsoft.com/devicelogin and enter the code displayed in your terminal
- Sign-in with your Azure AD account:
- Grant consent:
- Check the current Graph Connection details
- Let’s search for a group
Option 2 - Client credentials (certificate)
The Microsoft.Graph module supports authentication with a client certificate. Client secrets are not supported (when this post was written).
- Generate a new certificate in your personal certificate store
- Create an Azure AD App registration
- Assign the desired Microsoft Graph Permissions (Application Permissions, do not forget to grant admin consent)
- Upload the public key of your generated certificate to the app registration
- Note the app registration details
- Connect to Graph with:
| |
- When checking the connection details
Reconnecting
If you have cached tokens (verify with Get-MgContext) you can use the Connect-Graph command without passing additional arguments.
Clearing the token cache
Clearing the token cache is fairly simple, just run:
| |
Final words
I really like the new Microsoft.Graph PowerShell module but in the same time I hope that they will integrate really all the features from other modules which are already using Microsoft Graph. Just to name some of them: Intune PowerShell SDK, Azure AD PowerShell, MicrosoftTeams… We are already experiencing enough portals - at least let’s keep the number of PowerShell modules low.
Cheers and happy g-raph -ing.