Edit

Microsoft Graph migration

  • Article
  • 2 minutes to read

Due to the deprecation of Azure Active Directory (Azure AD) Graph, the underlying Active Directory Graph API will be replaced by Microsoft Graph API in Azure CLI 2.37.0.

Breaking changes

For differences of the underlying API and output JSON breaking changes, please refer to Property differences between Azure AD Graph and Microsoft Graph.

For example, the most outstanding change is that the objectId property in the output JSON of a Graph object is replaced by id.

Command argument and behavior breaking changes are listed below.

az ad app create/update

  • Split --reply-urls into --web-redirect-uris and --public-client-redirect-uris
  • Replace --homepage with --web-home-page-url
  • Replace --available-to-other-tenants with --sign-in-audience
  • Replace --native-app with --is-fallback-public-client
  • Replace --oauth2-allow-implicit-flow with --enable-access-token-issuance
  • Add --enable-id-token-issuance to set web/implicitGrantSettings/enableIdTokenIssuance
  • Remove --password and --credential-description. Use az ad app credential reset to let Graph service create a password for you (https://github.com/Azure/azure-cli/issues/20675)
  • Add --key-display-name to set keyCredential's displayName

az ad app permission grant

  • Remove --expires
  • --scope no longer defaults to user_impersonation and is now required

az ad app credential reset

az ad sp delete

az ad sp credential

az ad sp credential reset

az ad user create

  • Replace --force-change-password-next-login with --force-change-password-next-sign-in

az ad user update

  • Replace --force-change-password-next-login with --force-change-password-next-sign-in

az ad group get-member-groups

  • Remove --additional-properties

az ad group member add

  • Remove --additional-properties

Known issues

  • Regarding generic update arguments, the only supported operation is using --set on the root level of a Graph object. Using --add, --remove or --set on sub-levels currently doesn't work (due to the underlying infrastructure change). For unsupported scenarios, you may use az rest to directly call Microsoft Graph API. Examples can be found at https://github.com/Azure/azure-cli/issues/22580.
  • Microsoft Graph related commands like az ad and az role will fail in Azure Stack environments which don't have Microsoft Graph support. Please use Azure CLI 2.36.0 or earlier versions for Azure Stack environments.

Install a previous version

If you are not ready for the migration yet, such as lacking Microsoft Graph permissions, you may keep using Azure CLI versions <= 2.36.0. If you have already installed 2.37.0, you may roll back to a previous version following the "Install specific version" section under the installation documents (except for Homebrew which doesn't support installing previous versions).

Troubleshooting

Graph command fails with AADSTS50005 or AADSTS53000

Your tenant may have Conditional Access policies that block using device code flow to access Microsoft Graph. In such cases, use authorization code flow or a service principal to sign in instead. For more information about sign in methods, please see Sign in with Azure CLI.

Microsoft tenant (72f988bf-86f1-41af-91ab-2d7cd011db47) has such Conditional Access policies configured.

More information

You can find more information about the Microsoft Graph migration on https://github.com/Azure/azure-cli/issues/22580.

Give feedback

If you have any questions, please reply to https://github.com/Azure/azure-cli/issues/22580 or create a new issue with the az feedback command.