Skip to content

Files

Latest commit

rolyonrolyon
Update dates
May 15, 2022
948dd62 · May 15, 2022

History

History
497 lines (384 loc) · 22.7 KB

conditions-format.md

File metadata and controls

497 lines (384 loc) · 22.7 KB
title description services author ms.service ms.subservice ms.topic ms.workload ms.date ms.author
Azure role assignment condition format and syntax (preview) - Azure RBAC
Get an overview of the format and syntax of Azure role assignment conditions for Azure attribute-based access control (Azure ABAC).
active-directory
rolyon
role-based-access-control
conditions
conceptual
identity
05/16/2022
rolyon

Azure role assignment condition format and syntax (preview)

Important

Azure ABAC and Azure role assignment conditions are currently in preview. This preview version is provided without a service level agreement, and it's not recommended for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.

A 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 the format and syntax of role assignment conditions.

Condition format

To better understand role assignment conditions, it helps to look at the format.

Simple condition

The most basic condition consists of a targeted action and an expression. An action is an operation that a user can perform on a resource type. An expression is a statement that evaluates to true or false, which determines whether the action is allowed to be performed.

The following shows the format of a simple condition.

Format of a simple condition with a single action and a single expression.

(
    (
        !(ActionMatches{'<action>'})
    )
    OR
    (
        <attribute> <operator> <value>
    )
)

The following condition has an action of "Read a blob". The expression checks whether the container name is blobs-example-container.

(
    (
        !(ActionMatches{'Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read'})
    )
    OR 
    (
        @Resource[Microsoft.Storage/storageAccounts/blobServices/containers:name]
        StringEquals 'blobs-example-container'
    )
)

Diagram showing read access to blobs with particular container name.

How a condition is evaluated

If a user tries to perform an action in the role assignment that is not <action>, !(ActionMatches) evaluates to true and the overall condition evaluates to true to allow the action to be performed.

If a user tries to perform <action> in the role assignment, !(ActionMatches) evaluates to false, so the expression is evaluated. If the expression evaluates to true, the overall condition evaluates to true to allow <action> to be performed. Otherwise, <action> is not allowed to be performed.

The following pseudo code shows another way that you can read this condition.

if a user tries to perform an action in the role assignment that does not match <action>
{
    Allow action to be performed
}
else
{
    if <attribute> <operator> <value> is true
    {
        Allow <action> to be performed
    }
    else
    {
        Do not allow <action> to be performed
    }
}

Suboperations

Some actions have suboperations. For example, the "Read a blob" data action has the suboperation "Read content from a blob with tag conditions". Conditions with suboperations have the following format.

Format for an action with a suboperation.

(
    (
        !(ActionMatches{'<action>'}
        AND
        SubOperationMatches{'<subOperation>'})

    )
    OR
    (
        <attribute> <operator> <value>
    )
)

Multiple actions

A condition can include multiple actions that you want to allow if the condition is true. If you select multiple actions for a single condition, there might be fewer attributes to choose from for your condition because the attributes must be available across the selected actions.

Format for multiple actions to allow if condition is true.

(
    (
        !(ActionMatches{'<action>'})
        AND
        !(ActionMatches{'<action>'})
    )
    OR
    (
        <attribute> <operator> <value>
    )
)

Multiple expressions

A condition can include multiple expressions. Depending on the operator, attributes can be checked against multiple values.

Format for multiple expressions using Boolean operators and multiple values.

(
    (
        !(ActionMatches{'<action>'})
    )
    OR
    (
        <attribute> <operator> <value>
        AND | OR
        <attribute> <operator> {<value>, <value>, <value>}
        AND | OR
        <attribute> <operator> <value>
    )
)

Multiple conditions

You can also combine conditions to target multiple actions.

Format for multiple conditions using Boolean operator.

(
    (
        !(ActionMatches{'<action>'})
    )
    OR
    (
        <attribute> <operator> <value>
        AND | OR
        <attribute> <operator> {<value>, <value>, <value>}
        AND | OR
        <attribute> <operator> <value>
    )
)
AND
(
    (
        !(ActionMatches{'<action>'})
    )
    OR
    (
        <attribute> <operator> <value>
        AND | OR
        <attribute> <operator> <value>
    )
)

Condition syntax

The following shows the syntax for a role assignment condition.

(
    (
        !(ActionMatches{'<action>'} AND SubOperationMatches{'<subOperation>'})
        AND
        !(ActionMatches{'<action>'} AND SubOperationMatches{'<subOperation>'})
        AND
        ...
    )
    OR
    (
        <attribute> <operator> {<value, <value>, ...}
        AND | OR
        <attribute> <operator> {<value>, <value>, ...}
        AND | OR
        ...
    )
)
AND
(
    (
        !(ActionMatches{'<action>'} AND SubOperationMatches{'<subOperation>'})
        AND
        !(ActionMatches{'<action>'} AND SubOperationMatches{'<subOperation>'})
        AND
        ...
    )
    OR
    (
        <attribute> <operator> {<value, <value>, ...}
        AND | OR
        <attribute> <operator> {<value>, <value>, ...}
        AND | OR
        ...
    )
)
AND
...

Actions

Currently, conditions can be added to built-in or custom role assignments that have blob storage or queue storage data actions. These include the following built-in roles:

For a list of the blob storage actions you can use in conditions, see Actions and attributes for Azure role assignment conditions in Azure Storage (preview).

Attributes

Depending on the selected actions, the attribute might be found in different places. If you select multiple actions for a single condition, there might be fewer attributes to choose from for your condition because the attributes must be available across the selected actions. To specify an attribute, you must include the source as a prefix.

[!div class="mx-tableFixed"]

Attribute source Description Code
Resource Indicates that the attribute is on the resource, such as a container name. @Resource
Request Indicates that the attribute is part of the action request, such as setting the blob index tag. @Request
Principal Indicates that the attribute is an Azure AD custom security attribute on the principal, such as a user, enterprise application (service principal), or managed identity. @Principal

Resource and request attributes

For a list of the blob storage or queue storage attributes you can use in conditions, see:

Principal attributes

To use principal attributes, you must have all of the following:

  • Azure AD Premium P1 or P2 license
  • Azure AD permissions for signed-in user, such as the Attribute Assignment Administrator role
  • Custom security attributes defined in Azure AD

For more information about custom security attributes, see:

Function operators

This section lists the function operators that are available to construct conditions.

ActionMatches

[!div class="mx-tdCol2BreakAll"]

Property Value
Operator ActionMatches
Description Checks if the current action matches the specified action pattern.
Examples ActionMatches{'Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read'}
If the action being checked equals "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read", then true

ActionMatches{'Microsoft.Authorization/roleAssignments/*'}
If the action being checked equals "Microsoft.Authorization/roleAssignments/write", then true

ActionMatches{'Microsoft.Authorization/roleDefinitions/*'}
If the action being checked equals "Microsoft.Authorization/roleAssignments/write", then false

SubOperationMatches

[!div class="mx-tdCol2BreakAll"]

Property Value
Operator SubOperationMatches
Description Checks if the current suboperation matches the specified suboperation pattern.
Examples SubOperationMatches{'Blob.List'}

Exists

[!div class="mx-tdCol2BreakAll"]

Property Value
Operator Exists
Description Checks if the specified attribute exists.
Examples Exists @Request[Microsoft.Storage/storageAccounts/blobServices/containers/blobs:snapshot]
Attributes support Encryption scope name
Snapshot
Version ID

Logical operators

This section lists the logical operators that are available to construct conditions.

And

[!div class="mx-tdCol2BreakAll"]

Property Value
Operators AND
&&
Description And operator.
Examples !(ActionMatches{'Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read'} AND SubOperationMatches{'Blob.Read.WithTagConditions'})

Or

[!div class="mx-tdCol2BreakAll"]

Property Value
Operators OR
`
Description Or operator.
Examples @Request[Microsoft.Storage/storageAccounts/blobServices/containers/blobs:versionId] DateTimeEquals '2022-06-01T00:00:00.0Z' OR NOT Exists @Request[Microsoft.Storage/storageAccounts/blobServices/containers/blobs:versionId

Not

[!div class="mx-tdCol2BreakAll"]

Property Value
Operators NOT
!
Description Not or negation operator.
Examples NOT Exists @Request[Microsoft.Storage/storageAccounts/blobServices/containers/blobs:versionId]

Boolean comparison operators

This section lists the Boolean comparison operators that are available to construct conditions.

[!div class="mx-tdCol2BreakAll"]

Property Value
Operators BoolEquals
BoolNotEquals
Description Boolean comparison.
Examples @Resource[Microsoft.Storage/storageAccounts:isHnsEnabled] BoolEquals true

String comparison operators

This section lists the string comparison operators that are available to construct conditions.

StringEquals

[!div class="mx-tdCol2BreakAll"]

Property Value
Operators StringEquals
StringEqualsIgnoreCase
Description Case-sensitive (or case-insensitive) matching. The values must exactly match the string.
Examples @Request[Microsoft.Storage/storageAccounts/blobServices/containers/blobs/tags:Project<$key_case_sensitive$>] StringEquals 'Cascade'

StringNotEquals

[!div class="mx-tdCol2BreakAll"]

Property Value
Operators StringNotEquals
StringNotEqualsIgnoreCase
Description Negation of StringEquals (or StringEqualsIgnoreCase) operator.

StringStartsWith

[!div class="mx-tdCol2BreakAll"]

Property Value
Operators StringStartsWith
StringStartsWithIgnoreCase
Description Case-sensitive (or case-insensitive) matching. The values start with the string.

StringNotStartsWith

[!div class="mx-tdCol2BreakAll"]

Property Value
Operators StringNotStartsWith
StringNotStartsWithIgnoreCase
Description Negation of StringStartsWith (or StringStartsWithIgnoreCase) operator.

StringLike

[!div class="mx-tdCol2BreakAll"]

Property Value
Operators StringLike
StringLikeIgnoreCase
Description Case-sensitive (or case-insensitive) matching. The values can include a multi-character match wildcard (*) or a single-character match wildcard (?) anywhere in the string. If needed, these characters can be escaped by add a backslash \* and \?.
Examples @Resource[Microsoft.Storage/storageAccounts/blobServices/containers/blobs:path] StringLike 'readonly/*'

Resource[name1] StringLike 'a*c?'
If Resource[name1] equals "abcd", then true

Resource[name1] StringLike 'A*C?'
If Resource[name1] equals "abcd", then false

Resource[name1] StringLike 'a*c'
If Resource[name1] equals "abcd", then false

StringNotLike

[!div class="mx-tdCol2BreakAll"]

Property Value
Operators StringNotLike
StringNotLikeIgnoreCase
Description Negation of StringLike (or StringLikeIgnoreCase) operator.

Numeric comparison operators

This section lists the numeric comparison operators that are available to construct conditions.

[!div class="mx-tdCol2BreakAll"]

Property Value
Operators NumericEquals
NumericNotEquals
NumericGreaterThan
NumericGreaterThanEquals
NumericLessThan
NumericLessThanEquals
Description Number matching. Only integers are supported.

DateTime comparison operators

This section lists the date/time comparison operators that are available to construct conditions.

[!div class="mx-tdCol2BreakAll"]

Property Value
Operators DateTimeEquals
DateTimeNotEquals
DateTimeGreaterThan
DateTimeGreaterThanEquals
DateTimeLessThan
DateTimeLessThanEquals
Description Full-precision check with the format: yyyy-mm-ddThh:mm:ss.mmmmmmmZ. Used for blob version ID and blob snapshot.
Examples @Request[Microsoft.Storage/storageAccounts/blobServices/containers/blobs:versionId] DateTimeEquals '2022-06-01T00:00:00.0Z'

Cross product comparison operators

This section lists the cross product comparison operators that are available to construct conditions.

ForAnyOfAnyValues

[!div class="mx-tdCol2BreakAll"]

Property Value
Operators ForAnyOfAnyValues:StringEquals
ForAnyOfAnyValues:StringEqualsIgnoreCase
ForAnyOfAnyValues:StringNotEquals
ForAnyOfAnyValues:StringNotEqualsIgnoreCase
ForAnyOfAnyValues:StringLike
ForAnyOfAnyValues:StringLikeIgnoreCase
ForAnyOfAnyValues:StringNotLike
ForAnyOfAnyValues:StringNotLikeIgnoreCase
ForAnyOfAnyValues:NumericEquals
ForAnyOfAnyValues:NumericNotEquals
ForAnyOfAnyValues:NumericGreaterThan
ForAnyOfAnyValues:NumericGreaterThanEquals
ForAnyOfAnyValues:NumericLessThan
ForAnyOfAnyValues:NumericLessThanEquals
Description If at least one value on the left-hand side satisfies the comparison to at least one value on the right-hand side, then the expression evaluates to true. Has the format: ForAnyOfAnyValues:<BooleanFunction>. Supports multiple strings and numbers.
Examples @Resource[Microsoft.Storage/storageAccounts/encryptionScopes:name] ForAnyOfAnyValues:StringEquals {'validScope1', 'validScope2'}
If encryption scope name equals validScope1 or validScope2, then true.

{'red', 'blue'} ForAnyOfAnyValues:StringEquals {'blue', 'green'}
true

{'red', 'blue'} ForAnyOfAnyValues:StringEquals {'orange', 'green'}
false

ForAllOfAnyValues

[!div class="mx-tdCol2BreakAll"]

Property Value
Operators ForAllOfAnyValues:StringEquals
ForAllOfAnyValues:StringEqualsIgnoreCase
ForAllOfAnyValues:StringNotEquals
ForAllOfAnyValues:StringNotEqualsIgnoreCase
ForAllOfAnyValues:StringLike
ForAllOfAnyValues:StringLikeIgnoreCase
ForAllOfAnyValues:StringNotLike
ForAllOfAnyValues:StringNotLikeIgnoreCase
ForAllOfAnyValues:NumericEquals
ForAllOfAnyValues:NumericNotEquals
ForAllOfAnyValues:NumericGreaterThan
ForAllOfAnyValues:NumericGreaterThanEquals
ForAllOfAnyValues:NumericLessThan
ForAllOfAnyValues:NumericLessThanEquals
Description If every value on the left-hand side satisfies the comparison to at least one value on the right-hand side, then the expression evaluates to true. Has the format: ForAllOfAnyValues:<BooleanFunction>. Supports multiple strings and numbers.
Examples @Request[Microsoft.Storage/storageAccounts/blobServices/containers/blobs/tags:Project<$key_case_sensitive$>] ForAllOfAnyValues:StringEquals {'Cascade', 'Baker', 'Skagit'}

{'red', 'blue'} ForAllOfAnyValues:StringEquals {'orange', 'red', 'blue'}
true

{'red', 'blue'} ForAllOfAnyValues:StringEquals {'red', 'green'}
false

ForAnyOfAllValues

[!div class="mx-tdCol2BreakAll"]

Property Value
Operators ForAnyOfAllValues:StringEquals
ForAnyOfAllValues:StringEqualsIgnoreCase
ForAnyOfAllValues:StringNotEquals
ForAnyOfAllValues:StringNotEqualsIgnoreCase
ForAnyOfAllValues:StringLike
ForAnyOfAllValues:StringLikeIgnoreCase
ForAnyOfAllValues:StringNotLike
ForAnyOfAllValues:StringNotLikeIgnoreCase
ForAnyOfAllValues:NumericEquals
ForAnyOfAllValues:NumericNotEquals
ForAnyOfAllValues:NumericGreaterThan
ForAnyOfAllValues:NumericGreaterThanEquals
ForAnyOfAllValues:NumericLessThan
ForAnyOfAllValues:NumericLessThanEquals
Description If at least one value on the left-hand side satisfies the comparison to every value on the right-hand side, then the expression evaluates to true. Has the format: ForAnyOfAllValues:<BooleanFunction>. Supports multiple strings and numbers.
Examples {10, 20} ForAnyOfAllValues:NumericLessThan {15, 18}
true

ForAllOfAllValues

[!div class="mx-tdCol2BreakAll"]

Property Value
Operators ForAllOfAllValues:StringEquals
ForAllOfAllValues:StringEqualsIgnoreCase
ForAllOfAllValues:StringNotEquals
ForAllOfAllValues:StringNotEqualsIgnoreCase
ForAllOfAllValues:StringLike
ForAllOfAllValues:StringLikeIgnoreCase
ForAllOfAllValues:StringNotLike
ForAllOfAllValues:StringNotLikeIgnoreCase
ForAllOfAllValues:NumericEquals
ForAllOfAllValues:NumericNotEquals
ForAllOfAllValues:NumericGreaterThan
ForAllOfAllValues:NumericGreaterThanEquals
ForAllOfAllValues:NumericLessThan
ForAllOfAllValues:NumericLessThanEquals
Description If every value on the left-hand side satisfies the comparison to every value on the right-hand side, then the expression evaluates to true. Has the format: ForAllOfAllValues:<BooleanFunction>. Supports multiple strings and numbers.
Examples {10, 20} ForAllOfAllValues:NumericLessThan {5, 15, 18}
false

{10, 20} ForAllOfAllValues:NumericLessThan {25, 30}
true

{10, 20} ForAllOfAllValues:NumericLessThan {15, 25, 30}
false

Special characters

Character Description
* An asterisk (*) represents a multi-character wildcard match that can be used with Like operators. If needed, you can escape an asterisk by adding a backslash \*.
? A question mark (?) represents a single-character wildcard match that can be used with Like operators. If needed, you can escape a question mark by adding a backslash \?.
$ A dollar sign ($) is used to help delineate tag keys. In Azure PowerShell, if a string enclosed in double quotes (") includes a dollar sign, you must prefix it with a backtick (`). For example: tags:Project<`$key_case_sensitive`$>.

Grouping and precedence

If you have three or more expressions for a targeted action with different operators between the expressions, the evaluation order is ambiguous. You use parentheses () to group expressions and specify the order that the expressions are evaluated. Expressions enclosed in parentheses have higher precedence. For example, if you have the following expression:

a AND b OR c

You must add parentheses in one of the following ways:

(a AND b) OR c

a AND (b OR c)

Next steps