Build management-group custom policy IDs with the correct ARM resource scope

Source facts

A custom Azure Policy definition deployed to a management group is an extension of that group. Microsoft’s ARM guidance uses extensionResourceId() to identify it, with the management group’s fully qualified resource ID as the first argument. Built-in definitions instead belong at tenant scope and use tenantResourceId(). The two identifiers therefore should not be constructed as though their definitions share the same owning resource. Microsoft Learn.

Applicability

Apply this review to JSON ARM templates that create or reference management-group custom definitions. Identify whether the intended definition is custom or built-in before copying an expression from another assignment. Keep the definition’s ID separate from the name chosen for the assignment itself.

DSE recommendation

DSE recommends checking the definition’s ownership scope before constructing its policyDefinitionId. Record the expected management-group ID for a custom definition and review the complete expression, including its first argument. Avoid replacing that argument with a subscription or deployment resource-group ID merely because those values are already available elsewhere in the template. Review reused expressions when moving a policy between organizational scopes.

Verification

Resolve the constructed ID through a read-only check and inspect the returned definition’s name and rule before an authorized assignment change. Compare the result with the approved policy artifact, not only its display label. In a test deployment, inspect the assignment’s recorded definition ID. Retain that evidence with the template revision so an unintended reference can be distinguished from an issue in the policy rule itself.

Official references

Microsoft Learn. Source retrieved September 9, 2026.