Add or edit Azure role assignment conditions using the REST API

  • Article

An Azure role assignment condition is an additional check that you can optionally add to your role assignment to provide more fine-grained access control. For example, you can add a condition that requires an object to have a specific tag to read the object. This article describes how to add, edit, list, or delete conditions for your role assignments using the REST API.

Prerequisites

You must use the following versions:

  • 2020-03-01-preview or later
  • 2020-04-01-preview or later if you want to utilize the description property for role assignments
  • 2022-04-01 is the first stable version

For more information about the prerequisites to add or edit role assignment conditions, see Conditions prerequisites.

Add a condition

To add a role assignment condition, use the Role Assignments - Create REST API. Role Assignments - Create includes the following parameters related to conditions.

Parameter Type Description
condition String Condition under which the user can be granted permission.
conditionVersion String Version of the condition syntax. If condition is specified without conditionVersion, the version is set to the default value of 2.0.

Use the following request and body:

PUT https://management.chinacloudapi.cn/{scope}/providers/Microsoft.Authorization/roleAssignments/{roleAssignmentId}?api-version=2022-04-01

{
    "properties": {
        "roleDefinitionId": "/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}",
        "principalId": "{principalId}",
        "condition": "{condition}",
        "conditionVersion": "2.0",
        "description": "{description}"
    }
}

The following example shows how to assign the Storage Blob Data Reader role with a condition. The condition checks whether container name equals 'blobs-example-container'.

PUT https://management.chinacloudapi.cn/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Authorization/roleAssignments/{roleAssignmentId}?api-version=2022-04-01

{
    "properties": {
        "roleDefinitionId": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Authorization/roleDefinitions/2a2b9908-6ea1-4ae2-8e65-a410df84e7d1",
        "principalId": "{principalId}",
        "condition": "((!(ActionMatches{'Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read'})) OR (@Resource[Microsoft.Storage/storageAccounts/blobServices/containers:name] StringEquals 'blobs-example-container'))",
        "conditionVersion": "2.0",
        "description": "Read access if container name equals blobs-example-container"
    }
}

The following shows an example of the output:

{
    "properties": {
        "roleDefinitionId": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Authorization/roleDefinitions/2a2b9908-6ea1-4ae2-8e65-a410df84e7d1",
        "principalId": "{principalId}",
        "principalType": "User",
        "scope": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}",
        "condition": "((!(ActionMatches{'Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read'})) OR (@Resource[Microsoft.Storage/storageAccounts/blobServices/containers:name] StringEquals 'blobs-example-container'))",
        "conditionVersion": "2.0",
        "createdOn": "2022-07-20T06:20:44.0205560Z",
        "updatedOn": "2022-07-20T06:20:44.2955371Z",
        "createdBy": null,
        "updatedBy": "{updatedById}",
        "delegatedManagedIdentityResourceId": null,
        "description": "Read access if container name equals blobs-example-container"
    },
    "id": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Authorization/roleAssignments/{roleAssignmentId}",
    "type": "Microsoft.Authorization/roleAssignments",
    "name": "{roleAssignmentId}"
}

Edit a condition

To edit an existing role assignment condition, use the same Role Assignments - Create REST API as you used to add the role assignment condition. The following shows an example JSON where condition and description are updated. Only the condition, conditionVersion, and description properties can be edited. You must specify the other properties to match the existing role assignment.

PUT https://management.chinacloudapi.cn/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Authorization/roleAssignments/{roleAssignmentId}?api-version=2022-04-01

{
    "properties": {
        "roleDefinitionId": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Authorization/roleDefinitions/2a2b9908-6ea1-4ae2-8e65-a410df84e7d1",
        "principalId": "{principalId}",
        "condition": "((!(ActionMatches{'Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read'})) OR (@Resource[Microsoft.Storage/storageAccounts/blobServices/containers:name] StringEquals 'blobs-example-container' OR @Resource[Microsoft.Storage/storageAccounts/blobServices/containers:name] StringEquals 'blobs-example-container2'))",
        "conditionVersion": "2.0",
        "description": "Read access if container name equals blobs-example-container or blobs-example-container2"
    }
}

List a condition

To list a role assignment condition, use the Role Assignments Get or List REST API. For more information, see List Azure role assignments using the REST API.

Delete a condition

To delete a role assignment condition, edit the role assignment condition and set both the condition and condition version to either an empty string or null.

Alternatively, if you want to delete both the role assignment and the condition, you can use the Role Assignments - Delete API. For more information, see Remove Azure role assignments.

Next steps