Exploring the new Microsoft Graph PowerShell Module(s)

2 minute read

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:

Install-Module -Name Microsoft.Graph -Scope CurrentUser

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") Connect-Graph
  • Navigate with your web brwoser to https://microsoft.com/devicelogin and enter the code displayed in your terminal DeviceAuth
  • Sign-in with your Azure AD account: deviceauth-accountpng
  • Grant consent: consent connected
  • Check the current Graph Connection details Get-MgContext
  • Let’s search for a group Get-MgGroup

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 AppReg
  • Assign the desired Microsoft Graph Permissions (Application Permissions, do not forget to grant admin consent) AppPermissions
  • Upload the public key of your generated certificate to the app registration AddCert
  • Note the app registration details AppDetails
  • Connect to Graph with:
    Connect-Graph -ClientId 66d94fbd-2d81-4c80-b85a-0dbfd2cd164c -TenantId 7955e1b3-cbad-49eb-9a84-e14aed7f3400 -CertificateThumbprint 9542C4E9B5E21120F3FEC7AD22411F0F727CA0D2
    
  • When checking the connection details Context

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:

Disconnect-Graph

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.

Comments