Skip to content

upgrade-to-v2.md

Latest commit

 

History

History
177 lines (110 loc) · 8.87 KB

upgrade-to-v2.md

File metadata and controls

177 lines (110 loc) · 8.87 KB

Microsoft Graph PowerShell V2 Changelog and Upgrade Guide

The purpose of this document is to outline breaking changes and migration work module users might run into while upgrading to v2 of the module.

Overview

The old v1 version of the PowerShell module used profiles (Select-MgProfile <API-VERSION>) to switch the commands from one version of Microsoft Graph API to another. The profile design made the module bulky and error prone as it combined Microsoft Graph v1.0 and beta commands into a single module.

The v1 version relied on the now deprecated Microsoft Graph Auth providers to acquire and cache access tokens. This limited us to just a handful of auth grant types that we could support.

Breaking changes

The following section lists breaking changes that may require script changes for users of the module.

Profile Support

Previously, customers needed to use Select-MgProfile beta to load beta commands and Select-MgProfile v1.0 to load v1.0 commands. The new version drops profile support by having separate v1.0 and beta modules. v2 replaces profile support with the following changes:

Module Names

Each module will be divided into independent v1.0 and beta modules. v1.0 modules will retain the names of existing modules. beta modules will have Beta in the module name, e.g.

V1.0 Beta
Microsoft.Graph Microsoft.Graph.Beta
Microsoft.Graph.Users Microsoft.Graph.Beta.Users

Command Names

v1.0 commands will maintain the current Verb-Subject syntax with Mg as the command prefix. beta commands will maintain the current Verb-Subject syntax, with MgBeta as the prefix, e.g.

V1.0 Beta
Get-MgUser Get-MgBetaUser
Get-MgUserMessage Get-MgBetaUserMessage

With this change, customers targeting beta endpoint will no longer need to use Select-MgProfile beta to load beta commands as beta commands will exist side-by-side with v1.0 commands. This will also allow for mixing on v1.0 and beta commands in the same script without needing to reload the entire module.

With v1
Connect-MgGraph
Select-MgProfile beta
$BetaUsers = Get-MgUser
Select-MgProfile v1.0
$V1Users = Get-MgUser
With V2
Connect-MgGraph
$BetaUsers = Get-MgBetaUser
$V1Users = Get-MgUser

Beta Namespace

Entity types in beta have moved from Microsoft.Graph.PowerShell.Models.<Entity> to Microsoft.Graph.Beta.PowerShell.Models.<Entity> namespace. This was done to disambiguate beta types from v1.0 types.

Connect-MgGraph -AccessToken

In v2, we've changed -AccessToken from String to SecureString type. This change was added to harden the module from security vulnerabilities.

Connect-MgGraph -ForceRefresh

We've dropped support for -ForceRefresh on Connect-MgGraph command. -ForceRefresh is no longer support by the auth token credentials used in v2. Customers should instead use Disconnect-MgGraph to sign out of current context then call Connect-MgGraph to get a new access token.

Renamed DeviceManagement.Enrolment module to DeviceManagement.Enrollment

DeviceManagement.Enrolment module has been renamed to DeviceManagement.Enrollment to align with the API.

Directory Role and Entitlement Management Commands

Directory role and entitlement management commands that were in DeviceManagement.Enrollment module have been moved to Identity.Governance to align with the API reference.

Product Name Change in Certain Command

Pluralized product names, such as Windows, were wrongly named to their singular forms (e.g., Window) in the v1 SDK. In the v2 SDK, these names have been restored to their original plural forms. Therefore, commands that used to have Window in their name now have Windows instead. For example:

v1 SDK v2 SDK
Get-MgDeviceManagementWindowAutopilotDeviceIdentity Get-MgDeviceManagementWindowsAutopilotDeviceIdentity
Get-MgDeviceManagementWindowInformationProtectionAppLearningSummary Get-MgDeviceManagementWindowsInformationProtectionAppLearningSummary

New Features and Improvements

The following new features and improvements have been added to the module in v2.

Authentication

Managed Identity

The new module adds support for Managed Identity. Managed Identity allows the module to obtain access tokens for Azure resources that are protected by Azure Active Directory. The identity is managed by the Azure platform and does not require you to provision or rotate any secrets. See Managed identities fro Azure resources for more details.

System-assigned managed identity

Uses an automatically managed identity on a service instance. The identity is tied to the lifecycle of a service instance.

Connect-MgGraph -Identity
User-assigned managed identity

Uses a user created managed identity as a standalone Azure resource.

Connect-MgGraph -Identity -ClientId "User_Assigned_Managed_identity_Client_Id"

Client Secret Credentials

The new module adds support for client secret credentials by adding -Credential parameter to Connect-MgGraph.

$ClientSecretCredential = Get-Credential -Username "Client_Id"
# Enter client_secret in the password prompt.
Connect-MgGraph -TenantId "Tenant_Id" -ClientSecretCredential $ClientSecretCredential

Certificate Credentials

In v2, we've added support for certificate lookup in both current user and local machine certificate store. Priority will be given certificates in CurrentUser store if two identical certificates are present in both stores.

Connect-MgGraph -ClientId "Client_Id" -Tenant "Tenant" -CertificateThumbprint "Cert_Thumbprint"

Environment Variable Based Auth

We've added -EnvironmentVariable to Connect-MgGraph to support environment variable based auth. Client secret takes precedence over certificate, i.e., if values for a client secret and certificate are both present, the client secret will be used. See Azure.Identity Environment Variables for more details.

# Add environment variables to be used by Connect-MgGraph.
$Env:AZURE_CLIENT_ID = "application id of the client app"
$Env:AZURE_TENANT_ID = "Id of your tenant"
$Env:AZURE_CLIENT_SECRET = "secret of the client app"

# Tell Connect-MgGraph to use your environment variables.
Connect-MgGraph -EnvironmentVariable

Service Modules

Count Commands (/$count)

We've added dedicated count commands in v2 for supported resources. In v2, you can now get a count of users in your tenant using:

$UsersCount = Get-MgUserCount -ConsistencyLevel Eventual

See advanced query capabilities on Azure AD objects for more details.

OData Cast Support

V2 adds OData cast commands via *-Mg*As<CAST-Type> syntax when supported by the API. With OData cast support, customers can now access properties on specialized types rather than going through AdditionalProperties for supported APIs. For example, one can use Get-MgGroupMemberAsUser to list group members that are users:

$Users = Get-MgGroupMemberAsUser -GroupId "GROUP_ID"

In the example above, the cast type can also be ServicePrincipal, Application, Device, Group, and more as supported by the API.

Improved Service Error Reporting

We've updated how service errors are written to the error stream to help with debugging API related errors. In v2, when a service error occurs, the SDK will now write message, HTTP status code, error code, request-id, date, and other useful headers to the error stream.

image

See Microsoft Graph API error response for more details.

HTTP/2 support

V2 adds HTTP/2 support for supported API endpoints. The module will gracefully fallback to HTTP/1.1 when HTTP/2 is not supported by the API. HTTP/2 improves performance by adding support for; multiplexing, header compression, and server push.

Success status code range support

With success status code range support. v2 commands will correctly handle and return the right output when an HTTP request responds back with a successful code (2xx). The old implementation only succeeded when the response status code exactly matched what was specified in the API schema.