Getty Images
What's new in Microsoft Graph PowerShell v2?
The company overhauled the new version of its software development kit and updated PowerShell modules that replace legacy methods for managing Microsoft's cloud-based services.
As Microsoft retires older PowerShell management methods for its cloud-based services, administrators must learn how to work with the newer tools, such as Microsoft Graph.
Developers work with the Microsoft Graph unified API to build apps for Microsoft's cloud products, but administrators can also use it to make changes on the Microsoft 365 collaboration platform and the cloud-based access and identity management product Microsoft Entra ID, formerly Azure Active Directory (AD).
With Microsoft Graph, admins interact with data from multiple Microsoft services in a single request. There are two endpoints available: The v1.0 endpoint is stable and recommended for production use, while the beta endpoint consists of APIs in preview status used for testing.
The Microsoft Graph PowerShell SDK is the library that functions as the API wrapper with cmdlets that uncover the entire API set to PowerShell. The standard PowerShell modules, such as Azure AD and MSOnline, used service-specific APIs. As Microsoft slowly merged each independent API into the unified API of Microsoft Graph, PowerShell commands needed either rewriting, deprecating or migrating to a new library.
The Microsoft Graph PowerShell module, which uses the Microsoft Graph PowerShell SDK to tap into the Microsoft Graph API, provides cmdlets to admins who can retrieve data or make changes to the Microsoft 365 tenant and the collaboration services, such as Exchange Online and SharePoint Online. Admins can use PowerShell automation to perform a variety of tasks, such as making bulk licensing changes, sending administrative notifications and producing reports on service use.
What were the drawbacks of Microsoft Graph PowerShell SDK v1?
Microsoft Graph PowerShell SDK v1 used a V1.0 endpoint for production and a beta endpoint to test functionality not yet generally available. To use either one, you would use the following PowerShell command:
Select-MgProfile -Name "V1.0" Select-MgProfile -Name "Beta"
You can run into potential problems with this approach if you use the incorrect endpoint version and do not get the expected results with your PowerShell code. Also, the same script might require the use of both endpoints, which is often needed to perform certain tasks. To do this, you swap profiles frequently, which is not the most efficient approach.
Select-MgProfile -Name "V1.0" $users = Get-MgUser Select-MgProfile -Name "Beta" $alerts = Get-MgSecurityAlert
In the example code, every command that runs after retrieving the security alerts executes with the beta endpoint unless you reset back to the v1 endpoint.
What are the benefits of Microsoft Graph PowerShell SDK v2?
After a short public preview period, Microsoft released the Microsoft Graph PowerShell SDK v2 to general availability in July 2023, which attempted to resolve some drawbacks of the SDK v1. Microsoft Graph PowerShell SDK v2 also features versioning and several other enhancements.
To go with this new SDK version, update the Microsoft.Graph and Microsoft.Graph.Beta PowerShell modules. You can adjust the example code and use name adjustments to the cmdlets based on the module needed.
$users = Get-MgUser $alerts = Get-MgBetaSecurityAlert
As long as both modules are installed, you can tap into newer functionality without swapping to the beta profile.
Install-Module Microsoft.Graph Install-Module Microsoft.Graph.Beta Import-Module Microsoft.Graph Import-Module Microsoft.Graph.Beta
The install size of the Microsoft Graph PowerShell SDK v2 is about 635 MB compared to the 969 MB of Microsoft Graph PowerShell SDK v1. This size difference helps speed up the module import into the console and improves automation efforts, specifically within Azure.
Microsoft Graph PowerShell SDK v2 features a new authentication method that increases security while reducing complexity. Microsoft Graph PowerShell SDK v2 supports managed identity for authentication via the Connect-MgGraph command. With managed identity, the v2 module can access tokens for Azure resources that Microsoft Entra ID protects. The Azure platform manages the identity and does not require you to provision or rotate any secrets. You can utilize system-assigned managed identities and user-assigned managed identities.
Connect-MgGraph -Identity Connect-MgGraph -Identity -ClientId "c853667c-e346-4f40-b07b-49edbf8eb8d5."
Microsoft Graph PowerShell SDK v2 also supports client secrets by adding the -ClientSecretCredential parameter to the Connect-MgGraph cmdlet to perform work on the tenant without signing in.
# Client Secret Connection
$secret = Get-Credential `
-Username "c853667c-e346-4f40-b07b-49edbf8eb8d5"
Connect-MgGraph `
-TenantId "320a9610-d27d-4772-875c-03934f561c76" `
-ClientSecretCredential $secret
Microsoft Graph PowerShell SDK v2 also introduces another new authentication method with certificate credentials for both the current user and the local machine.
# Certificate Connection
Connect-MgGraph `
-ClientId "c853667c-e346-4f40-b07b-49edbf8eb8d5" `
-Tenant "320a9610-d27d-4772-875c-03934f561c76" `
-CertificateThumbprint "a909502dd82ae41433e6f83886b00d4288a32a7c"
You can also use environment variables as storage for authentication properties. Storing parameter keys and values in environment variables prevents leaking sensitive information when sharing scripts.
The updated Connect-MgGraph command supports environment variable-based authentication with the EnvironmentVariable flag.
# Add environment variables $Env:CLIENT_ID = "c853667c-e346-4f40-b07b-49edbf8eb8d5" $Env:TENANT_ID = "320a9610-d27d-4772-875c-03934f561c76" $Env:CLIENT_SECRET = "~w28Q~lkHcX9GyStTAZP-Ymaz95c7nOl1_-oUa4Z" # Connect using environment variables Connect-MgGraph –EnvironmentVariable
Changes to be aware of in Microsoft Graph PowerShell v2
When any code is modified or updated, often features or components no longer work or move to new locations. The Microsoft PowerShell Graph SDK v2 is no different.
The beta entity types now reside within the Microsoft.Graph.Beta.PowerShell.Modules.<Entity> namespace to keep them unique from the standard types.
Microsoft has also modified the property AccessToken, which you use with the Connect-MgGraph command. It is a SecureString not a String data type, as part of the overall work to harden the PowerShell modules from security vulnerabilities. The library no longer supports the "Force Refresh" property using the Connect-MgGraph command. Instead, you need to sign out with the Disconnect-MgGraph command and reconnect.
How to upgrade to Microsoft Graph PowerShell v2
To start with Microsoft Graph PowerShell SDK v2, you need to install the updated Microsoft.Graph and Microsoft.Graph.Beta PowerShell modules.
# Install Microsoft.Graph and allow the prerelease version to install Install-Module Microsoft.Graph -AllowPrerelease -AllowClobber -Force # Install Microsoft.Graph.Beta and allow the prerelease version to install Install-Module Microsoft.Graph.Beta -AllowPrerelease -AllowClobber -Force
To replace the current version, remove the AllowClobber property. To run the versions side by side, keep the AllowClobber property.
Once installed, load the module you will use with the Import-Module command.
Import-Module Microsoft.Graph Import-Module Microsoft.Graph.Beta
To check the modules loaded, execute the following:
Get-Module -Name Microsoft.Graph*
Once loaded, you can use the v1 and beta modules and execute v1 and beta commands in a script without the need to use the Select-MgProfile command.
Get-MgUser Get-MgBetaUser
Microsoft Graph PowerShell SDK v2 changes will ease management work
The Microsoft Graph PowerShell SDK simplifies tenant management through the automation of daily tasks. The SDK handles complex features such as throttling, retries, redirects and authentication.
The release of the Microsoft Graph PowerShell SDK v2 brings a more enhanced experience. The v1 and beta modules use different prefixes in their cmdlets, which helps you to write more robust, less error-prone scripts. The prefixes in the cmdlets help identify where preview functionality resides and makes it less ambiguous to combine the use of both production and preview endpoints in any script.
