Note

Access to this page requires authorization. You can try signing in or .

Access to this page requires authorization. You can try .

az role definition

Manage role definitions.

Commands

Name Description Type Status
az role definition create

Create a custom role definition.

 Core GA
az role definition delete

Delete a role definition.

 Core GA
az role definition list

List role definitions.

 Core GA
az role definition show

Show a role definition.

 Core GA
az role definition update

Update a role definition.

 Core GA

az role definition create

Create a custom role definition.

az role definition create --role-definition
 [--acquire-policy-token]
 [--change-reference]

Examples

Create a role with read-only access to storage and network resources, and the ability to start or restart VMs. (Bash)

az role definition create --role-definition '{
 "Name": "Contoso On-call",
 "Description": "Perform VM actions and read storage and network information.",
 "Actions": [
 "Microsoft.Compute/*/read",
 "Microsoft.Compute/virtualMachines/start/action",
 "Microsoft.Compute/virtualMachines/restart/action",
 "Microsoft.Network/*/read",
 "Microsoft.Storage/*/read",
 "Microsoft.Authorization/*/read",
 "Microsoft.Resources/subscriptions/resourceGroups/read",
 "Microsoft.Resources/subscriptions/resourceGroups/resources/read",
 "Microsoft.Insights/alertRules/*",
 "Microsoft.Support/*"
 ],
 "DataActions": [
 "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/*"
 ],
 "NotDataActions": [
 "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write"
 ],
 "AssignableScopes": ["/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"]
}'

Create a role from a file containing a JSON description.

az role definition create --role-definition @ad-role.json

Required Parameters

--role-definition

Description of a role as JSON, or a path to a file containing a JSON description.

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--change-reference

The related change reference ID for this resource operation.

Property Value
Parameter group: Global Policy Arguments

az role definition delete

Delete a role definition.

az role definition delete --name
 [--acquire-policy-token]
 [--change-reference]
 [--custom-role-only {false, true}]
 [--resource-group]
 [--scope]

Examples

Delete a role definition. (autogenerated)

az role definition delete --name MyRole

Required Parameters

--name -n

Matches the role definition's name (GUID) or roleName (e.g. 'Reader') property.

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--change-reference

The related change reference ID for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--custom-role-only

Custom roles only(vs. build-in ones).

Property Value
Default value: False
Accepted values: false, true
--resource-group -g

Use it only if the role or assignment was added at the level of a resource group.

--scope

Scope at which the role assignment or definition applies to, e.g., /subscriptions/0b1f6471-1bf0-4dda-aec3-111122223333, /subscriptions/0b1f6471-1bf0-4dda-aec3-111122223333/resourceGroups/myGroup, or /subscriptions/0b1f6471-1bf0-4dda-aec3-111122223333/resourceGroups/myGroup/providers/Microsoft.Compute/virtualMachines/myVM.

az role definition list

List role definitions.

az role definition list [--custom-role-only {false, true}]
 [--name]
 [--resource-group]
 [--scope]

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--custom-role-only

Custom roles only(vs. build-in ones).

Property Value
Default value: False
Accepted values: false, true
--name -n

Matches the role definition's name (GUID) or roleName (e.g. 'Reader') property. If a GUID is provided, for better performance, use az role definition show command.

--resource-group -g

Use it only if the role or assignment was added at the level of a resource group.

--scope

Scope at which the role assignment or definition applies to, e.g., /subscriptions/0b1f6471-1bf0-4dda-aec3-111122223333, /subscriptions/0b1f6471-1bf0-4dda-aec3-111122223333/resourceGroups/myGroup, or /subscriptions/0b1f6471-1bf0-4dda-aec3-111122223333/resourceGroups/myGroup/providers/Microsoft.Compute/virtualMachines/myVM.

az role definition show

Show a role definition.

az role definition show [--id]
 [--name]
 [--scope]

Examples

Show the 'Reader' role definition with its name (GUID).

az role definition show --scope /subscriptions/00000000-0000-0000-0000-000000000000 --name acdd72a7-3385-48ef-bd42-f606fba81ae7

Show the 'Reader' role definition with its resource ID.

az role definition show --id /subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.Authorization/roleDefinitions/acdd72a7-3385-48ef-bd42-f606fba81ae7

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--id

The fully qualified role definition ID. Use the format, /subscriptions/{guid}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId} for subscription level role definitions, or /providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId} for tenant level role definitions.

--name -n

The role definition's name (GUID).

--scope

Scope at which the role assignment or definition applies to, e.g., /subscriptions/0b1f6471-1bf0-4dda-aec3-111122223333, /subscriptions/0b1f6471-1bf0-4dda-aec3-111122223333/resourceGroups/myGroup, or /subscriptions/0b1f6471-1bf0-4dda-aec3-111122223333/resourceGroups/myGroup/providers/Microsoft.Compute/virtualMachines/myVM.

az role definition update

Update a role definition.

az role definition update --role-definition
 [--acquire-policy-token]
 [--change-reference]

Examples

Update a role using the output of "az role definition list". (Bash)

az role definition update --role-definition '{
 "roleName": "Contoso On-call",
 "Description": "Perform VM actions and read storage and network information.",
 "id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/providers/Microsoft.Authorization/roleDefinitions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
 "roleType": "CustomRole",
 "type": "Microsoft.Authorization/roleDefinitions",
 "Actions": [
 "Microsoft.Compute/*/read",
 "Microsoft.Compute/virtualMachines/start/action",
 "Microsoft.Compute/virtualMachines/restart/action",
 "Microsoft.Network/*/read",
 "Microsoft.Storage/*/read",
 "Microsoft.Authorization/*/read",
 "Microsoft.Resources/subscriptions/resourceGroups/read",
 "Microsoft.Resources/subscriptions/resourceGroups/resources/read",
 "Microsoft.Support/*"
 ],
 "DataActions": [
 "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/*"
 ],
 "NotDataActions": [
 "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write"
 ],
 "AssignableScopes": ["/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"]
}'

Required Parameters

--role-definition

Description of an existing role as JSON, or a path to a file containing a JSON description.

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--change-reference

The related change reference ID for this resource operation.

Property Value
Parameter group: Global Policy Arguments

Feedback

Was this page helpful?