Manage your Azure subscriptions at scale with management groups

Change the name of a management group

You can change the name of the management group by using the Azure portal, Azure PowerShell, or the Azure CLI.

Change the name in the portal

1. Sign in to the Azure portal.

2. Select All services > Management groups.

3. Select the management group that you want to rename.

4. Select details.

5. Select the Rename Group option at the top of the pane.

   

6. On the Rename Group pane, enter the new name that you want to display.

   

7. Select Save.

Change the name in Azure PowerShell

To update the display name, use Update-AzManagementGroup in Azure PowerShell. For example, to change a management group's display name from Contoso IT to Contoso Group, run the following command:

Azure PowerShell

Update-AzManagementGroup -GroupId 'ContosoIt' -DisplayName 'Contoso Group'

Change the name in the Azure CLI

For the Azure CLI, use the update command:

Azure CLI

az account management-group update --name 'Contoso' --display-name 'Contoso Group'

Delete a management group

To delete a management group, you must meet the following requirements:

• There are no child management groups or subscriptions under the management group. To move a subscription or management group to another management group, see Move management groups and subscriptions later in this article.

• You need write permissions on the management group (Owner, Contributor, or Management Group Contributor). To see what permissions you have, select the management group and then select IAM. To learn more on Azure roles, see What is Azure role-based access control (Azure RBAC)?.

Delete a management group in the portal

1. Sign in to the Azure portal.

2. Select All services > Management groups.

3. Select the management group that you want to delete.

4. Select details.

5. Select Delete.

   

    Tip

   If the Delete button is unavailable, hovering over the button shows you the reason.

6. A dialog opens and asks you to confirm that you want to delete the management group.

   

7. Select Yes.

Delete a management group in Azure PowerShell

To delete a management group, use the Remove-AzManagementGroup command in Azure PowerShell:

Azure PowerShell

Remove-AzManagementGroup -GroupId 'Contoso'

Delete a management group in the Azure CLI

With the Azure CLI, use the command az account management-group delete:

Azure CLI

az account management-group delete --name 'Contoso'

View management groups

You can view any management group if you have a direct or inherited Azure role on it.

View management groups in the portal

1. Sign in to the Azure portal.

2. Select All services > Management groups.

3. The page for management group hierarchy appears. On this page, you can explore all the management groups and subscriptions that you have access to. Selecting the group name takes you to a lower level in the hierarchy. The navigation works the same as a file explorer does.

4. To see the details of the management group, select the (details) link next to the title of the management group. If this link isn't available, you don't have permissions to view that management group.

   

View management groups in Azure PowerShell

You use the Get-AzManagementGroup command to retrieve all groups. For the full list of GET PowerShell commands for management groups, see the Az.Resources modules.

Azure PowerShell

Get-AzManagementGroup

For a single management group's information, use the -GroupId parameter:

Azure PowerShell

Get-AzManagementGroup -GroupId 'Contoso'

To return a specific management group and all the levels of the hierarchy under it, use the -Expand and -Recurse parameters:

Azure PowerShell

PS C:\> $response = Get-AzManagementGroup -GroupId TestGroupParent -Expand -Recurse
PS C:\> $response

Id                : /providers/Microsoft.Management/managementGroups/TestGroupParent
Type              : /providers/Microsoft.Management/managementGroups
Name              : TestGroupParent
TenantId          : 00000000-0000-0000-0000-000000000000
DisplayName       : TestGroupParent
UpdatedTime       : 2/1/2018 11:15:46 AM
UpdatedBy         : 00000000-0000-0000-0000-000000000000
ParentId          : /providers/Microsoft.Management/managementGroups/00000000-0000-0000-0000-000000000000
ParentName        : 00000000-0000-0000-0000-000000000000
ParentDisplayName : 00000000-0000-0000-0000-000000000000
Children          : {TestGroup1DisplayName, TestGroup2DisplayName}

PS C:\> $response.Children[0]

Type        : /managementGroup
Id          : /providers/Microsoft.Management/managementGroups/TestGroup1
Name        : TestGroup1
DisplayName : TestGroup1DisplayName
Children    : {TestRecurseChild}

PS C:\> $response.Children[0].Children[0]

Type        : /managementGroup
Id          : /providers/Microsoft.Management/managementGroups/TestRecurseChild
Name        : TestRecurseChild
DisplayName : TestRecurseChild
Children    :

View management groups in the Azure CLI

You use the list command to retrieve all groups:

Azure CLI

az account management-group list

For a single management group's information, use the show command:

Azure CLI

az account management-group show --name 'Contoso'

To return a specific management group and all the levels of the hierarchy under it, use the -Expand and -Recurse parameters:

Azure CLI

az account management-group show --name 'Contoso' -e -r

Move management groups and subscriptions

One reason to create a management group is to bundle subscriptions together. Only management groups and subscriptions can become children of another management group. A subscription that moves to a management group inherits all user access and policies from the parent management group.

You can move subscriptions between management groups. A subscription can have only one parent management group.

When you move a management group or subscription to be a child of another management group, three rules need to be evaluated as true.

If you're doing the move action, you need permission at each of the following layers:

• Child subscription or management group
  • Microsoft.management/managementgroups/write
  • Microsoft.management/managementgroups/subscriptions/write (only for subscriptions)
  • Microsoft.Authorization/roleAssignments/write
  • Microsoft.Authorization/roleAssignments/delete
  • Microsoft.Management/register/action
• Target parent management group
  • Microsoft.management/managementgroups/write
• Current parent management group
  • Microsoft.management/managementgroups/write

There's an exception: if the target or the existing parent management group is the root management group, the permission requirements don't apply. Because the root management group is the default landing spot for all new management groups and subscriptions, you don't need permissions on it to move an item.

If the Owner role on the subscription is inherited from the current management group, your move targets are limited. You can move the subscription only to another management group where you have the Owner role. You can't move the subscription to a management group where you're only a Contributor because you would lose ownership of the subscription. If you're directly assigned to the Owner role for the subscription, you can move it to any management group where you have the Contributor role.

To see what permissions you have in the Azure portal, select the management group and then select IAM. To learn more about Azure roles, see What is Azure role-based access control (Azure RBAC)?.

Add an existing subscription to a management group in the portal

1. Sign in to the Azure portal.

2. Select All services > Management groups.

3. Select the management group that you want to be the parent.

4. At the top of the page, select Add subscription.

5. Select the subscription in the list with the correct ID.

   

6. Select Save.

Remove a subscription from a management group in the portal

1. Sign in to the Azure portal.

2. Select All services > Management groups.

3. Select the management group that's the current parent.

4. Select the ellipsis (...) at the end of the row for the subscription in the list that you want to move.

   

5. Select Move.

6. On Move pane, select the value for New parent management group ID.

   

7. Select Save.

Move a subscription in Azure PowerShell

To move a subscription in PowerShell, you use the New-AzManagementGroupSubscription command:

Azure PowerShell

New-AzManagementGroupSubscription -GroupId 'Contoso' -SubscriptionId '12345678-1234-1234-1234-123456789012'

To remove the link between the subscription and the management group, use the Remove-AzManagementGroupSubscription command:

Azure PowerShell

Remove-AzManagementGroupSubscription -GroupId 'Contoso' -SubscriptionId '12345678-1234-1234-1234-123456789012'

Move a subscription in the Azure CLI

To move a subscription in the Azure CLI, you use the add command:

Azure CLI

az account management-group subscription add --name 'Contoso' --subscription '12345678-1234-1234-1234-123456789012'

To remove the subscription from the management group, use the subscription remove command:

Azure CLI

az account management-group subscription remove --name 'Contoso' --subscription '12345678-1234-1234-1234-123456789012'

Move a subscription in an ARM template

To move a subscription in an Azure Resource Manager template (ARM template), use the following template and deploy it at the tenant level:

JSON

{
    "$schema": "https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "targetMgId": {
            "type": "string",
            "metadata": {
                "description": "Provide the ID of the management group that you want to move the subscription to."
            }
        },
        "subscriptionId": {
            "type": "string",
            "metadata": {
                "description": "Provide the ID of the existing subscription to move."
            }
        }
    },
    "resources": [
        {
            "scope": "/",
            "type": "Microsoft.Management/managementGroups/subscriptions",
            "apiVersion": "2020-05-01",
            "name": "[concat(parameters('targetMgId'), '/', parameters('subscriptionId'))]",
            "properties": {
            }
        }
    ],
    "outputs": {}
}

Or, use the following Bicep file:

Bicep

targetScope = 'managementGroup'

@description('Provide the ID of the management group that you want to move the subscription to.')
param targetMgId string

@description('Provide the ID of the existing subscription to move.')
param subscriptionId string

resource subToMG 'Microsoft.Management/managementGroups/subscriptions@2020-05-01' = {
  scope: tenant()
  name: '${targetMgId}/${subscriptionId}'
}

Move a management group in the portal

1. Sign in to the Azure portal.

2. Select All services > Management groups.

3. Select the management group that you want to be the parent.

4. At the top of the page, select Add management group.

5. On the Add management group pane, choose whether you want to use a new or existing management group:

   • Selecting Create new creates a new management group.
   • Selecting Use existing presents you with a dropdown list of all the management groups that you can move to this management group.

   

6. Select Save.

Move a management group in Azure PowerShell

To move a management group under a different group, use the Update-AzManagementGroup command in Azure PowerShell:

Azure PowerShell

$parentGroup = Get-AzManagementGroup -GroupId ContosoIT
Update-AzManagementGroup -GroupId 'Contoso' -ParentId $parentGroup.id

Move a management group in the Azure CLI

To move a management group in the Azure CLI, use the update command:

Azure CLI

az account management-group update --name 'Contoso' --parent ContosoIT

Audit management groups by using activity logs

Management groups are supported in Azure Monitor activity logs. You can query all events that happen to a management group in the same central location as other Azure resources. For example, you can see all role assignments or policy assignment changes made to a particular management group.

When you want to query on management groups outside the Azure portal, the target scope for management groups looks like "/providers/Microsoft.Management/managementGroups/{yourMgID}".

 

What are Azure management groups?

Management groups give you enterprise-grade management at scale, no matter what type of subscriptions you might have. However, all subscriptions within a single management group must trust the same Microsoft Entra tenant.

For example, you can apply a policy to a management group that limits the regions available for virtual machine (VM) creation. This policy would be applied to all nested management groups, subscriptions, and resources to allow VM creation only in authorized regions.

Hierarchy of management groups and subscriptions

You can build a flexible structure of management groups and subscriptions to organize your resources into a hierarchy for unified policy and access management. The following diagram shows an example of creating a hierarchy for governance by using management groups.

Diagram of a root management group that holds both management groups and subscriptions. Some child management groups hold management groups, some hold subscriptions, and some hold both. One of the examples in the sample hierarchy is four levels of management groups, with all subscriptions at the child level.

You can create a hierarchy that applies a policy, for example, that limits VM locations to the West US region in the management group called Corp. This policy will inherit all the Enterprise Agreement (EA) subscriptions that are descendants of that management group and will apply to all VMs under those subscriptions. The resource or subscription owner can't alter this security policy, to allow for improved governance.

Another scenario where you would use management groups is to provide user access to multiple subscriptions. By moving multiple subscriptions under a management group, you can create one Azure role assignment on the management group. The role will inherit that access to all the subscriptions. One assignment on the management group can enable users to have access to everything they need, instead of scripting Azure role-based access control (RBAC) over different subscriptions.

Important facts about management groups

• A single directory can support 10,000 management groups.

• A management group tree can support up to six levels of depth.

  This limit doesn't include the root level or the subscription level.

• Each management group and subscription can support only one parent.

• Each management group can have many children.

• All subscriptions and management groups are within a single hierarchy in each directory. For more information, see Important facts about the root management group later in this article.

Root management group for each directory

Each directory has a single top-level management group called the root management group. The root management group is built into the hierarchy to have all management groups and subscriptions fold up to it.

The root management group allows for the application of global policies and Azure role assignments at the directory level. Initially, the Microsoft Entra Global Administrator needs to elevate themselves to the User Access Administrator role of this root group. After elevating access, the administrator can assign any Azure role to other directory users or groups to manage the hierarchy. As an administrator, you can assign your account as the owner of the root management group.

Important facts about the root management group

• By default, the root management group's display name is Tenant root group, and it operates itself as a management group. The ID is the same value as the Microsoft Entra tenant ID.
• To change the display name, your account must have the Owner or Contributor role on the root management group. For more information, see Change the name of a management group.
• The root management group can't be moved or deleted, unlike other management groups.
• All subscriptions and management groups fold up into one root management group within the directory.
  • All resources in the directory fold up to the root management group for global management.
  • New subscriptions automatically default to the root management group when they're created.
• All Azure customers can see the root management group, but not all customers have access to manage that root management group.
  • Everyone who has access to a subscription can see the context of where that subscription is in the hierarchy.
  • No one has default access to the root management group. Microsoft Entra Global Administrators are the only users who can elevate themselves to gain access. After they have access to the root management group, they can assign any Azure role to other users to manage the group.

Initial setup of management groups

When any user starts using management groups, an initial setup process happens. The first step is creation of the root management group in the directory. All existing subscriptions that exist in the directory then become children of the root management group.

The reason for this process is to make sure there's only one management group hierarchy within a directory. The single hierarchy within the directory allows administrative customers to apply global access and policies that other customers within the directory can't bypass.

Anything assigned on the root applies to the entire hierarchy. That is, it applies to all management groups, subscriptions, resource groups, and resources within that Microsoft Entra tenant.

Management group access

Azure management groups support Azure RBAC for all resource access and role definitions. Child resources that exist in the hierarchy inherit these permissions. Any Azure role can be assigned to a management group that will inherit down the hierarchy to the resources.

For example, you can assign the Azure role VM Contributor to a management group. This role has no action on the management group but will inherit to all VMs under that management group.

The following chart shows the list of roles and the supported actions on management groups.

Azure role name	Create	Rename	Move**	Delete	Assign access	Assign policy	Read
Owner	X	X	X	X	X	X	X
Contributor	X	X	X	X			X
Management Group Contributor*	X	X	X	X			X
Reader							X
Management Group Reader*							X
Resource Policy Contributor						X
User Access Administrator					X	X

*: These roles allow users to perform the specified actions only on the management group scope.

**: Role assignments on the root management group aren't required to move a subscription or a management group to and from it.

For details on moving items within the hierarchy, see Manage your resources with management groups.

Azure custom role definition and assignment

You can define a management group as an assignable scope in an Azure custom role definition. The Azure custom role will then be available for assignment on that management group and any management group, subscription, resource group, or resource under it. The custom role will inherit down the hierarchy like any built-in role.

For information about the limitations with custom roles and management groups, see Limitations later in this article.

Example definition

Defining and creating a custom role doesn't change with the inclusion of management groups. Use the full path to define the management group: /providers/Microsoft.Management/managementgroups/{_groupId_}.

Use the management group's ID and not the management group's display name. This common error happens because both are custom-defined fields in creating a management group.

JSON

...
{
  "Name": "MG Test Custom Role",
  "Id": "id",
  "IsCustom": true,
  "Description": "This role provides members understand custom roles.",
  "Actions": [
    "Microsoft.Management/managementGroups/delete",
    "Microsoft.Management/managementGroups/read",
    "Microsoft.Management/managementGroups/write",
    "Microsoft.Management/managementGroups/subscriptions/delete",
    "Microsoft.Management/managementGroups/subscriptions/write",
    "Microsoft.resources/subscriptions/read",
    "Microsoft.Authorization/policyAssignments/*",
    "Microsoft.Authorization/policyDefinitions/*",
    "Microsoft.Authorization/policySetDefinitions/*",
    "Microsoft.PolicyInsights/*",
    "Microsoft.Authorization/roleAssignments/*",
    "Microsoft.Authorization/roledefinitions/*"
  ],
  "NotActions": [],
  "DataActions": [],
  "NotDataActions": [],
  "AssignableScopes": [
        "/providers/microsoft.management/managementGroups/ContosoCorporate"
  ]
}
...

Issues with breaking the role definition and assignment hierarchy path

Role definitions are assignable scopes anywhere within the management group hierarchy. A role definition can be on a parent management group, whereas the actual role assignment exists on the child subscription. Because there's a relationship between the two items, you'll receive an error if you try to separate the assignment from its definition.

For example, consider the following example of a small section of a hierarchy.

The diagram focuses on the root management group with child landing zones and sandbox management groups. The management group for landing zones has two child management groups named Corp and Online, whereas the sandbox management group has two child subscriptions.

Assume that a custom role is defined on the sandbox management group. That custom role is then assigned on the two sandbox subscriptions.

If you try to move one of those subscriptions to be a child of the Corp management group, you'll break the path from subscription role assignment to the role definition for the sandbox management group. In this scenario, you'll receive an error that says the move isn't allowed because it will break this relationship.

To fix this scenario, you have these options:

• Remove the role assignment from the subscription before moving the subscription to a new parent management group.
• Add the subscription to the role definition's assignable scope.
• Change the assignable scope within the role definition. In this example, you can update the assignable scopes from the sandbox management group to the root management group so that both branches of the hierarchy can reach the definition.
• Create another custom role that's defined in the other branch. This new role also requires you to change the role on the subscription.

Limitations

There are limitations to using custom roles on management groups:

• You can define only one management group in the assignable scopes of a new role. This limitation is in place to reduce the number of situations where role definitions and role assignments are disconnected. This kind of situation happens when a subscription or management group with a role assignment moves to a different parent that doesn't have the role definition.
• Custom roles with DataActions can't be assigned at the management group scope. For more information, see Custom role limits.
• Azure Resource Manager doesn't validate the management group's existence in the role definition's assignable scope. If there's a typo or an incorrect management group ID, the role definition is still created.

Moving management groups and subscriptions

To move a management group or subscription to be a child of another management group, you need:

• Management group write permissions and role assignment write permissions on the child subscription or management group.
  • Built-in role example: Owner
• Management group write access on the target parent management group.
  • Built-in role example: Owner, Contributor, Management Group Contributor
• Management group write access on the existing parent management group.
  • Built-in role example: Owner, Contributor, Management Group Contributor

There's an exception: if the target or the existing parent management group is the root management group, the permission requirements don't apply. Because the root management group is the default landing spot for all new management groups and subscriptions, you don't need permissions on it to move an item.

If the Owner role on the subscription is inherited from the current management group, your move targets are limited. You can move the subscription only to another management group where you have the Owner role. You can't move the subscription to a management group where you're only a Contributor because you would lose ownership of the subscription. If you're directly assigned to the Owner role for the subscription, you can move it to any management group where you have the Contributor role.

Auditing management groups by using activity logs

Management groups are supported in Azure Monitor activity logs. You can query all events that happen to a management group in the same central location as other Azure resources. For example, you can see all role assignments or policy assignment changes made to a particular management group.

When you want to query on management groups outside the Azure portal, the target scope for management groups looks like