Azure / Azure/azure-cli

Align design across client tools to avoid inconsistent for Microsoft Graph

Open
#22,355 1 comment 0 reactions 1 assignee Claimed by @jiasli View on GitHub
act-identity-squad Auto-Assign feature-request Graph Microsoft Graph
Dominant language
Python
Stars
4.6k
Forks
3.5k
Avg merge
3d 2h
Merged PRs (30d)
60

Description

## Discussion: whether to preserve deprecated AD Graph parameter names

There has been an internal discussion recently about whether we should **preserve deprecated AD Graph parameter names**.

### Azure PowerShell's solution: Keep AD Graph parameter names

For Azure PowerShell, after the Microsoft Graph migration, it uses

- **deprecated AD Graph parameter names as official names**
- **new Microsoft Graph parameter names as aliases**

For example, [`New-AzADApplication`](https://docs.microsoft.com/en-us/powershell/module/az.resources/new-azadapplication?view=azps-7.2.0) uses the deprecated AD Graph property name `-HomePage` as the official parameter name:

![image](https://user-images.githubusercontent.com/4003950/156689775-9744a332-df6d-4230-8b52-02e36841d275.png)

According to https://docs.microsoft.com/en-us/graph/migrate-azure-ad-graph-property-differences, `homepage` has been replaced by `web/homePageUrl` in Microsoft Graph:

![image](https://user-images.githubusercontent.com/4003950/155959373-2e1e8b65-c2e7-48ac-a681-3f442352f944.png)

The new corresponding parameter name should be `-WebHomePageUrl`, but `-WebHomePageUrl` is used as an alias, instead of the official name. Other parameters face similar problems:

- `-AvailableToOtherTenants` which conflicts with `-SignInAudience`
- `-ReplyUrls` vs `-WebRedirectUri`. `New-AzADApplication` makes `-ReplyUrls` and `-WebRedirectUri` the same:
![image](https://user-images.githubusercontent.com/4003950/155960002-0b35e72c-8db0-452f-bfbd-0f07b982a672.png)
However, in Microsoft Graph, `replyUrls` is split into `web/redirectUris` and `publicClient/redirectUris`, instead of replaced by `web/redirectUris`: ![image](https://user-images.githubusercontent.com/4003950/155959675-53781296-4b22-4606-ae0c-4d3cd19042a0.png)
meaning there is no one-one mapping between `replyUrls` and `web/redirectUris`.

### Problems

- New users of Microsoft Graph can't easily find the corresponding parameter names (`-WebHomePageUrl`). Instead, they will have to learn the deprecated AD Graph parameter names (`-HomePage`). This increases learning effort for new users.
- The cmdlet parameter doesn't match the output - `-HomePage` maps to `web/homePageUrl`, introducing inconsistency.

### Azure CLI's solution: be consistent with new Microsoft Graph API

Currently, as detailed in https://docs.microsoft.com/cli/azure/microsoft-graph-migration, we decide to replace deprecated AD Graph parameter names with new Microsoft Graph ones, such as

> `--homepage` argument is replaced by `--web-home-page-url`

If you have any feedback, please feel free to left a comment in this issue.

_Originally posted by @jiasli in https://github.com/Azure/azure-cli/issues/12946#issuecomment-1058796773_

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.