Azure Policy assignment structure

Article
09/05/2024

Policy assignments define which resources are evaluated by a policy definition or initiative. Further, the policy assignment can determine the values of parameters for that group of resources at assignment time, making it possible to reuse policy definitions that address the same resource properties with different needs for compliance.

You use JavaScript Object Notation (JSON) to create a policy assignment. The policy assignment contains elements for:

scope
policy definition ID and version
display name
description
metadata
resource selectors
overrides
enforcement mode
excluded scopes
non-compliance messages
parameters
identity

For example, the following JSON shows a sample policy assignment request in DoNotEnforce mode with parameters:

{
  "properties": {
    "displayName": "Enforce resource naming rules",
    "description": "Force resource names to begin with DeptA and end with -LC",
    "definitionVersion": "1.*.*",
    "metadata": {
      "assignedBy": "Cloud Center of Excellence"
    },
    "enforcementMode": "DoNotEnforce",
    "notScopes": [],
    "policyDefinitionId": "/subscriptions/{mySubscriptionID}/providers/Microsoft.Authorization/policyDefinitions/ResourceNaming",
    "nonComplianceMessages": [
      {
        "message": "Resource names must start with 'DeptA' and end with '-LC'."
      }
    ],
    "parameters": {
      "prefix": {
        "value": "DeptA"
      },
      "suffix": {
        "value": "-LC"
      }
    },
    "identity": {
      "type": "SystemAssigned"
    },
    "resourceSelectors": [],
    "overrides": []
  }
}

Scope

The scope used for assignment resource creation time is the primary driver of resource applicability. For more information on assignment scope, see Understand scope in Azure Policy.

Policy definition ID and version (preview)

This field must be the full path name of either a policy definition or an initiative definition. The policyDefinitionId is a string and not an array. The latest content of the assigned policy definition or initiative is retrieved each time the policy assignment is evaluated. The recommendation is that if multiple policies are often assigned together, to use an initiative instead.

For built-in definitions and initiatives, you can use specific the definitionVersion of which to assess on. By default, the version is set to the latest major version and autoingest minor and patch changes.

To autoingest any minor changes of the definition, the version number would be #.*.*. The Wildcard represents autoingesting updates.
To pin to a minor version path, the version format would be #.#.*.
All patch changes must be autoinjested for security purposes. Patch changes are limited to text changes and break glass scenarios.

Display name and description

You use displayName and description to identify the policy assignment and provide context for its use with the specific set of resources. displayName has a maximum length of 128 characters and description a maximum length of 512 characters.

Metadata

The optional metadata property stores information about the policy assignment. Customers can define any properties and values useful to their organization in metadata. However, there are some common properties used by Azure Policy. Each metadata property has a limit of 1,024 characters.

Common metadata properties

assignedBy (string): The friendly name of the security principal that created the assignment.
createdBy (string): The GUID of the security principal that created the assignment.
createdOn (string): The Universal ISO 8601 DateTime format of the assignment creation time.
updatedBy (string): The friendly name of the security principal that updated the assignment, if any.
updatedOn (string): The Universal ISO 8601 DateTime format of the assignment update time, if any.

Scenario specific metadata properties

parameterScopes (object): A collection of key-value pairs where the key matches a strongType configured parameter name and the value defines the resource scope used in Portal to provide the list of available resources by matching strongType. Portal sets this value if the scope is different than the assignment scope. If set, an edit of the policy assignment in Portal automatically sets the scope for the parameter to this value. However, the scope isn't locked to the value and it can be changed to another scope.

The following example of parameterScopes is for a strongType parameter named backupPolicyId that sets a scope for resource selection when the assignment is edited in the portal.
```
"metadata": {
    "parameterScopes": {
      "backupPolicyId": "/subscriptions/{SubscriptionID}/resourcegroups/{ResourceGroupName}"
    }
}
```

evidenceStorages (object): The recommended default storage account that should be used to hold evidence for attestations to policy assignments with a manual effect. The displayName property is the name of the storage account. The evidenceStorageAccountID property is the resource ID of the storage account. The evidenceBlobContainer property is the blob container name in which you plan to store the evidence.

{
  "properties": {
    "displayName": "A contingency plan should be in place to ensure operational continuity for each Azure subscription.",
    "policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/{definitionId}",
    "metadata": {
      "evidenceStorages": [
        {
          "displayName": "Default evidence storage",
          "evidenceStorageAccountId": "/subscriptions/{subscriptionId}/resourceGroups/{rg-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name}",
          "evidenceBlobContainer": "evidence-container"
        }
      ]
    }
  }
}

Resource selectors

The optional resourceSelectors property facilitates safe deployment practices (SDP) by enabling you to gradually roll out policy assignments based on factors like resource location, resource type, or whether a resource has a location. When resource selectors are used, Azure Policy only evaluates resources that are applicable to the specifications made in the resource selectors. Resource selectors can also be used to narrow down the scope of exemptions in the same way.

In the following example scenario, the new policy assignment is evaluated only if the resource's location is either East US or West US.

{
  "properties": {
    "policyDefinitionId": "/subscriptions/{subId}/providers/Microsoft.Authorization/policyDefinitions/ResourceLimit",
    "definitionVersion": "1.1.*",
    "resourceSelectors": [
      {
        "name": "SDPRegions",
        "selectors": [
          {
            "kind": "resourceLocation",
            "in": [
              "eastus",
              "westus"
            ]
          }
        ]
      }
    ]
  },
  "systemData": { ...
  },
  "id": "/subscriptions/{subId}/providers/Microsoft.Authorization/policyAssignments/ResourceLimit",
  "type": "Microsoft.Authorization/policyAssignments",
  "name": "ResourceLimit"
}

When you're ready to expand the evaluation scope for your policy, you just have to update the assignment. The following example shows our policy assignment with two more Azure regions added to the SDPRegions selector. Note, in this example, SDP means to Safe Deployment Practice:

{
  "properties": {
    "policyDefinitionId": "/subscriptions/{subId}/providers/Microsoft.Authorization/policyDefinitions/ResourceLimit",
    "definitionVersion": "1.1.*",
    "resourceSelectors": [
      {
        "name": "SDPRegions",
        "selectors": [
          {
            "kind": "resourceLocation",
            "in": [
              "eastus",
              "westus",
              "centralus",
              "southcentralus"
            ]
          }
        ]
      }
    ]
  },
  "systemData": { ...
  },
  "id": "/subscriptions/{subId}/providers/Microsoft.Authorization/policyAssignments/ResourceLimit",
  "type": "Microsoft.Authorization/policyAssignments",
  "name": "ResourceLimit"
}

Resource selectors have the following properties:

name: The name of the resource selector.
selectors: (Optional) The property used to determine which subset of resources applicable to the policy assignment should be evaluated for compliance.
- kind: The property of a selector that describes which characteristic narrows down the set of evaluated resources. Each kind can only be used once in a single resource selector. Allowed values are:
  - resourceLocation: This property is used to select resources based on their type. Can't be used in the same resource selector as resourceWithoutLocation.
  - resourceType: This property is used to select resources based on their type.
  - resourceWithoutLocation: This property is used to select resources at the subscription level that don't have a location. Currently only supports subscriptionLevelResources. Can't be used in the same resource selector as resourceLocation.
- in: The list of allowed values for the specified kind. Can't be used with notIn. Can contain up to 50 values.
- notIn: The list of not-allowed values for the specified kind. Can't be used with in. Can contain up to 50 values.

A resource selector can contain multiple selectors. To be applicable to a resource selector, a resource must meet requirements specified by all its selectors. Further, up to 10 resourceSelectors can be specified in a single assignment. In-scope resources are evaluated when they satisfy any one of these resource selectors.

Overrides

The optional overrides property allows you to change the effect of a policy definition without changing the underlying policy definition or using a parameterized effect in the policy definition.

A common use case for overrides on effect is policy initiatives with a large number of associated policy definitions. In this situation, managing multiple policy effects can consume significant administrative effort, especially when the effect needs to be updated from time to time. Overrides can be used to simultaneously update the effects of multiple policy definitions within an initiative.

Let's take a look at an example. Imagine you have a policy initiative named CostManagement that includes a custom policy definition with policyDefinitionReferenceId corpVMSizePolicy and a single effect of audit. Suppose you want to assign the CostManagement initiative, but don't yet want to see compliance reported for this policy. This policy's audit effect can be replaced by disabled through an override on the initiative assignment, as shown in the following sample:

{
  "properties": {
    "policyDefinitionId": "/subscriptions/{subId}/providers/Microsoft.Authorization/policySetDefinitions/CostManagement",
    "overrides": [
      {
        "kind": "policyEffect",
        "value": "disabled",
        "selectors": [
          {
            "kind": "policyDefinitionReferenceId",
            "in": [
              "corpVMSizePolicy"
            ]
          }
        ]
      }
    ]
  },
  "systemData": { ...
  },
  "id": "/subscriptions/{subId}/providers/Microsoft.Authorization/policyAssignments/CostManagement",
  "type": "Microsoft.Authorization/policyAssignments",
  "name": "CostManagement"
}

Another common use case for overrides is rolling out a new version of a definition. For recommended steps on safely updating an assignment version, see Policy Safe deployment.

Overrides have the following properties:

kind: The property the assignment overrides. The supported kinds are policyEffect and policyVersion.
value: The new value that overrides the existing value. For kind: policyEffect, the supported values are effects. For kind: policyVersion, the supported version number must be greater than or equal to the definitionVersion specified in the assignment.
selectors: (Optional) The property used to determine what scope of the policy assignment should take on the override.
- kind: The property of a selector that describes which characteristic narrows down the scope of the override. Allowed values for kind: policyEffect:
  - policyDefinitionReferenceId: This property specifies which policy definitions within an initiative assignment should take on the effect override.
  - resourceLocation: This property is used to select resources based on their type. Can't be used in the same resource selector as resourceWithoutLocation.
  Allowed value for kind: policyVersion:
  - resourceLocation: This property is used to select resources based on their type. Can't be used in the same resource selector as resourceWithoutLocation.
- in: The list of allowed values for the specified kind. Can't be used with notIn. Can contain up to 50 values.
- notIn: The list of not-allowed values for the specified kind. Can't be used with in. Can contain up to 50 values.

One override can be used to replace the effect of many policies by specifying multiple values in the policyDefinitionReferenceId array. A single override can be used for up to 50 policyDefinitionReferenceId, and a single policy assignment can contain up to 10 overrides, evaluated in the order in which they're specified. Before the assignment is created, the effect chosen in the override is validated against the policy rule and parameter allowed value list (in cases where the effect is parameterized).

Enforcement mode

The enforcementMode property provides customers the ability to test the outcome of a policy on existing resources without initiating the policy effect or triggering entries in the Azure Activity log.

This scenario is commonly referred to as What If and aligns to safe deployment practices. enforcementMode is different from the Disabled effect, as that effect prevents resource evaluation from happening at all.

This property has the following values:

Mode	JSON Value	Type	Remediate manually	Activity log entry	Description
Enabled	Default	string	Yes	Yes	The policy effect is enforced during resource creation or update.
Disabled	DoNotEnforce	string	Yes	No	The policy effect isn't enforced during resource creation or update.

If enforcementMode isn't specified in a policy or initiative definition, the value Default is used. Remediation tasks can be started for deployIfNotExists policies, even when enforcementMode is set to DoNotEnforce.

Excluded scopes

The scope of the assignment includes all child resource containers and child resources. If a child resource container or child resource shouldn't have the definition applied, each can be excluded from evaluation by setting notScopes. This property is an array to enable excluding one or more resource containers or resources from evaluation. notScopes can be added or updated after creation of the initial assignment.

Note

An excluded resource is different from an exempted resource. For more information, see Understand scope in Azure Policy.

Non-compliance messages

To set a custom message that describes why a resource is non-compliant with the policy or initiative definition, set nonComplianceMessages in the assignment definition. This node is an array of message entries. This custom message is in addition to the default error message for non-compliance and is optional.

Important

Custom messages for non-compliance are only supported on definitions or initiatives with Resource Manager modes definitions.

"nonComplianceMessages": [
  {
    "message": "Default message"
  }
]

If the assignment is for an initiative, different messages can be configured for each policy definition in the initiative. The messages use the policyDefinitionReferenceId value configured in the initiative definition. For more information, see policy definitions properties.

"nonComplianceMessages": [
  {
    "message": "Default message"
  },
  {
    "message": "Message for just this policy definition by reference ID",
    "policyDefinitionReferenceId": "10420126870854049575"
  }
]

Parameters

This segment of the policy assignment provides the values for the parameters defined in the policy definition or initiative definition. This design makes it possible to reuse a policy or initiative definition with different resources, but check for different business values or outcomes.

"parameters": {
  "prefix": {
    "value": "DeptA"
  },
  "suffix": {
    "value": "-LC"
  }
}

In this example, the parameters previously defined in the policy definition are prefix and suffix. This particular policy assignment sets prefix to DeptA and suffix to -LC. The same policy definition is reusable with a different set of parameters for a different department, reducing the duplication and complexity of policy definitions while providing flexibility.

Identity

For policy assignments with effect set to deployIfNotExists or modify, the requirement is to have an identity property to do remediation on non-compliant resources. When an assignment uses an identity, the user must also specify a location for the assignment.