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:

azure-cli/src/azure-cli/azure/cli/command_modules/role/_params.py

Line 232 in ce44693

with self.argument_context('ad') as c:

azure-cli/src/azure-cli/azure/cli/command_modules/role/_params.py

Line 237 in ce44693

c.argument('query_filter', options_list=['--filter'], help='OData filter, e.g. --filter "displayname eq \'test\' and servicePrincipalType eq \'Application\'"')

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.

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