Azure Policy definitions, hands-on

A rule engine in front of every change

Every create, update and delete in Azure passes through Azure Resource Manager, whether it comes from the portal, the CLI, Terraform or a software development kit. Azure Policy is the rule engine inside that path. A policy definition is a JSON document that pairs a condition with an effect: if a resource looks like this, deny the request, or record the resource as non-compliant, or change it, or deploy something beside it. An assignment applies a definition to a scope, which is a management group, a subscription, a resource group or a single resource. From then on Azure checks every matching request against it and re-checks existing resources on a schedule.

Platform and cloud security teams write policy to set guardrails that hold whichever tool a team deploys with. Governance, risk and compliance (GRC) engineers assign Microsoft's regulatory compliance initiatives, such as those for the Center for Internet Security (CIS) benchmarks, the US National Institute of Standards and Technology's Special Publication 800-53 and the Payment Card Industry Data Security Standard (PCI DSS), which are collections of policy definitions assigned like any other. Either way, someone has to read and write the definition language, and that is what this page teaches, with one running example: a rule against Secure Shell (SSH) open to the internet on a network security group, written wrong first and then right, in a throwaway resource group.

Five ways a policy silently does nothing

These five never produce an error. Each one leaves an assignment in place that looks like a control, with a compliance page to match. The walk-through below reproduces all five in one resource group, and fixes them.

1. Indexed mode on a type that cannot be tagged. A definition in Indexed mode evaluates only resource types that support tags and location. Resource groups, subscriptions and child resources such as the rules inside a network security group are never evaluated. A definition created without a mode gets Indexed: that is the API's default, and so the Azure CLI's when you pass only the rule, even if the file you took it from says All.
2. An audit effect read as enforcement. audit writes a warning to the activity log and marks the resource non-compliant, and the request goes through. Fifty audit assignments report problems and stop none of them.
3. A condition on a property that is absent. A field condition reads a property from the request or the stored resource. If the property is not in that JSON, a comparison such as equals is false, the resource does not match, and it is reported compliant. Network security group rules carry ports as either destinationPortRange or destinationPortRanges, never both, so a policy written against one form passes every rule written in the other.
4. An assignment in DoNotEnforce mode. The assignment is evaluated and reports non-compliance, but its effect never runs and nothing reaches the activity log. It is the right way to trial a deny and an easy setting to forget.
5. Resources that already existed. deny, append and modify act on create and update requests. Resources that already break the rule are marked non-compliant and left as they are until someone changes them, or until a remediation task runs, which only modify and deployIfNotExists support.

One failure runs the other way. If a template function inside a condition errors, for example substring() asked for three characters of a two-character name, the evaluation fails, and Azure treats a failed evaluation as a deny. A typo there blocks deployments instead of letting them through.

Anatomy of a definition

Here is the first attempt at the running example, as it would sit in a repository. It is meant to deny any network security group rule that lets SSH in from anywhere, and step 5 of the walk-through shows why it does not.

{
  "properties": {
    "displayName": "Deny SSH from the internet (first attempt)",
    "mode": "All",
    "policyRule": {
      "if": {
        "allOf": [
          { "field": "type", "equals": "Microsoft.Network/networkSecurityGroups/securityRules" },
          { "field": "Microsoft.Network/networkSecurityGroups/securityRules/access", "equals": "Allow" },
          { "field": "Microsoft.Network/networkSecurityGroups/securityRules/direction", "equals": "Inbound" },
          { "field": "Microsoft.Network/networkSecurityGroups/securityRules/destinationPortRange", "equals": "22" },
          { "field": "Microsoft.Network/networkSecurityGroups/securityRules/sourceAddressPrefix", "in": ["*", "Internet", "0.0.0.0/0"] }
        ]
      },
      "then": { "effect": "deny" }
    }
  }
}

The parts:

• displayName, with optional description and metadata, describe the definition. Its name and ID are not in the file: they belong to the resource the definition becomes when you create it, under a management group or a subscription. That location also limits where it can be assigned.
• mode decides which resource types are evaluated at all. All covers resource groups, subscriptions and every resource type. Indexed covers only types that support tags and location. Microsoft recommends All in most cases and Indexed for policies that enforce tags or location, so that resources unable to carry them don't fill the report as non-compliant. A rule on resource groups or subscriptions needs All. There are also resource provider modes, such as Microsoft.Kubernetes.Data for Kubernetes clusters and Microsoft.KeyVault.Data for the keys, secrets and certificates inside Key Vault, which the service itself evaluates.
• policyRule holds if, the condition, and then, which names one effect.
• parameters, absent here, declare values that each assignment fills in, each with a type and optionally allowedValues and a defaultValue. A rule reads one as [parameters('name')]. The corrected definition in step 4 makes its effect a parameter, so the same definition can be assigned as Audit in one place and Deny in another.

Fields and aliases

A condition starts with what it reads. field reads from the resource. A few names work on every resource type: type, name, fullName, kind, location, id, identity.type, and tags or tags['owner']. Everything else is reached through an alias. Microsoft.Network/networkSecurityGroups/securityRules/destinationPortRange is an alias for the path properties.destinationPortRange inside a rule, and Azure keeps that mapping for each API (application programming interface) version, so one definition works whichever version a client sends.

Aliases come from each resource provider. List them for one resource type:

az provider show --namespace Microsoft.Network --expand "resourceTypes/aliases" --query "resourceTypes[?resourceType=='networkSecurityGroups/securityRules'].aliases[].name" -o tsv

The first lines of that list on 3 November 2026:

Microsoft.Network/networkSecurityGroups/securityRules/protocol
Microsoft.Network/networkSecurityGroups/securityRules/sourcePortRange
Microsoft.Network/networkSecurityGroups/securityRules/sourcePortRanges[*]
Microsoft.Network/networkSecurityGroups/securityRules/destinationPortRange
Microsoft.Network/networkSecurityGroups/securityRules/destinationPortRanges[*]

A rule has no tags alias because a rule cannot be tagged, which is why Indexed mode skips it. Only some aliases can be written by the modify effect, and Azure marks those Modifiable. Filter for them:

az provider show --namespace Microsoft.Network --expand "resourceTypes/aliases" --query "resourceTypes[?resourceType=='networkSecurityGroups/securityRules'].aliases[] | [?defaultMetadata.attributes=='Modifiable'].name" -o tsv

Microsoft's Azure Policy extension for Visual Studio Code also shows the alias for a property when you hover over it in a resource's JSON. If a property has no alias, no condition can read it.

Conditions and logic

A condition is a field (or a value) and one operator: equals, notEquals, in, notIn, like and notLike (with one * wildcard), contains, containsKey, exists, less, greater and their OrEquals forms, and match, where # stands for a digit, ? for a letter and . for any character. String comparisons ignore case, except match and notMatch, which have matchInsensitively forms. Conditions combine with allOf (and), anyOf (or) and not, nested as deep as you need.

Use value in place of field to test the result of a template function or a parameter. Most Azure Resource Manager template functions are available, plus a few that exist only in policy: field(), current(), ipRangeContains(), addDays(), policy() and requestContext().apiVersion. This is where the fail-closed case lives: a function that errors fails the evaluation, which counts as a deny. Wrap risky calls in if(), as Microsoft's own example does:

{
  "value": "[if(greaterOrEquals(length(field('name')), 3), substring(field('name'), 0, 3), 'not starting with abc')]",
  "equals": "abc"
}

Arrays and count

An alias ending in [*] selects every member of an array, and a plain field condition on it is true only when every member satisfies it. So destinationPortRanges[*] equals "22" is false for a rule allowing 22 and 443, and true for a rule with no port list at all, because no member breaks it. That is rarely the question you meant. count asks the question directly: it evaluates its where condition once for each member and compares the number that matched.

{
  "count": {
    "field": "Microsoft.Network/networkSecurityGroups/securityRules/destinationPortRanges[*]",
    "where": {
      "field": "Microsoft.Network/networkSecurityGroups/securityRules/destinationPortRanges[*]",
      "in": ["22", "*"]
    }
  },
  "greater": 0
}

Inside where, the same alias refers to the one member being counted. A value count does the same over a literal array or an array parameter, naming the current member with name and reading it with current(). A rule may hold up to five field counts per array and ten value counts.

Effects

Each definition has exactly one effect. The effect decides what a match does, and when.

Three more are specialised: manual lets a person attest compliance, as in regulatory initiatives; mutate changes Kubernetes objects in Azure Kubernetes Service; and addToNetworkGroup serves Azure Virtual Network Manager.

When several assignments apply to one request, Azure evaluates each independently, and the result is the most restrictive. Within a request, disabled is checked first, then append and modify, then deny, then audit, so a modify can make a request compliant before a deny sees it. auditIfNotExists and deployIfNotExists run after the resource provider reports success.

The two existence effects carry their target in details. This rule audits key vaults that have no diagnostic setting sending any logs, in the shape Microsoft's built-in Key Vault definitions use:

{
  "if": { "field": "type", "equals": "Microsoft.KeyVault/vaults" },
  "then": {
    "effect": "auditIfNotExists",
    "details": {
      "type": "Microsoft.Insights/diagnosticSettings",
      "existenceCondition": {
        "count": {
          "field": "Microsoft.Insights/diagnosticSettings/logs[*]",
          "where": { "field": "Microsoft.Insights/diagnosticSettings/logs[*].enabled", "equals": "true" }
        },
        "greaterOrEquals": 1
      }
    }
  }
}

modify and deployIfNotExists change resources, so their details must list roleDefinitionIds, the roles their changes need. An assignment of either needs a managed identity holding those roles. Remediation tasks and deployIfNotExists deployments run as that identity, while evaluation always uses the identity of whoever sent the request. The portal grants the roles when it creates the assignment; the CLI and the software development kits do not, unless you ask, as step 5 does.

denyAction has edges worth knowing before relying on it: deleting a parent still deletes its children and extension resources, so protecting a diagnostic setting does not stop someone deleting the storage account it belongs to; and when a whole resource group is deleted, only a definition in Indexed mode can block it, through its cascadeBehaviors setting; one in All mode never does.

Assignments, initiatives and when evaluation runs

A definition does nothing until it is assigned. An assignment names the definition and a scope, and everything below that scope inherits it: assigned at a management group, it applies to every subscription, resource group and resource underneath. The assignment also carries:

• Parameters, the values for this scope, such as {"effect": {"value": "Deny"}}.
• enforcementMode: Default applies the effect. DoNotEnforce evaluates and reports but never applies the effect on create or update and writes no activity log entry; remediation tasks can still be run. Enroll enforces only for scopes that opt in through enrollment resources, for staged roll-outs.
• Exclusions (notScopes), scopes removed from evaluation entirely.
• Non-compliance messages, shown to whoever is denied. A denial that says what to fix saves a ticket.
• An identity, for modify and deployIfNotExists, plus a location when it is system-assigned.

Microsoft recommends exclusions for broad, permanent bypasses, such as a test environment, and exemptions for specific or time-bound ones. For an exception to a security control, prefer the exemption. An excluded scope drops out of the compliance report and is visible only in the assignment's notScopes; an exempted resource stays in the report as Exempt, can carry an expiry date, and creating one needs a permission on the assignment itself, so the exception stays visible and reviewable.

An initiative (a policy set definition) groups definitions so they are assigned, parameterised and reported together. Microsoft's regulatory compliance initiatives are initiatives with hundreds of members. This one wraps the corrected SSH rule from the walk-through and passes its own parameter through:

{
  "properties": {
    "displayName": "Network guardrails",
    "parameters": {
      "sshEffect": { "type": "String", "allowedValues": ["Audit", "Deny", "Disabled"], "defaultValue": "Audit" }
    },
    "policyDefinitions": [
      {
        "policyDefinitionReferenceId": "noInternetSsh",
        "policyDefinitionId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/policyDefinitions/csoh-lab-ssh",
        "parameters": { "effect": { "value": "[parameters('sshEffect')]" } }
      }
    ]
  }
}

Evaluation happens at these moments, according to Microsoft's documentation:

• When a resource is created or updated, in the request itself. The compliance result for that one resource appears about 15 minutes later.
• When an assignment is created or updated. It takes about five minutes to apply, then the resources in scope are evaluated.
• Once every 24 hours, in a standard compliance scan of every assignment.
• On demand: az policy state trigger-scan --resource-group <group>.

Resource types under Microsoft.Resources are never evaluated, except subscriptions and resource groups.

Walk-through

1. Know what you can test locally

Nothing on your own machine runs Azure Policy's engine. The Visual Studio Code extension can evaluate a definition against a resource, but it needs an Azure sign-in, and Microsoft documents that its evaluation feature does not work on macOS or Linux. PSRule for Azure has an experimental feature that converts policy assignments, exported from Azure, into its own rules for checking templates before deployment: useful in a pipeline, but a translation of your policy rather than Azure evaluating it. Locally you can check that a definition is well-formed JSON with the parts it needs. Whether it does what you meant is decided in Azure, so the test bed is a throwaway resource group with every assignment scoped to it.

Run the steps in one terminal: later steps reuse a variable set in step 2.

2. Choose the subscription and make the lab

az account show --query "{name:name, id:id}" -o table

Check that it is the subscription you mean to use. The definitions in steps 3 and 4 are created in it but do nothing until assigned, and every assignment is scoped to the lab resource group. Keep the subscription ID for later steps:

SUB=$(az account show --query id -o tsv)

Create the resource group, tagged with an owner that step 7 copies onto resources, and one network security group before any policy exists:

az group create --name csoh-policy-lab --location eastus --tags owner=platform-team

az network nsg create --resource-group csoh-policy-lab --name lab-nsg-before

3. Create the first attempt

Save the definition from the anatomy section as a file:

cat > ssh-naive.json <<'EOF'
{
  "properties": {
    "displayName": "Deny SSH from the internet (first attempt)",
    "mode": "All",
    "policyRule": {
      "if": {
        "allOf": [
          { "field": "type", "equals": "Microsoft.Network/networkSecurityGroups/securityRules" },
          { "field": "Microsoft.Network/networkSecurityGroups/securityRules/access", "equals": "Allow" },
          { "field": "Microsoft.Network/networkSecurityGroups/securityRules/direction", "equals": "Inbound" },
          { "field": "Microsoft.Network/networkSecurityGroups/securityRules/destinationPortRange", "equals": "22" },
          { "field": "Microsoft.Network/networkSecurityGroups/securityRules/sourceAddressPrefix", "in": ["*", "Internet", "0.0.0.0/0"] }
        ]
      },
      "then": { "effect": "deny" }
    }
  }
}
EOF

The CLI takes the parts of a definition as separate options, so pull each one out of the file with jq. This creates a definition in the subscription; it has no effect until step 5 assigns it.

az policy definition create --name csoh-lab-ssh-naive --display-name "$(jq -r .properties.displayName ssh-naive.json)" --mode "$(jq -r .properties.mode ssh-naive.json)" --rules "$(jq -c .properties.policyRule ssh-naive.json)"

4. Write the corrected rule, and create it twice

The corrected rule checks both forms of each property: the single destinationPortRange and the list destinationPortRanges, and the same for the source. It treats * (every port) like 22, and makes the effect a parameter. Like the first attempt, it judges rules created on their own, the way az network nsg rule create sends them; exercise 3 covers rules sent inside the network security group's own request.

cat > ssh.json <<'EOF'
{
  "properties": {
    "displayName": "SSH must not be open to the internet",
    "description": "Inbound Allow rules from any source must not include port 22, in either the single or the list form of the rule.",
    "mode": "All",
    "metadata": { "version": "1.0.0", "category": "Network" },
    "parameters": {
      "effect": {
        "type": "String",
        "allowedValues": ["Audit", "Deny", "Disabled"],
        "defaultValue": "Audit",
        "metadata": { "displayName": "Effect", "description": "Audit, Deny or Disabled" }
      }
    },
    "policyRule": {
      "if": {
        "allOf": [
          { "field": "type", "equals": "Microsoft.Network/networkSecurityGroups/securityRules" },
          { "field": "Microsoft.Network/networkSecurityGroups/securityRules/access", "equals": "Allow" },
          { "field": "Microsoft.Network/networkSecurityGroups/securityRules/direction", "equals": "Inbound" },
          {
            "anyOf": [
              { "field": "Microsoft.Network/networkSecurityGroups/securityRules/destinationPortRange", "in": ["22", "*"] },
              {
                "count": {
                  "field": "Microsoft.Network/networkSecurityGroups/securityRules/destinationPortRanges[*]",
                  "where": {
                    "field": "Microsoft.Network/networkSecurityGroups/securityRules/destinationPortRanges[*]",
                    "in": ["22", "*"]
                  }
                },
                "greater": 0
              }
            ]
          },
          {
            "anyOf": [
              { "field": "Microsoft.Network/networkSecurityGroups/securityRules/sourceAddressPrefix", "in": ["*", "Internet", "0.0.0.0/0"] },
              {
                "count": {
                  "field": "Microsoft.Network/networkSecurityGroups/securityRules/sourceAddressPrefixes[*]",
                  "where": {
                    "field": "Microsoft.Network/networkSecurityGroups/securityRules/sourceAddressPrefixes[*]",
                    "in": ["*", "Internet", "0.0.0.0/0"]
                  }
                },
                "greater": 0
              }
            ]
          }
        ]
      },
      "then": { "effect": "[parameters('effect')]" }
    }
  }
}
EOF

Create it the careful way, with the mode from the file:

az policy definition create --name csoh-lab-ssh --display-name "$(jq -r .properties.displayName ssh.json)" --mode "$(jq -r .properties.mode ssh.json)" --params "$(jq -c .properties.parameters ssh.json)" --rules "$(jq -c .properties.policyRule ssh.json)"

Then create it again the way most people first do, passing the rule and parameters and nothing else:

az policy definition create --name csoh-lab-ssh-indexed --params "$(jq -c .properties.parameters ssh.json)" --rules "$(jq -c .properties.policyRule ssh.json)"

az policy definition show --name csoh-lab-ssh-indexed --query mode -o tsv

Expect Indexed: Azure CLI 2.91.0 documents Indexed as the default for --mode, and nothing in the rule says otherwise. Same rule, same file, and as step 5 shows, this one never evaluates a single network security group rule.

The last definition copies the resource group's owner tag onto any resource that lacks one. It is a modify policy, so it names the role its change needs: Tag Contributor.

cat > inherit-owner.json <<'EOF'
{
  "properties": {
    "displayName": "Inherit the owner tag from the resource group",
    "mode": "Indexed",
    "policyRule": {
      "if": {
        "allOf": [
          { "field": "tags['owner']", "exists": "false" },
          { "value": "[resourceGroup().tags['owner']]", "notEquals": "" }
        ]
      },
      "then": {
        "effect": "modify",
        "details": {
          "roleDefinitionIds": [
            "/providers/Microsoft.Authorization/roleDefinitions/4a9ae827-6dc8-4573-8ac7-8239d42aa03f"
          ],
          "operations": [
            { "operation": "add", "field": "tags['owner']", "value": "[resourceGroup().tags['owner']]" }
          ]
        }
      }
    }
  }
}
EOF

Here Indexed is correct: only resources that can carry tags should be judged on one.

az policy definition create --name csoh-lab-inherit-owner --display-name "$(jq -r .properties.displayName inherit-owner.json)" --mode "$(jq -r .properties.mode inherit-owner.json)" --rules "$(jq -c .properties.policyRule inherit-owner.json)"

5. Assign everything to the lab, and test

Every command here names the resource group. Without --resource-group or --scope, az policy assignment create assigns at the whole subscription.

az policy assignment create --name lab-ssh-naive --policy csoh-lab-ssh-naive --resource-group csoh-policy-lab

az policy assignment create --name lab-ssh-indexed --policy csoh-lab-ssh-indexed --resource-group csoh-policy-lab --params '{"effect": {"value": "Deny"}}'

az policy assignment create --name lab-ssh-audit --policy csoh-lab-ssh --resource-group csoh-policy-lab --params '{"effect": {"value": "Audit"}}'

az policy assignment create --name lab-ssh-trial --policy csoh-lab-ssh --resource-group csoh-policy-lab --params '{"effect": {"value": "Deny"}}' --enforcement-mode DoNotEnforce

The tag policy gets a system-assigned managed identity, granted Tag Contributor on the lab group only:

az policy assignment create --name lab-inherit-owner --policy csoh-lab-inherit-owner --resource-group csoh-policy-lab --mi-system-assigned --location eastus --role "Tag Contributor" --identity-scope "/subscriptions/$SUB/resourceGroups/csoh-policy-lab"

So four assignments carry an SSH rule: the first attempt as a deny, the corrected rule as a deny in Indexed mode, the corrected rule as an audit, and the corrected rule as a deny that is not enforced. Assignments take about five minutes to apply. Then try the plainest violation, SSH from anywhere, with one port:

az network nsg rule create --resource-group csoh-policy-lab --nsg-name lab-nsg-before --name allow-ssh --priority 100 --direction Inbound --access Allow --protocol Tcp --source-address-prefixes '*' --destination-port-ranges 22

This should fail with RequestDisallowedByPolicy, and the error lists the assignments that denied it. Expect lab-ssh-naive alone. lab-ssh-trial matches too but is not enforced, and lab-ssh-indexed never looked. If the rule is created instead, the assignments have not applied yet: delete it with az network nsg rule delete --resource-group csoh-policy-lab --nsg-name lab-nsg-before --name allow-ssh, wait a few minutes and try again.

Now the same rule as someone who also wants web traffic on port 443 would write it, with two ports:

az network nsg rule create --resource-group csoh-policy-lab --nsg-name lab-nsg-before --name allow-ssh-https --priority 110 --direction Inbound --access Allow --protocol Tcp --source-address-prefixes '*' --destination-port-ranges 22 443 --query "{name:name, destinationPortRange:destinationPortRange, destinationPortRanges:destinationPortRanges}"

Expect it to be created: SSH open to the internet in a resource group with four assignments that carry a rule against it. The output shows why the first attempt missed it: given more than one port, the CLI sends the list form, destinationPortRanges, and leaves destinationPortRange out. The first attempt's condition on destinationPortRange has nothing to compare, so it is false. lab-ssh-indexed has the right condition but never evaluates rules. lab-ssh-audit matched and let it through, because that is what audit does, and lab-ssh-trial matched and is not enforced.

Create a second network security group, now that the tag policy is assigned. The modify effect should add the tag in the request itself:

az network nsg create --resource-group csoh-policy-lab --name lab-nsg-after --query "NewNSG.tags"

Expect {"owner": "platform-team"}. Then ask for a compliance scan of the lab, which can take several minutes, and read the results:

az policy state trigger-scan --resource-group csoh-policy-lab

az policy state list --resource-group csoh-policy-lab --query "[].{assignment:policyAssignmentName, state:complianceState, resource:resourceId}" -o table

Look at the rows for allow-ssh-https. lab-ssh-naive evaluated it and calls it Compliant: that is the absent-property failure, recorded as a pass. lab-ssh-audit and lab-ssh-trial call it NonCompliant, which is the corrected rule working, reported and not enforced. lab-ssh-indexed has no row for any rule: it was never evaluated. And lab-nsg-before is NonCompliant for lab-inherit-owner, because it existed before the policy did.

6. Enforce the corrected rule

The trial assignment reported what it would have blocked. Switch it to enforcing:

az policy assignment update --name lab-ssh-trial --resource-group csoh-policy-lab --enforcement-mode Default

After a few minutes, try a two-port rule again:

az network nsg rule create --resource-group csoh-policy-lab --nsg-name lab-nsg-before --name allow-ssh-rdp --priority 120 --direction Inbound --access Allow --protocol Tcp --source-address-prefixes '*' --destination-port-ranges 22 3389

Expect RequestDisallowedByPolicy from lab-ssh-trial. Note what has not changed: allow-ssh-https is still there and SSH is still open. A deny stops new requests and leaves existing resources as they are, so the cleanup of what is already wrong is a separate job: a remediation task where the effect supports one, and a person where it does not.

One request shape is still not covered. An Azure Resource Manager template, a Bicep file or Terraform's inline security_rule blocks can send rules inside the network security group's own request, and that request's type is Microsoft.Network/networkSecurityGroups, so this definition's first condition is false for it. Exercise 3 adds the branch that reads the group's own list of rules.

7. Remediate the existing resource

lab-nsg-before has no owner tag, and will not get one until something changes it. A remediation task applies the modify operation to existing non-compliant resources, using the assignment's identity:

az policy remediation create --name lab-fix-owner --policy-assignment lab-inherit-owner --resource-group csoh-policy-lab

az policy remediation show --name lab-fix-owner --resource-group csoh-policy-lab --query "{state:provisioningState, deployments:deploymentStatus}"

az network nsg show --resource-group csoh-policy-lab --name lab-nsg-before --query tags

When the task reports Succeeded, the tag is {"owner": "platform-team"}. Had the identity lacked Tag Contributor on this group, the task would have failed, which is the usual result of creating a modify assignment from the CLI without --role.

8. Clean up

Remove the identity's role assignment first, while the identity still exists:

PRINCIPAL=$(az policy assignment show --name lab-inherit-owner --resource-group csoh-policy-lab --query identity.principalId -o tsv)

az role assignment delete --assignee-object-id "$PRINCIPAL" --role "Tag Contributor" --scope "/subscriptions/$SUB/resourceGroups/csoh-policy-lab"

for a in lab-ssh-naive lab-ssh-indexed lab-ssh-audit lab-ssh-trial lab-inherit-owner; do az policy assignment delete --name $a --resource-group csoh-policy-lab; done

for d in csoh-lab-ssh-naive csoh-lab-ssh-indexed csoh-lab-ssh csoh-lab-inherit-owner; do az policy definition delete --name $d; done

az group delete --name csoh-policy-lab --yes

Confirm nothing is left: the first command should print [] and the second false.

az policy definition list --query "[?starts_with(name, 'csoh-lab')].name"

az group exists --name csoh-policy-lab

Policy as code

Definitions and assignments are JSON, so they belong in a repository, reviewed in pull requests and deployed by a pipeline instead of edited in the portal. Microsoft's recommended workflow has four stages:

1. Keep each definition and its assignments as files, and have the pipeline update Azure whenever they change.
2. Assign a new or changed definition with DoNotEnforce to a scope far from production, a resource group or subscription kept for testing, and read the compliance results for false positives and false negatives. Microsoft's guidance names the cases to cover: create and update requests, compliant and non-compliant resources, and a property missing from the resource.
3. Test remediation for modify and deployIfNotExists definitions: the task succeeds, compliance updates, and the resource really changed.
4. Switch the assignment to Default, then widen its scope one environment at a time.

The pipeline is continuous integration (CI) like any other: give it its own identity, signing in through workload identity federation (OpenID Connect, OIDC) rather than with a stored secret, and only the rights it needs to write definitions and assignments. Deploy whole files, so that the mode in git is the mode in Azure. The jq extraction in step 3 does that, and so do Bicep and Terraform when the mode is written into the resource. A missing mode is filled in as Indexed by the API itself, whatever deploys the file, so a check in the pipeline should refuse a file without one. This one runs locally on the lab files, and prints nothing when all three are complete:

for f in ssh-naive.json ssh.json inherit-owner.json; do jq -e '.properties.mode and .properties.policyRule.if and .properties.policyRule.then.effect' "$f" >/dev/null || echo "incomplete: $f"; done

Before trusting its silence, make it fail once: delete the "mode" line from a copy of ssh.json, run it on the copy, and it should print the copy's name.

Role assignment conditions

Azure Policy governs what resources look like. Azure role-based access control (RBAC) governs who may act on them, and its role assignments can carry a condition, an attribute-based access control (ABAC) check that narrows what the role grants. A condition only narrows what the role grants; it cannot explicitly deny access. Conditions are available on role assignments that include Blob Storage or Queue Storage data actions, such as reading blobs only in one container or only with a given blob index tag, and on role assignments that let someone create or delete role assignments, which is where they matter most for security.

Giving someone Owner or User Access Administrator so that they can grant access lets them grant anything, including Owner. The safer delegation, from Microsoft's own example, is the Role Based Access Control Administrator role with a condition limiting which roles may be assigned and removed. This one allows only Backup Contributor and Backup Reader:

(
 (
  !(ActionMatches{'Microsoft.Authorization/roleAssignments/write'})
 )
 OR
 (
  @Request[Microsoft.Authorization/roleAssignments:RoleDefinitionId] ForAnyOfAnyValues:GuidEquals {5e467623-bb1f-42f4-a55d-6e525e11384b, a795c7a0-d4a2-40c1-ae25-d81f01202912}
 )
)
AND
(
 (
  !(ActionMatches{'Microsoft.Authorization/roleAssignments/delete'})
 )
 OR
 (
  @Resource[Microsoft.Authorization/roleAssignments:RoleDefinitionId] ForAnyOfAnyValues:GuidEquals {5e467623-bb1f-42f4-a55d-6e525e11384b, a795c7a0-d4a2-40c1-ae25-d81f01202912}
 )
)

Read each half as an if-then. !(ActionMatches{...}) is true for every action except the one named, so any other action the role grants passes straight through; only the named action has to satisfy the expression after OR. That is the shape of every condition, and it is this language's version of the absent-property failure: an action the condition does not name is not constrained at all. Microsoft's example needs two halves because the attribute comes from different places. A new assignment's role is in the request (@Request); an existing one's is on the resource (@Resource). With only the first half, the delegate could remove anyone's role assignments.

A condition can be added when the role is assigned or to an existing assignment, in the portal's condition editor or with the CLI, where az role assignment create takes --condition and --condition-version 2.0 (both marked preview in Azure CLI 2.91.0). The two role IDs above are Backup Contributor and Backup Reader; look up any role's ID with az role definition list --name "Backup Reader" --query "[0].name" -o tsv.

Hands-on exercises

Exercises 1 to 3 build on the walk-through's definitions, and 1 and 2 can be checked in the lab before you clean up. Exercise 6 is about role assignment conditions.

{
  "field": "Microsoft.Network/networkSecurityGroups/securityRules/destinationPortRanges[*]",
  "equals": "22"
}

{
  "value": "[if(and(not(empty(field('Microsoft.Network/networkSecurityGroups/securityRules/destinationPortRange'))), contains(field('Microsoft.Network/networkSecurityGroups/securityRules/destinationPortRange'), '-')), and(lessOrEquals(int(first(split(field('Microsoft.Network/networkSecurityGroups/securityRules/destinationPortRange'), '-'))), 22), greaterOrEquals(int(last(split(field('Microsoft.Network/networkSecurityGroups/securityRules/destinationPortRange'), '-'))), 22)), 'false')]",
  "equals": "true"
}

{
  "allOf": [
    { "field": "type", "equals": "Microsoft.Network/networkSecurityGroups" },
    {
      "count": {
        "field": "Microsoft.Network/networkSecurityGroups/securityRules[*]",
        "where": {
          "allOf": [
            { "field": "Microsoft.Network/networkSecurityGroups/securityRules[*].access", "equals": "Allow" },
            { "field": "Microsoft.Network/networkSecurityGroups/securityRules[*].direction", "equals": "Inbound" },
            {
              "anyOf": [
                { "field": "Microsoft.Network/networkSecurityGroups/securityRules[*].destinationPortRange", "in": ["22", "*"] },
                { "not": { "field": "Microsoft.Network/networkSecurityGroups/securityRules[*].destinationPortRanges[*]", "notIn": ["22", "*"] } }
              ]
            },
            {
              "anyOf": [
                { "field": "Microsoft.Network/networkSecurityGroups/securityRules[*].sourceAddressPrefix", "in": ["*", "Internet", "0.0.0.0/0"] },
                { "not": { "field": "Microsoft.Network/networkSecurityGroups/securityRules[*].sourceAddressPrefixes[*]", "notIn": ["*", "Internet", "0.0.0.0/0"] } }
              ]
            }
          ]
        }
      },
      "greater": 0
    }
  ]
}

{
  "properties": {
    "displayName": "Resource groups must have an owner tag",
    "mode": "All",
    "policyRule": {
      "if": {
        "allOf": [
          { "field": "type", "equals": "Microsoft.Resources/subscriptions/resourceGroups" },
          { "field": "tags['owner']", "exists": "false" }
        ]
      },
      "then": { "effect": "deny" }
    }
  }
}

Common mistakes

• Leaving the mode to a default. A definition without a mode is Indexed, whether it came from az policy definition create without --mode or from a template that left it out, and child resources, resource groups and subscriptions are then never evaluated. (Azure PowerShell defaults to All instead.) Deploy the whole file, and check the mode with az policy definition show.
• Checking one form of a property. Many resources express a setting in more than one way: a single value or a list, a newer property or an older default. Microsoft's own built-in "Storage accounts should prevent shared key access" matches when allowSharedKeyAccess does not exist or is empty, as well as when it is true, because an account with the property unset allows shared key access.
• Using a [*] field condition to mean "any member". It means every member, and it is true for an empty array. Use count.
• Treating audit as a control. It is a report. Count your assignments by effect before saying what is enforced.
• Leaving a trial in DoNotEnforce. Give every trial an end date and a named owner, and list assignments in that mode as part of review.
• Expecting a deny to clean up. Existing resources stay as they are. Plan the cleanup of what is already wrong, and use remediation tasks where the effect supports them.
• Creating a modify or deployIfNotExists assignment from the CLI without a role. The portal grants the identity its roles; the CLI does so only with --role and --identity-scope, and otherwise remediation fails.
• Assigning without a scope. az policy assignment create with neither --resource-group nor --scope assigns at the whole subscription.
• Excluding instead of exempting. An exclusion hides a scope from the report. An exemption keeps it visible, with a reason and an expiry.
• A template function that can error. A failed evaluation is a deny. Guard functions such as substring() and split() with if().