Inaccurate --filter example for az ad app permission list-grants

[DevopsMercenary]

The --filter example of

https://learn.microsoft.com/en-us/cli/azure/ad/app/permission?view=azure-cli-latest#az-ad-app-permission-list-grants

returns Invalid filter clause

The example for list-grants shows

OData filter, e.g. --filter "displayname eq 'test' and servicePrincipalType eq 'Application'".

but when I try it myself

$ az ad app permission list-grants --filter "displayname eq 'test' and servicePrincipalType eq 'Application'"
Invalid filter clause
``

$ az version { "azure-cli": "2.44.1", "azure-cli-core": "2.44.1", "azure-cli-telemetry": "1.0.8", "extensions": { "account": "0.2.5", "desktopvirtualization": "0.2.0", "dns-resolver": "0.2.0", "quota": "0.1.0", "ssh": "1.1.3" } }

---
#### Document Details

⚠ *Do not edit this section. It is required for learn.microsoft.com ➟ GitHub issue linking.*

* ID: 6a5b5348-f67e-ef14-0529-4c80fddd4bc6
* Version Independent ID: bfd7e6b1-1fba-3d25-8ee3-5105bcf4157d
* Content: [az ad app permission](https://learn.microsoft.com/en-us/cli/azure/ad/app/permission?view=azure-cli-latest)
* Content Source: [latest/docs-ref-autogen/ad/app/permission.yml](https://github.com/MicrosoftDocs/azure-docs-cli/blob/main/latest/docs-ref-autogen/ad/app/permission.yml)
* Service: **active-directory**
* GitHub Login: @rloutlaw
* Microsoft Alias: **routlaw**

[yonzhan]

@jiasli for awareness

[jiasli]

Even in Azure CLI <= 2.36.0 when AD Graph is used, the result of az ad app permission list-grants looks like

[
  {
    "clientId": "07b02b3f-7905-454d-bb6f-7f1512603842",
    "consentType": "AllPrincipals",
    "expiryTime": "2023-05-08T04:53:18.3775361",
    "objectId": "PyuwBwV5TUW7b38VEmA4QonI76O38TJFngGR4y0QOfQ",
    "odatatype": null,
    "principalId": null,
    "resourceId": "a3efc889-f1b7-4532-9e01-91e32d1039f4",
    "scope": "User.Read Directory.AccessAsUser.All",
    "startTime": "0001-01-01T00:00:00"
  }
  ...
]

In Azure CLI >= 2.37.0, the result looks like

[
  {
    "clientId": "07b02b3f-7905-454d-bb6f-7f1512603842",
    "consentType": "AllPrincipals",
    "id": "PyuwBwV5TUW7b38VEmA4QonI76O38TJFngGR4y0QOfQ",
    "principalId": null,
    "resourceId": "a3efc889-f1b7-4532-9e01-91e32d1039f4",
    "scope": "User.Read Directory.AccessAsUser.All"
  }
  ...
]

So displayname or servicePrincipalType are never valid properties for oauth2PermissionGrants type. Instead, they are for servicePrincipals type (returned by az ad sp list).

The reason why the example for --filter shows that is because --filter is defined on the whole az ad scope, so whenever a command under az ad supports --filter, the help message shows the same example:

https://github.com/Azure/azure-cli/blob/ce4469321e66be2ef75b2c2721be7e289ab20a84/src/azure-cli/azure/cli/command_modules/role/_params.py#L232

https://github.com/Azure/azure-cli/blob/ce4469321e66be2ef75b2c2721be7e289ab20a84/src/azure-cli/azure/cli/command_modules/role/_params.py#L237

By reviewing the source code, commands that support --filter are:

• az ad app list
• az ad app permission list-grants
• az ad sp list
• az ad user list
• az ad group list

To solve it, I think we can do either

1. Link to https://learn.microsoft.com/en-us/graph/filter-query-parameter which is a comprehensive explanation of $filter query parameter. The document is written by MS Graph service, so we don't need to provide examples and verify them on the client side for each command. (Personally, I prefer this option.)
2. Provide customized examples for each command's --filter. This needs extra effort and can't cover all functionalities.

[ghost]

Thank you for your feedback. This has been routed to the support team for assistance.