Use `roleName` filter to limit the results returned by `az role definition list --name`

[kewalaka]

Related command

Any role definition list operation that filters by name, e.g.:

az role definition list --name "Contributor"

Is your feature request related to a problem? Please describe.

The call to the resource manager API fetches all the IDs:

GET https://management.azure.com/subscriptions/<id>/providers/Microsoft.Authorization/roleDefinitions?api-version=2022-05-01-preview 
HTTP/1.1

Whilst the works, it seems unnecessarily costly given a specific name has been supplied.

Describe the solution you'd like

Consider specifying the role name if supplied, using the target query parameter:

GET https://management.azure.com/subscriptions/<id>/providers/Microsoft.Authorization/roleDefinitions?api-version=2022-05-01-preview&$filter=roleName%20eq%20'Contributor' 
HTTP/1.1

Describe alternatives you've considered
n/a

Additional context
https://learn.microsoft.com/en-us/rest/api/authorization/role-definitions/list?view=rest-authorization-2022-04-01&tabs=HTTP#uri-parameters

[yonzhan]

Thank you for opening this issue, we will look into it.

[kewalaka]

I guess downloading it once for all the role types might be more efficient if you take into account caching. Was just a curiosity i spotted when doing some testing.

[jiasli]

@kewalaka, you have sharp eyes!

The role definition filtering is indeed performed on the client side:

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

Lines 140 to 150 in e8aa309

	def _search_role_definitions(cli_ctx, definitions_client, name, scopes, custom_role_only=False):
	for scope in scopes:
	roles = list(definitions_client.list(scope))
	worker = MultiAPIAdaptor(cli_ctx)
	if name:
	roles = [r for r in roles if r.name == name or worker.get_role_property(r, 'role_name') == name]
	if custom_role_only:
	roles = [r for r in roles if worker.get_role_property(r, 'role_type') == 'CustomRole']
	if roles:
	return roles
	return []

This is because, according to L145, --name matches both name and roleName. For example, you may retrieve Reader role definition with either command:

az role definition list --name Reader
az role definition list --name acdd72a7-3385-48ef-bd42-f606fba81ae7

And the result is the same:

[
  {
    "assignableScopes": [
      "/"
    ],
    "createdBy": null,
    "createdOn": "2015-02-02T21:55:09.880642+00:00",
    "description": "View all resources, but does not allow you to make any changes.",
    "id": "/subscriptions/xxx/providers/Microsoft.Authorization/roleDefinitions/acdd72a7-3385-48ef-bd42-f606fba81ae7",
    "name": "acdd72a7-3385-48ef-bd42-f606fba81ae7",
    "permissions": [
      {
        "actions": [
          "*/read"
        ],
        "condition": null,
        "conditionVersion": null,
        "dataActions": [],
        "notActions": [],
        "notDataActions": []
      }
    ],
    "roleName": "Reader",
    "roleType": "BuiltInRole",
    "type": "Microsoft.Authorization/roleDefinitions",
    "updatedBy": null,
    "updatedOn": "2021-11-11T20:13:47.862868+00:00"
  }
]

But I think you made a very good point. We may consider adding --role-name for a more efficient search.

[jiasli]

I guess downloading it once for all the role types might be more efficient if you take into account caching. Was just a curiosity i spotted when doing some testing.

Most Azure CLI commands by far have no caching mechanism, as it is impossible to know when the data returned by the ARM service expires.

Take https://learn.microsoft.com/en-us/rest/api/authorization/role-definitions/list?view=rest-authorization-2022-04-01&tabs=HTTP as an example, if a new role is created, CLI will not know that. Quering ARM service again will defeat the purpose of caching.

[kewalaka]

Most Azure CLI commands by far have no caching mechanism, as it is impossible to know when the data returned by the ARM service expires.

Take https://learn.microsoft.com/en-us/rest/api/authorization/role-definitions/list?view=rest-authorization-2022-04-01&tabs=HTTP as an example, if a new role is created, CLI will not know that. Quering ARM service again will defeat the purpose of caching.

Good point! I was thinking in the context of built in roles but of course that is too limiting.

[jiasli]

I did a quick test in #30587 and the number of returned role definitions reduced from 727 to 1, making az role definition list much faster.

However, roleName eq '{role_name}' filter is not documented in any official documents:

• https://learn.microsoft.com/en-us/azure/role-based-access-control/role-definitions-list
• https://learn.microsoft.com/en-us/rest/api/authorization/role-definitions/list?view=rest-authorization-2022-04-01&tabs=HTTP

Azure CLI has been using roleName as a filter since 2016 (#508):

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

Line 620 in a43f7f9

role_defs = list(definitions_client.list(scope, "roleName eq '{}'".format(role)))

I'll internally discuss with RBAC team on this.