Microsoft Graph PowerShell module made it to the PowerShell Gallery! So, now you can try it out on your computer by simply running the Install-Module Microsoft.Graph.Authentication command. See more here.
Microsoft Graph is the key to Microsoft 365 system. This OData interface allows to get and modify data of objects such as users, groups, their data and the tenant. Find out more at aka.ms/graph.
Announced at the last Microsoft Ignite conference, admins can now use the Microsoft Graph PowerShell module directly from the PowerShell Gallery. See more details at Microsoft Graph PowerShell SDK (Preview) on GitHub. So let´s start our quick overview.
Uninstall previous Microsoft.Graph versions
If you had installed an older version of Microsoft.Graph (e.g. before it was available in the PS Gallery), you can uninstall any existing versions of Microsoft Graph as here.
Get-InstalledModule -Name microsoft.graph.* | Uninstall-Module -AllVersions
Install Microsoft.Graph from the PS Gallery
To install the latest version, run the Install-Module as Administrator as here. (The current module version number was changed to align with the milestones in the GitHub repo.)
Install-Module Microsoft.Graph -Repository PSGallery -force
Downloading and installing the modules can take some minutes. Note that you can also install the module for the Graph Beta endpoint by using Install-Module Microsoft.Graph.Beta.
You can check out the modules by executing the Get-InstalledModule command.
Get-InstalledModule -Name microsoft.graph.*
You will see a list of available (currently 89) modules, their version and their resource description. The current version number is 0.1.1 (only Microsoft.Graph.Authentication is 0.1.5). The single modules are by default stored as PS-libraries in C:\Program Files\WindowsPowerShell\Modules.
Note: The new packages are called Microsoft.Graph* although they still point to the Beta API. This will be changed in near future.
To see a list of all commandlets (which is looong), use
Get-Command -Module Microsoft.Graph.*
As we see, the prefix "Mg", for MicrosoftGraph, is used for the commands here. Let´s see if this prefix will come to the Connect and Disconnect commands as well.
Now let´s use it.
Connect to Microsoft.Graph
You need to authenticate with a Microsoft Identity to get an access token to call Microsoft Graph modules. You can authenticate for delegated access (via Device Code Flow) or via Client Credential Flow with a certificate, see Microsoft Graph PowerShell SDK (Preview) on GitHub. Here, we connect interactively as a user with delegated permissions to read users:
Connect-Graph -Scopes "User.Read.All"
A text says to open a browser and do a device login using the generated authentication code, such as "To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code AB12… to authenticate.". Then, sign-in with a work account of the tenant. After the successful operation, the module responds "Welcome To Microsoft Graph!". It´s nice that the session is
Note: If you run in any issues during authentication, you can run the following command to fix authentication. This updates that module to the latest version 0.1.5.
Install-Module Microsoft.Graph.Authentication -Repository PSGallery -force
Nevertheless, I had an issue with authentication on my machine. My user did not have Write permissions to the file userTokenCache.bin3 or to the directory stored in C:\Program Files\WindowsPowerShell\Modules\Microsoft.Graph.Authentication\0.1.5\bin and I had to fix that. It worked afterwards.
Use the Graph commands
Then, run one of the many available Graph commands. The commands (of course) have a similar behavior as the Graph API calls, for example:
Get-MgUser -Top 10 -Select Id, DisplayName, UserPrincipalName, UserType
Note: When working with Graph, it´s always a good idea to select only the necessary data with "Select" as in this sample.
The playground is open.
Disconnect
To close the connection, use
Disconnect-Graph
Try it out!
The availability of the Microsoft.Graph module in the PowerShell Gallery makes it easy to consume it. For IT-Administrators, Graph opens the full world of accessing data in a Microsoft 365 tenant.
Happy administering and automating with Microsoft Graph PowerShell!