policy assignment managed identity

This browser is no longer supported.

Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.

az policy assignment

Manage resource policy assignments.

az policy assignment create

Create a resource policy assignment.

Create a resource policy assignment at scope

Create a resource policy assignment and provide rule parameter values.

Create a resource policy assignment with a system assigned identity.

Create a resource policy assignment with a system assigned identity. The identity will have 'Contributor' role access to the subscription.

Create a resource policy assignment with a user assigned identity.

Create a resource policy assignment with an enforcement mode. It indicates whether a policy effect will be enforced or not during assignment creation and update. Please visit https://aka.ms/azure-policyAssignment-enforcement-mode for more information.

Optional Parameters

Argument 'assign_identity' has been deprecated and will be removed in a future release.

Assigns a system assigned identity to the policy assignment. This argument will be deprecated, please use --mi-system-assigned instead.

Description of the policy assignment.

Display name of the policy assignment.

Enforcement mode of the policy assignment, e.g. Default, DoNotEnforce. Please visit https://aka.ms/azure-policyAssignment-enforcement-mode for more information.

Scope that the system assigned identity can access.

The location of the policy assignment. Only required when utilizing managed identity.

Provide this flag to use system assigned identity for policy assignment. Check out help for more examples.

UserAssigned Identity Id to be used for policy assignment. Check out help for more examples.

Name of the new policy assignment.

Space-separated scopes where the policy assignment does not apply.

JSON formatted string or a path to a file or uri with parameter values of the policy rule.

Name or id of the policy definition. If not provided, a policy set definition parameter must be provided.

Name or id of the policy set definition. If not provided, a policy definition parameter must be provided.

The resource group where the policy will be applied.

Role name or id that will be assigned to the managed identity.

Scope to which this policy assignment applies.

Argument 'sku' has been deprecated and will be removed in a future release.

Policy sku.

Increase logging verbosity to show all debug logs.

Show this help message and exit.

Only show errors, suppressing warnings.

Output format.

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

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

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

az policy assignment delete

Delete a resource policy assignment.

Delete a resource policy assignment. (autogenerated)

Required Parameters

Name of the policy assignment.

Scope at which this policy assignment subcommand applies. Defaults to current context subscription.

az policy assignment list

List resource policy assignments.

Include policy assignments either inherited from parent scope or at child scope.

az policy assignment show

Show a resource policy assignment.

Show a resource policy assignment. (autogenerated)

az policy assignment update

Update a resource policy assignment.

Update a resource policy assignment's description.

Additional resources

Policy Assignment File Folder Structure Guidelines

Assignment scopes and excluded scopes.

• CSV Assignment Parameters
• Policy Exemptions

Policy Assignments

This chapter describes how Policy Assignments are handled by EPAC. Policy Assignments are the actual assignments of Policies and Policy Sets to scopes in Azure.

Assignment JSON structure

Assignment JSON is hierarchical for efficient definitions, avoiding duplication (copy/paste) of JSON. Each branch of the tree is cumulative. Each tree node must include a nodeName - an arbitrary string exclusively used by EPAC to display an error location. EPAC concatenates a leading / and the nodeName entries encountered in the tree to create a "breadcrumbs" trail; therefore, we recommend that you use / to help separate the concatenated nodeName . The following partial and invalid assignment tree would create this error message.

JSON Schema

The GitHub repo contains a JSON schema which can be used in tools such as VS Code to provide code completion.

To utilize the schema add a $schema tag to the JSON file.

In any EPAC deployment you will have a number of assignment files. When a deployment plan is built EPAC does a recursive search for all the files in the policyAssignments folder. This means that you are free to use any folder structure you think is appropriate to help organise the files. For example if you have a multi-tenant or multi-environment setup you might choose to create folders representing each tenant or environment and then store the assignment files for each environment in that folder.

• Every tree branch must accumulate a definitionEntry (or definitionEntryList ), Assignment naming ( name and displayName ) and scope element.
• The elements parameters , overrides , resourceSelectors , notScope , enforcementMode , metadata , userAssignedIdentity , managedIdentityLocations , additionalRoleAssignments and nonComplianceMessages are optional.
• For Policy Sets with large numbers of included Policies you should use a spreadsheet (CSV file) to manage effects (parameterized or effect overrides ), parameters and optional nonComplianceMessages . We recommend the CSV approach for Policy Sets with more than 10 included Policies.
• EPAC continues to support deprecated elements initiativeId , initiativeName and ignoreBranch , Consider using their replacements policySetId , policySetName and enforcementMode instead.
• Role Assignments for user-assigned Managed Identities (UAMI) are not managed by EPAC, and will not generate a roles-plan.json file.
• additionalRoleAssignments are used when a resource required is not in the current scope. For example, a Policy Assignment that requires a Event Hub to be managed in a subscription not contained in the current management group.

The tree is not required to be balanced. The number of levels is not restricted; however, anything beyond 3 levels is unnecessary in real scenarios and would be difficult to read and manage as the depth increases.

Assignment Element and Metadata

Each Assignment is required to have a name which is used in its resource Id. EPAC also requires a displayName . The description is optional. For the allowed location assignment you specify the component with:

Multiple assignment naming components in a tree branch are string concatenated for each of the three fields.

Azure has a limit of 24 characters for the concatenated name string. EPAC displays an error if this limit is exceeded. Azure also has a limit of 128 characters for displayName and 512 characters for description (For additional information see Assignment Structure: Display name and description ).

Defining metadata

metadata is sometimes used to assign categories for changes. Do NOT specify EPAC-reserved elements roles and pacOwnerId . For the final metadata EPAC creates the union of instances in the entire tree branch.

Not recommended : Adding assignedBy to the metadata overrides the deployedBy value from the global-settings.jsonc file normally used for assignedBy . It defaults to "epac/$pacOwnerId/$pacSelector" .

Metadata for Role Assignments

Role assignments do not contain a metadata field. Instead, the description field is used to populate the deployedBy value. The description field is populated with the Policy Assignment Id, reason and deployedBy value. This is useful for tracking the source of the Role Assignment.

Reasons is one of:

• Role Assignment required by Policy - Policy definition(s) specify the required Role Definition Ids.
• additional Role Assignment - from filed "additionalRoleAssignments" in the Policy Assignment file.
• additional cross tenant Role Assignment - from filed "additionalRoleAssignments" with crossTenant set to $true in the Policy Assignment file.

Assigning Policy Sets or Policies

Assigning a single policy or policy set.

Each assignment assigns either a Policy or Policy Set. In EPAC this is done with a definitionEntry or a definitionEntryList . Exactly one occurrence must exist in any collated tree branch. For each entry, you need to specify one of the following:

• policyName - custom Policy. Specifying just the name allows EPAC to inject the correct definition scope.
• policySetName - custom Policy Set. Specifying just the name allows EPAC to inject the correct definition scope
• policyId - resource id for builtin Policy.
• policySetId - resource id for builtin Policy Set.

displayName is an optional field to document the entry if the Policy name is a GUID. Builtin Policies and Policy Sets use a GUID.

Assigning multiple Policies or Policy Sets

Using definitionEntryList allows you to save on copy/paste tree branches. Without it, the number of branches would need to be duplicated as many times as the list has entries.

Each entry in the list creates an Assignment at each leaf of the tree. Since assignments must have unique names at a specific scope, the Assignment naming component must be amended for each list entry. In this sub-component you can decide if you want to concatenate the string by appending or prepending them by specifying append boolean value.

In the above example one of the children (leaf node) has the following Assignment name.

This example generates two assignments at the "prod" leaf per scope:

• /providers/Microsoft.Management/managementGroups/ Contoso-Prod /providers/Microsoft.Authorization/policyAssignments/ pr-asb
• displayName = "Prod Azure Security Benchmark"
• description = "Prod Environment controls enforcement with Azure Security Benchmark Initiative."
• /providers/Microsoft.Management/managementGroups/ Contoso-Prod /providers/Microsoft.Authorization/policyAssignments/ pr-nist-800-53-r5
• displayName = "Prod NIST SP 800-53 Rev. 5"
• description = "Prod Environment controls enforcement with NIST SP 800-53 Rev. 5 Initiative."

scope is required exactly once in each tree branch. Excluded scopes ( notScope ) are cumulative from global-settings.json and the entire tree branch; however, once a scope is defined notScopes may not be defined at any child node.

Both scope and notScopes are specific to an EPAC Environment using the pacSelector name , e.g., epac-dev and tenant .

notScopes works the same. In addition "*" means all EPAC Environments.

Managed Identities and role assignments

Policies with a DeployIfNotExists or Modify effect need a Managed Identity (MI) and role assignments to execute remediation tasks. EPAC calculates the necessary role assignments based on the roleDefinitionIds in the policy definition. By default EPAC uses a system-assigned Managed Identity. The team maintaining EPAC recommend using system-assigned identities; however, your organization may have role assignment reasons to use user-assigned Managed Identities.

Defining managedIdentityLocations

Policy assignments requiring a Managed Identity (system-assigned or user-assigned) require a location managedIdentityLocations . You must specify the location based on EPAC Environment or use "*" to use the same location for all of the EPAC Environments. You can specify them in global-settings.jsonc or at any node in the tree. The last (closest to the leaf node) is the one chosen if multiple managedIdentityLocations entries are encountered in a tree branch.

Defining optional additionalRoleAssignments

In some scenarios you will need additionalRoleAssignments ; e.g., for diagnostics settings to Event Hubs, the target resource might be in a different Management Group and therefore the Managed Identity requires additional role assignments. You must specify the additionalRoleAssignments based on EPAC Environment or use "*" to use the same additionalRoleAssignments for all of the EPAC Environments. If the pacEnvironment under deployment is specified in the additionalRoleAssignments, the "*" assignments will be ignored.

If the additional assignment is to made to a managing tenant in the scenario where the pacEnvironment under deployment is a managed (Azure Lighthouse) tenant, you must specify ""crossTenant": true" for that assignment. Ensure all necessary ABAC permissions are in place for the executing SPN.

User-assigned Managed Identities

Azure Policy can use a user-defined Managed Identity and EPAC allows you to use this functionality. You must specify the user-defined Managed Identity based on EPAC Environment or use "*" to use the same identity for all of the EPAC Environments (only possible in single tenant scenarios). Within each EPAC Environment entry, you can specify just the URI string indicating to use the same identity even if we are using a definitionEntryList , or in the case of a definitionEntryList can assign a different identity based on the definitionEntryList by specifying a matching policyName , policyId , policySetName or policySetId .

Defining parameters , overrides and nonComplianceMessages

Utilizing a csv file to define parameters , overrides and noncompliancemessages.

Assigning single or multiple security and compliance focused Policy Sets (Initiatives), such as Microsoft Cloud Security Benchmark, NIST 800-53 R5, PCI, NIST 800-171, etc, with just JSON parameters becomes very complex. Add to this the complexity of overriding the effect if it is not surfaced as a parameter in the Policy Set . Finally, adding the optional nonComplianceMessages further increases the complexity.

To address the problem of reading and maintaining hundreds or thousands of JSON lines, EPAC can use the content of a CSV file to create parameters , overrides and optionally nonComplianceMessages for a single Policy assignment definitionEntry or multiple Policy definitions ( definitionEntryList ).

This approach is best for large Policy Sets such as Azure Security Benchmark, NIST 800-53, etc. Smaller Policy Sets should still be handled with JSON parameters , overrides and nonComplianceMessages .

Implement these steps as documented in Managing Policy Assignment Parameters with a CSV file .

• Generate the CSV file from your already deployed Assignment(s) or Policy Set(s).
• Modify the effect and parameter columns for each type of environment type you will use.
• Modify the Policy Assignment file to reference the CSV file and the column prefix.
• Update the CSV file with the new effect and parameter values.

Defining parameters with JSON

parameters have a simplified JSON structure. You do not need the additional value indirection that Azure requests (EPAC will inject that indirection).

To enable definitionEntryList , parameters not present in the Policy or Policy Set definition are quietly ignored.

Advanced Elements

Defining overrides with json.

overrides are in the same format as documented by Azure . They are cumulative in each tree branch. The selectors element is only used for Assignments of Policy Sets. They are not valid for Assignments of a single Policy.

If using definitionEntryList , you must add the policyName , policyId , policySetName or policySetId as used in the definitionEntryList item.

Defining nonComplianceMessages with JSON

Assign a non-compliance message to the assignment, or individual non-compliance messages if the assignment is for an Policy Set. This value is an array of objects - each containing a message, and in the case of an initiative a policyDefinitionReferenceId. See this link for details.

If you use single definitionEntry , place them normally. If you use a definitionEntryList place them in the respective list entry.

Defining resourceSelectors

resourceSelectors may appear anywhere in the tree and are cumulative in any branch. They follow the standard Azure Format .

Defining enforcementMode

enforcementMode is similar to the deprecated ignoreBranch ; it deploys the assignment and sets the assignment to Default or DoNotEnforce . DoNotEnforce allows a what-if analysis. enforcementMode may appear anywhere in the tree. Definitions at a child override the previous setting.

Example assignment files

Simple policy assignment (allowed locations).

In the simple case an assignment is a single node with no difference in assignment , parameters , and definitionEntry across multiple scopes. In many scenarios "Allowed Locations" is such a simple Assignment. Such Assignments do not have child nodes, just the root node. Example

• nodeName is required for error messages; its value is immaterial. EPAC concatenates them in the current tree branch.
• definitionEntry specifies that the custom Policy Set general-allowed-locations-policy-set from our starter kit. displayName has no meaning - it is for readability and in this instance is superfluous.
• assignment fields name , displayName and description are used when creating the assignment.
• This assignment has no metadata . You don't need an empty collection. EPAC will add pacOwnerId and roles metadata . Do not add them manually.
• enforcementMode is set to default - it is superfluous.
• parameters are obvious. Note: you don't add the value layer Azure inserts - EPAC takes care of that.
• During Policy resource development (called epac-dev ) the Assignment is deployed to an EPAC development Management Group Epac-Mg-1 .
• During Policy prod deployments ( tenant -wide), it is deployed to the tenant Management Group Epac-Mg-1 .
• No notScope entries are specified.

Security-Focused Policy Assignment with JSON parameters

• In the following example we named our root node ( nodeName ) /security/ . Since it is only used in case of error messages produced by EPAC during planning its actual value doesn't matter as long as its unique.
• We use a definitionEntryList to create two assignments at every leaf (six assignments total).
• For assignment string concatenation we append the strings in the definitionEntryList to the strings in the child nodes. You can see this best when you look at the description string in the child nodes. It will form a sentence when concatenated by append ing the definitionEntryList assignment field description .
• The parameters specified in the children are specific to the IaC environment types and their scope . Note: a real assignment would define many more parameters. The set here is abbreviated since the actual set could easily exceed a hundred entries for each of the IaC environments. We'll see in the next example how to simplify large Policy Set parameters with a CSV file.

Inverted Policy Assignment (Tag Inheritance and Required Tags)

As mentioned above sometimes it is advantageous (to reduce the number of repetitions) to turn a definition on its head:

• Common parameters , scope , definitionEntryList (with two Policies) at the root ( nodeName is /Tags/ ).
• Start of the assignment strings ( append is defaulted to false ). Again look at description which will be a concatenated sentence.
• The children define the tagName parameter and the second part of the strings for assignment . The set of parameters is the union of the root node and the child node.
• This creates six Assignments (number of Policies assigned times number of children).

Non-Compliance Messages in a Policy Definition Assignment

Non-compliance messages in a policy set definition assignment, non-compliance messages in a policy set definition assignment with a definitionentrylist.

Navigation Menu

Search code, repositories, users, issues, pull requests..., provide feedback.

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly.

To see all available qualifiers, see our documentation .

• Notifications You must be signed in to change notification settings

create-and-manage.md

Latest commit, file metadata and controls, tutorial: create and manage policies to enforce compliance.

Understanding how to create and manage policies in Azure is important for staying compliant with your corporate standards and service-level agreements. In this tutorial, you learn to use Azure Policy to do some of the more common tasks related to creating, assigning, and managing policies across your organization, such as:

[!div class="checklist"] Assign a policy to enforce a condition for resources you create in the future Create and assign an initiative definition to track compliance for multiple resources Resolve a non-compliant or denied resource Implement a new policy across an organization

If you would like to assign a policy to identify the current compliance state of your existing resources, the quickstart articles go over how to do so.

Prerequisites

If you don't have an Azure subscription, create a free account before you begin.

Assign a policy

The first step in enforcing compliance with Azure Policy is to assign a policy definition. A policy definition defines under what condition a policy is enforced and what effect to take. In this example, assign the built-in policy definition called Inherit a tag from the resource group if missing to add the specified tag with its value from the parent resource group to new or updated resources missing the tag.

Go to the Azure portal to assign policies. Search for and select Policy .

:::image type="content" source="../media/create-and-manage/search-policy.png" alt-text="Screenshot of searching for Policy in the search bar." border="false":::

Select Assignments on the left side of the Azure Policy page. An assignment is a policy that has been assigned to take place within a specific scope.

:::image type="content" source="../media/create-and-manage/select-assignments.png" alt-text="Screenshot of selecting the Assignments node from the Policy Overview page." border="false":::

Select Assign Policy from the top of the Policy | Assignments page.

:::image type="content" source="../media/create-and-manage/select-assign-policy.png" alt-text="Screenshot of selecting the 'Assign policy' button on the Assignments page." border="false":::

On the Assign Policy page and Basics tab, select the Scope by selecting the ellipsis and selecting either a management group or subscription. Optionally, select a resource group. A scope determines what resources or grouping of resources the policy assignment gets enforced on. Then select Select at the bottom of the Scope page.

Resources can be excluded based on the Scope . Exclusions start at one level lower than the level of the Scope . Exclusions are optional, so leave it blank for now.

Select the Policy definition ellipsis to open the list of available definitions. You can filter the policy definition Type to Built-in to view all and read their descriptions.

Select Inherit a tag from the resource group if missing . If you can't find it right away, type inherit a tag into the search box and then press ENTER or select out of the search box. Select Select at the bottom of the Available Definitions page once you have found and selected the policy definition.

:::image type="content" source="../media/create-and-manage/select-available-definition.png" alt-text="Screenshot of the search filter while selecting a policy definition.":::

The Version is automatically populated to the latest major version of the definition and set to autoinjest any non-breaking changes. You may change the version to others, if available or adjust your ingesting settings, but no change is required. Overrides are optional, so leave it blank for now.

The Assignment name is automatically populated with the policy name you selected, but you can change it. For this example, leave Inherit a tag from the resource group if missing . You can also add an optional Description . The description provides details about this policy assignment.

Leave Policy enforcement as Enabled . When Disabled , this setting allows testing the outcome of the policy without triggering the effect. For more information, see enforcement mode .

Select the Parameters tab at the top of the wizard.

For Tag Name , enter Environment .

Select the Remediation tab at the top of the wizard.

Leave Create a remediation task unchecked. This box allows you to create a task to alter existing resources in addition to new or updated resources. For more information, see remediate resources .

Create a Managed Identity is automatically checked since this policy definition uses the modify effect. Type of Managed Identity is set to System Assigned . Permissions is set to Contributor automatically based on the policy definition. For more information, see managed identities and how remediation access control works .

Select the Non-compliance messages tab at the top of the wizard.

Set the Non-compliance message to This resource doesn't have the required tag . This custom message is displayed when a resource is denied or for non-compliant resources during regular evaluation.

Select the Review + create tab at the top of the wizard.

Review your selections, then select Create at the bottom of the page.

Implement a new custom policy

Now that you've assigned a built-in policy definition, you can do more with Azure Policy. Next, create a new custom policy to save costs by validating that virtual machines created in your environment can't be in the G series. This way, every time a user in your organization tries to create a virtual machine in the G series, the request is denied.

Select Definitions under Authoring in the left side of the Azure Policy page.

:::image type="content" source="../media/create-and-manage/definition-under-authoring.png" alt-text="Screenshot of the Definitions page under Authoring group." border="false":::

Select + Policy definition at the top of the page. This button opens to the Policy definition page.

Enter the following information:

The management group or subscription in which the policy definition is saved. Select by using the ellipsis on Definition location .

[!NOTE] If you plan to apply this policy definition to multiple subscriptions, the location must be a management group that contains the subscriptions you assign the policy to. The same is true for an initiative definition.

The name of the policy definition - Require VM SKUs not in the G series

The description of what the policy definition is intended to do - This policy definition enforces that all virtual machines created in this scope have SKUs other than the G series to reduce cost.

Choose from existing options (such as Compute ), or create a new category for this policy definition.

Copy the following JSON code and then update it for your needs with:

• The policy parameters.
• The policy rules/conditions, in this case - VM SKU size equal to G series
• The policy effect, in this case - Deny .

Here's what the JSON should look like. Paste your revised code into the Azure portal.

The field property in the policy rule must be a supported value. A full list of values is found on policy definition structure fields . An example of an alias might be "Microsoft.Compute/VirtualMachines/Size" .

To view more Azure Policy samples, see Azure Policy samples .

Select Save .

Create a policy definition with REST API

You can create a policy with the REST API for Azure Policy Definitions. The REST API enables you to create and delete policy definitions, and get information about existing definitions. To create a policy definition, use the following example:

Include a request body similar to the following example:

Create a policy definition with PowerShell

Before proceeding with the PowerShell example, make sure you've installed the latest version of the Azure PowerShell Az module.

You can create a policy definition using the New-AzPolicyDefinition cmdlet.

To create a policy definition from a file, pass the path to the file. For an external file, use the following example:

For a local file use, use the following example:

To create a policy definition with an inline rule, use the following example:

The output is stored in a $definition object, which is used during policy assignment. The following example creates a policy definition that includes parameters:

View policy definitions with PowerShell

To see all policy definitions in your subscription, use the following command:

It returns all available policy definitions, including built-in policies. Each policy is returned in the following format:

Create a policy definition with Azure CLI

You can create a policy definition using Azure CLI with the az policy definition command. To create a policy definition with an inline rule, use the following example:

View policy definitions with Azure CLI

Create and assign an initiative definition.

With an initiative definition, you can group several policy definitions to achieve one overarching goal. An initiative evaluates resources within scope of the assignment for compliance to the included policies. For more information about initiative definitions, see Azure Policy overview .

Create an initiative definition

:::image type="content" source="../media/create-and-manage/definition-under-authoring.png" alt-text="Screenshot of the Definitions page under the Authoring group.":::

Select + Initiative Definition at the top of the page to open the Initiative definition wizard.

:::image type="content" source="../media/create-and-manage/initiative-definition.png" alt-text="Screenshot of the initiative definition page and properties to set.":::

Use the Initiative location ellipsis to select a management group or subscription to store the definition. If the previous page was scoped to a single management group or subscription, Initiative location is automatically populated.

Enter the Name and Description of the initiative.

This example validates that resources are in compliance with policy definitions about getting secure. Name the initiative Get Secure and set the description as: This initiative has been created to handle all policy definitions associated with securing resources .

For Category , choose from existing options or create a new category.

Set a Version for the initiative, such as 1.0 .

[!NOTE] The version value is strictly metadata and isn't used for updates or any process by the Azure Policy service.

Select Next at the bottom of the page or the Policies tab at the top of the wizard.

Select Add policy definition(s) button and browse through the list. Select the policy definition(s) you want added to this initiative. For the Get Secure initiative, add the following built-in policy definitions by selecting the checkbox next to the policy definition:

• Allowed locations
• Endpoint protection should be installed on machines
• Non-internet-facing virtual machines should be protected with network security groups
• Azure Backup should be enabled for Virtual Machines
• Disk encryption should be applied on virtual machines
• Add or replace a tag on resources (add this policy definition twice)

After selecting each policy definition from the list, select Add at the bottom of the list. Since it's added twice, the Add or replace a tag on resources policy definitions each get a different reference ID .

:::image type="content" source="../media/create-and-manage/initiative-definition-2.png" alt-text="Screenshot of the selected policy definitions with their reference ID and group on the initiative definition page.":::

[!NOTE] The selected policy definitions can be added to groups by selecting one or more added definitions and selecting Add selected policies to a group . The group must exist first and can be created on the Groups tab of the wizard.

Select Next at the bottom of the page or the Groups tab at the top of the wizard. New groups can be added from this tab. For this tutorial, we aren't adding any groups.

Select Next at the bottom of the page or the Initiative parameters tab at the top of the wizard. If we wanted a parameter to exist at the initiative for passing to one or more included policy definitions, the parameter is defined here and then used on the Policy parameters tab. For this tutorial, we aren't adding any initiative parameters.

[!NOTE] Once saved to an initiative definition, initiative parameters can't be deleted from the initiative. If an initiative parameter is no longer needed, remove it from use by any policy definition parameters.

Select Next at the bottom of the page or the Policy parameters tab at the top of the wizard.

Policy definitions added to the initiative that have parameters are displayed in a grid. The value type can be 'Default value', 'Set value', or 'Use Initiative Parameter'. If 'Set value' is selected, the related value is entered under Value(s) . If the parameter on the policy definition has a list of allowed values, the entry box is a dropdown list selector. If 'Use Initiative Parameter' is selected, a dropdown list select is provided with the names of initiative parameters created on the Initiative parameters tab.

:::image type="content" source="../media/create-and-manage/initiative-definition-3.png" alt-text="Screenshot of the options for allowed values for the allowed locations definition parameter on the policy parameters tab of the initiative definition page.":::

[!NOTE] In the case of some strongType parameters, the list of values cannot be automatically determined. In these cases, an ellipsis appears to the right of the parameter row. Selecting it opens the 'Parameter scope (<parameter name>)' page. On this page, select the subscription to use for providing the value options. This parameter scope is only used during creation of the initiative definition and has no impact on policy evaluation or the scope of the initiative when assigned.

Set the 'Allowed locations' value type to 'Set value' and select 'East US 2' from the dropdown list. For the two instances of the Add or replace a tag on resources policy definitions, set the Tag Name parameters to 'Env' and 'CostCenter and the Tag Value parameters to 'Test' and 'Lab' as shown below. Leave the others as 'Default value'. Using the same definition twice in the initiative but with different parameters, this configuration adds or replaces an 'Env' tag with the value 'Test' and a 'CostCenter' tag with the value of 'Lab' on resources in scope of the assignment.

:::image type="content" source="../media/create-and-manage/initiative-definition-4.png" alt-text="Screenshot of the entered options for allowed values for the allowed locations definition parameter and values for both tag parameter sets on the policy parameters tab of the initiative definition page.":::

Select Review + create at the bottom of the page or at the top of the wizard.

Review the settings and select Create .

Create a policy initiative definition with Azure CLI

You can create a policy initiative definition using Azure CLI with the az policy set-definition command. To create a policy initiative definition with an existing policy definition, use the following example:

Create a policy initiative definition with Azure PowerShell

You can create a policy initiative definition using Azure PowerShell with the New-AzPolicySetDefinition cmdlet. To create a policy initiative definition with an existing policy definition, use the following policy initiative definition file as VMPolicySet.json :

Assign an initiative definition

Locate the Get Secure initiative definition you previously created and select it. Select Assign at the top of the page to open to the Get Secure: Assign initiative page.

:::image type="content" source="../media/create-and-manage/assign-definition.png" alt-text="Screenshot of the 'Assign' button on the initiative definition page." border="false":::

You can also select and hold (or right-click) on the selected row or select the ellipsis at the end of the row for a contextual menu. Then select Assign .

:::image type="content" source="../media/create-and-manage/select-right-click.png" alt-text="Screenshot of the context menu for an initiative to select the Assign functionality." border="false":::

Fill out the Get Secure: Assign Initiative page by entering the following example information. You can use your own information.

• Scope: The management group or subscription you saved the initiative to become the default. You can change scope to assign the initiative to a subscription or resource group within the saved location.
• Exclusions: Configure any resources within the scope to prevent the initiative assignment from being applied to them.
• Initiative definition and Assignment name: Get Secure (pre-populated as name of initiative being assigned).
• Description: This initiative assignment is tailored to enforce this group of policy definitions.
• Policy enforcement: Leave as the default Enabled .
• Assigned by: Automatically filled based on who is logged in. This field is optional, so custom values can be entered.

Select the Parameters tab at the top of the wizard. If you configured an initiative parameter in previous steps, set a value here.

Select the Remediation tab at the top of the wizard. Leave Create a Managed Identity unchecked. This box must be checked when the policy or initiative being assigned includes a policy with the deployIfNotExists or modify effects. As the policy used for this tutorial doesn't, leave it blank. For more information, see managed identities and how remediation access control works .

Check initial compliance

Select Compliance in the left side of the Azure Policy page.

Locate the Get Secure initiative. It's likely still in Compliance state of Not started . Select the initiative to get full details of the assignment.

:::image type="content" source="../media/create-and-manage/compliance-status-not-started.png" alt-text="Screenshot of the Initiative compliance page showing assignment evaluations in a Not started state." border="false":::

Once the initiative assignment has been completed, the compliance page is updated with the Compliance state of Compliant .

:::image type="content" source="../media/create-and-manage/compliance-status-compliant.png" alt-text="Screenshot of the Initiative compliance page showing assignment evaluations complete and in a Compliant state." border="false":::

Selecting any policy on the initiative compliance page opens the compliance details page for that policy. This page provides details at the resource level for compliance.

Remove a non-compliant or denied resource from the scope with an exclusion

After assigning a policy initiative to require a specific location, any resource created in a different location is denied. In this section, you walk through resolving a denied request to create a resource by creating an exclusion on a single resource group. The exclusion prevents enforcement of the policy (or initiative) on that resource group. In the following example, any location is allowed in the excluded resource group. An exclusion can apply to a subscription, a resource group, or an individual resource.

A policy exemption can also be used skip the evaluation of a resource. For more information, see Scope in Azure Policy .

Deployments prevented by an assigned policy or initiative can be viewed on the resource group targeted by the deployment: Select Deployments in the left side of the page, then select the Deployment Name of the failed deployment. The resource that was denied is listed with a status of Forbidden . To determine the policy or initiative and assignment that denied the resource, select Failed. Click here for details -> on the Deployment Overview page. A window opens on the right side of the page with the error information. Under Error Details are the GUIDs of the related policy objects.

:::image type="content" source="../media/create-and-manage/rg-deployment-denied.png" alt-text="Screenshot of a failed deployment that was denied by a policy assignment." border="false":::

On the Azure Policy page: Select Compliance in the left side of the page and select the Get Secure policy initiative. On this page, there's an increase in the Deny count for blocked resources. Under the Events tab are details about who tried to create or deploy the resource that was denied by the policy definition.

:::image type="content" source="../media/create-and-manage/compliance-overview.png" alt-text="Screenshot of the Events tab and policy event details on the Initiative compliance page." border="false":::

In this example, Trent Baker, one of Contoso's Sr. Virtualization specialists, was doing required work. We need to grant Trent a space for an exception. Create a new resource group, LocationsExcluded , and next grant it an exception to this policy assignment.

Update assignment with exclusion

Select Assignments under Authoring in the left side of the Azure Policy page.

Browse through all policy assignments and open the Get Secure policy assignment.

Set the Exclusion by selecting the ellipsis and selecting the resource group to exclude, LocationsExcluded in this example. Select Add to Selected Scope and then select Save .

:::image type="content" source="../media/create-and-manage/request-exclusion.png" alt-text="Screenshot of the Exclusions option on the Initiative Assignment page to add an excluded resource group to the policy assignment." border="false":::

[!NOTE] Depending on the policy definition and its effect, the exclusion could also be granted to specific resources within a resource group inside the scope of the assignment. As a Deny effect was used in this tutorial, it wouldn't make sense to set the exclusion on a specific resource that already exists.

Select Review + save and then select Save .

In this section, you resolved the denied request by creating an exclusion on a single resource group.

Clean up resources

If you're done working with resources from this tutorial, use the following steps to delete any of the policy assignments or definitions created above:

Select Definitions (or Assignments if you're trying to delete an assignment) under Authoring in the left side of the Azure Policy page.

Search for the new initiative or policy definition (or assignment) you want to remove.

Right-click the row or select the ellipses at the end of the definition (or assignment), and select Delete definition (or Delete assignment ).

In this tutorial, you successfully accomplished the following tasks:

[!div class="checklist"] Assigned a policy to enforce a condition for resources you create in the future Created and assign an initiative definition to track compliance for multiple resources Resolved a non-compliant or denied resource Implemented a new policy across an organization

To learn more about the structures of policy definitions, look at this article:

[!div class="nextstepaction"] Azure Policy definition structure