az role assignment

Reference

Manage role assignments.

Commands

Name	Description	Type	Status
az role assignment create	Create a new role assignment for a user, group, or service principal.	Core	GA
az role assignment delete	Delete role assignments.	Core	GA
az role assignment list	List role assignments.	Core	GA
az role assignment list-changelogs	List changelogs for role assignments.	Core	GA
az role assignment update	Update an existing role assignment for a user, group, or service principal.	Core	GA

az role assignment create

Edit

Create a new role assignment for a user, group, or service principal.

az role assignment create --role
                          --scope
                          [--assignee]
                          [--assignee-object-id]
                          [--assignee-principal-type {ForeignGroup, Group, ServicePrincipal, User}]
                          [--condition]
                          [--condition-version]
                          [--description]
                          [--name]

Examples

Create role assignment to grant the specified assignee the Reader role on an Azure virtual machine.

az role assignment create --assignee sp_name --role Reader --scope /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MyResourceGroup/providers/Microsoft.Compute/virtualMachines/MyVm

Create role assignment for an assignee with description and condition.

az role assignment create --role Owner --scope /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MyResourceGroup/providers/Microsoft.Storage/storageAccounts/MyStorageAccount --assignee "John.Doe@Contoso.com" --description "Role assignment foo to check on bar" --condition "@Resource[Microsoft.Storage/storageAccounts/blobServices/containers:Name] stringEquals 'foo'" --condition-version "2.0"

Create role assignment with your own assignment name.

az role assignment create --assignee-object-id 00000000-0000-0000-0000-000000000000 --assignee-principal-type ServicePrincipal --role Reader --scope /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MyResourceGroup --name 00000000-0000-0000-0000-000000000000

Required Parameters

--role

Role name or id.

--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.

Optional Parameters

--assignee

Represent a user, group, or service principal. supported format: object id, user sign-in name, or service principal name.

--assignee-object-id

The assignee's object ID (also known as principal ID). Use this argument instead of '--assignee' to bypass Microsoft Graph query in case the logged-in account has no permission or the machine has no network access to query Microsoft Graph.

--assignee-principal-type

Use with --assignee-object-id to avoid errors caused by propagation latency in Microsoft Graph.

Accepted values: ForeignGroup, Group, ServicePrincipal, User

--condition

Preview

Condition under which the user can be granted permission.

--condition-version

Preview

Version of the condition syntax. If --condition is specified without --condition-version, default to 2.0.

--description

Preview

Description of role assignment.

--name -n

A GUID for the role assignment. It must be unique and different for each role assignment. If omitted, a new GUID is generated.

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc

Default value: json

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az role assignment delete

Edit

Delete role assignments.

This command deletes all role assignments that satisfy the provided query condition. Before running this command, it is highly recommended to run az role assignment list first with the same arguments to see which role assignments will be deleted.

az role assignment delete [--assignee]
                          [--assignee-object-id]
                          [--ids]
                          [--include-inherited]
                          [--resource-group]
                          [--role]
                          [--scope]
                          [--yes]

Examples

Delete all role assignments with "Reader" role at the subscription scope.

az role assignment delete --role Reader --scope /subscriptions/00000000-0000-0000-0000-000000000000

Delete all role assignments of an assignee at the subscription scope.

az role assignment delete --assignee 00000000-0000-0000-0000-000000000000 --scope /subscriptions/00000000-0000-0000-0000-000000000000

Delete all role assignments of an assignee (with its object ID) at the subscription scope.

az role assignment delete --assignee-object-id 00000000-0000-0000-0000-000000000000 --scope /subscriptions/00000000-0000-0000-0000-000000000000

Optional Parameters

--assignee

Represent a user, group, or service principal. supported format: object id, user sign-in name, or service principal name.

--assignee-object-id

--ids

Space-separated role assignment ids.

--include-inherited

Include assignments applied on parent scopes.

Default value: False

--resource-group -g

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

--role

Role name or id.

--scope

--yes -y

Currently no-op.

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc

Default value: json

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az role assignment list

Edit

List role assignments.

By default, only assignments scoped to subscription will be displayed. To view assignments scoped by resource or group, use --all.

[WARNING] Azure classic subscription administrators will be retired on August 31, 2024. After August 31, 2024, all classic administrators risk losing access to the subscription. Delete classic administrators who no longer need access or assign an Azure RBAC role for fine-grained access control. Learn more: https://go.microsoft.com/fwlink/?linkid=2238474.

az role assignment list [--all]
                        [--assignee]
                        [--assignee-object-id]
                        [--fill-principal-name {false, true}]
                        [--fill-role-definition-name {false, true}]
                        [--include-classic-administrators {false, true}]
                        [--include-groups]
                        [--include-inherited]
                        [--resource-group]
                        [--role]
                        [--scope]

Examples

List role assignments at the subscription scope.

az role assignment list --scope /subscriptions/00000000-0000-0000-0000-000000000000

List role assignments at the subscription scope, without filling roleDefinitionName property.

az role assignment list --scope /subscriptions/00000000-0000-0000-0000-000000000000 --fill-role-definition-name false

List role assignments with "Reader" role at the subscription scope.

az role assignment list --role Reader --scope /subscriptions/00000000-0000-0000-0000-000000000000

List role assignments of an assignee at the subscription scope.

az role assignment list --assignee 00000000-0000-0000-0000-000000000000 --scope /subscriptions/00000000-0000-0000-0000-000000000000

List role assignments of an assignee (with its object ID) at the subscription scope, without filling principalName property. This command does not query Microsoft Graph.

az role assignment list --assignee-object-id 00000000-0000-0000-0000-000000000000 --scope /subscriptions/00000000-0000-0000-0000-000000000000 --fill-principal-name false

Optional Parameters

--all

Show all assignments under the current subscription.

Default value: False

--assignee

Represent a user, group, or service principal. supported format: object id, user sign-in name, or service principal name.

--assignee-object-id

--fill-principal-name

Query Microsoft Graph to get the assignee's userPrincipalName (for user), servicePrincipalNames (for service principal) or displayName (for group), then fill principalName property with it. If the logged-in account has no permission or the machine has no network access to query Microsoft Graph, set this flag to false to avoid warning or error.

Accepted values: false, true

Default value: True

--fill-role-definition-name

Fill roleDefinitionName property in addition to roleDefinitionId. This operation is expensive. If you encounter performance issue, set this flag to false.

Accepted values: false, true

Default value: True

--include-classic-administrators

Deprecated

Argument '--include-classic-administrators' has been deprecated and will be removed in next breaking change release(2.73.0) scheduled for May 2025.

List default role assignments for subscription classic administrators, aka co-admins.

Accepted values: false, true

Default value: False

--include-groups

Include extra assignments to the groups of which the user is a member (transitively).

Default value: False

--include-inherited

Include assignments applied on parent scopes.

Default value: False

--resource-group -g

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

--role

Role name or id.

--scope

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc

Default value: json

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az role assignment list-changelogs

Edit

List changelogs for role assignments.

az role assignment list-changelogs [--end-time]
                                   [--start-time]

Optional Parameters

--end-time

The end time of the query in the format of %Y-%m-%dT%H:%M:%SZ, e.g. 2000-12-31T12:59:59Z. Defaults to the current time.

--start-time

The start time of the query in the format of %Y-%m-%dT%H:%M:%SZ, e.g. 2000-12-31T12:59:59Z. Defaults to 1 Hour prior to the current time.

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc

Default value: json

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az role assignment update

Edit

Update an existing role assignment for a user, group, or service principal.

az role assignment update --role-assignment

Examples

Update a role assignment from a JSON file.

az role assignment update --role-assignment assignment.json

Update a role assignment from a JSON string. (Bash)

az role assignment update --role-assignment '{
    "canDelegate": null,
    "condition": "@Resource[Microsoft.Storage/storageAccounts/blobServices/containers:Name] stringEquals '"'"'foo'"'"'",
    "conditionVersion": "2.0",
    "description": "Role assignment foo to check on bar",
    "id": "/subscriptions/00000001-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.Authorization/roleAssignments/3eabdd43-375b-4dbd-8dc4-04acd15ce56b",
    "name": "3eabdd43-375b-4dbd-8dc4-04acd15ce56b",
    "principalId": "00000002-0000-0000-0000-000000000000",
    "principalType": "User",
    "resourceGroup": "rg1",
    "roleDefinitionId": "/subscriptions/00000001-0000-0000-0000-000000000000/providers/Microsoft.Authorization/roleDefinitions/acdd72a7-3385-48ef-bd42-f606fba81ae7",
    "scope": "/subscriptions/00000001-0000-0000-0000-000000000000/resourceGroups/rg1",
    "type": "Microsoft.Authorization/roleAssignments"
}'

Required Parameters

--role-assignment

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

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc

Default value: json

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Share via

az role assignment

Commands

az role assignment create

Examples

Required Parameters

Optional Parameters

az role assignment delete

Examples

Optional Parameters

az role assignment list

Examples

Optional Parameters

az role assignment list-changelogs

Optional Parameters

az role assignment update

Examples

Required Parameters