Merge pull request #199006 from rolyon/rolyon-rbac-custom-roles-management-group-scope-ga

[Azure RBAC] Custom roles for management groups

Author: American-Dipper

articles/role-based-access-control/custom-roles-cli.md

@@ -11,17 +11,12 @@ ms.service: role-based-access-control
 ms.topic: how-to
 ms.tgt_pltfrm: na
 ms.workload: identity
-ms.date: 07/28/2022
+ms.date: 04/05/2023
 ms.author: rolyon
 ms.reviewer: bagovind
 ---
 # Create or update Azure custom roles using Azure CLI
 
-> [!IMPORTANT]
-> Adding a management group to `AssignableScopes` is currently in preview.
-> This preview version is provided without a service level agreement, and it's not recommended for production workloads. Certain features might not be supported or might have constrained capabilities.
-> For more information, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).
-
 If the [Azure built-in roles](built-in-roles.md) don't meet the specific needs of your organization, you can create your own custom roles. This article describes how to list, create, update, or delete custom roles using Azure CLI.
 
 For a step-by-step tutorial on how to create a custom role, see [Tutorial: Create an Azure custom role using Azure CLI](tutorial-custom-role-cli.md).
@@ -60,7 +55,7 @@ az role definition list --custom-role-only true --output json --query '[].{roleN
 
 ## List a custom role definition
 
-To list a custom role definition, use [az role definition list](/cli/azure/role/definition#az-role-definition-list). This is the same command you would use for a built-in role.
+To list a custom role definition, use [az role definition list](/cli/azure/role/definition#az-role-definition-list). This command is the same command you would use for a built-in role.
 
 ```azurecli
 az role definition list --name {roleName}
@@ -183,7 +178,7 @@ To update a custom role, first use [az role definition list](/cli/azure/role/def
 az role definition update --role-definition {roleDefinition}
 ```
 
-The following example adds the *Microsoft.Insights/diagnosticSettings/* action to `Actions` and adds a management group to `AssignableScopes` for the *Virtual Machine Operator* custom role. Adding a management group to `AssignableScopes` is currently in preview.
+The following example adds the *Microsoft.Insights/diagnosticSettings/* action to `Actions` and adds a management group to `AssignableScopes` for the *Virtual Machine Operator* custom role.
 
 vmoperator.json
 

articles/role-based-access-control/custom-roles-portal.md

@@ -8,13 +8,13 @@ manager: amycolannino
 ms.service: role-based-access-control
 ms.topic: how-to
 ms.workload: identity
-ms.date: 07/28/2022
+ms.date: 04/05/2023
 ms.author: rolyon
 ---
 
 # Create or update Azure custom roles using the Azure portal
 
-If the [Azure built-in roles](built-in-roles.md) don't meet the specific needs of your organization, you can create your own Azure custom roles. Just like built-in roles, you can assign custom roles to users, groups, and service principals at management group (in preview only), subscription and resource group scopes. Custom roles are stored in an Azure Active Directory (Azure AD) directory and can be shared across subscriptions. Each directory can have up to 5000 custom roles. Custom roles can be created using the Azure portal, Azure PowerShell, Azure CLI, or the REST API. This article describes how to create custom roles using the Azure portal.
+If the [Azure built-in roles](built-in-roles.md) don't meet the specific needs of your organization, you can create your own Azure custom roles. Just like built-in roles, you can assign custom roles to users, groups, and service principals at management group, subscription and resource group scopes. Custom roles are stored in an Azure Active Directory (Azure AD) directory and can be shared across subscriptions. Each directory can have up to 5000 custom roles. Custom roles can be created using the Azure portal, Azure PowerShell, Azure CLI, or the REST API. This article describes how to create custom roles using the Azure portal.
 
 ## Prerequisites
 
@@ -39,7 +39,7 @@ There are three ways that you can start to create a custom role. You can clone a
 
 If an existing role does not quite have the permissions you need, you can clone it and then modify the permissions. Follow these steps to start cloning a role.
 
-1. In the Azure portal, open a subscription or resource group where you want the custom role to be assignable and then open **Access control (IAM)**.
+1. In the Azure portal, open a management group, subscription, or resource group where you want the custom role to be assignable and then open **Access control (IAM)**.
 
     The following screenshot shows the Access control (IAM) page opened for a subscription.
 
@@ -61,11 +61,11 @@ If an existing role does not quite have the permissions you need, you can clone
 
 If you prefer, you can follow these steps to start a custom role from scratch.
 
-1. In the Azure portal, open a subscription or resource group where you want the custom role to be assignable and then open **Access control (IAM)**.
+1. In the Azure portal, open a management group, subscription, or resource group where you want the custom role to be assignable and then open **Access control (IAM)**.
 
 1. Click **Add** and then click **Add custom role**.
 
-    ![Add custom role menu](./media/custom-roles-portal/add-custom-role-menu.png)
+    ![Screenshot showing Add custom role menu.](./media/custom-roles-portal/add-custom-role-menu.png)
 
     This opens the custom roles editor with the **Start from scratch** option selected.
 
@@ -129,7 +129,7 @@ If you prefer, you can specify most of your custom role values in a JSON file. Y
 
 1. Click **Add** and then click **Add custom role**.
 
-    ![Add custom role menu](./media/custom-roles-portal/add-custom-role-menu.png)
+    ![Screenshot showing Add custom role menu.](./media/custom-roles-portal/add-custom-role-menu.png)
 
     This opens the custom roles editor.
 
@@ -203,6 +203,9 @@ Microsoft.CostManagement/exports/*
 
 If you want to add a new wildcard permission, you can't add it using the **Add permissions** pane. To add a wildcard permission, you have to add it manually using the **JSON** tab. For more information, see [Step 6: JSON](#step-6-json).
 
+> [!NOTE]
+> It's recommended that you specify `Actions` and `DataActions` explicitly instead of using the wildcard (`*`) character. The additional access and permissions granted through future `Actions` or `DataActions` may be unwanted behavior using the wildcard.
+
 ### Exclude permissions
 
 If your role has a wildcard (`*`) permission and you want to exclude or subtract specific permissions from that wildcard permission, you can exclude them. For example, let's say that you have the following wildcard permission:
@@ -238,7 +241,7 @@ When you exclude a permission, it is added as a `NotActions` or `NotDataActions`
 
 On the **Assignable scopes** tab, you specify where your custom role is available for assignment, such as management group, subscriptions, or resource groups. Depending on how you chose to start, this tab might already list the scope where you opened the Access control (IAM) page.
 
- You can only define one management group in assignable scopes. Adding a management group to assignable scopes is currently in preview. Setting assignable scope to root scope ("/") is not supported.
+ You can define only one management group in assignable scopes. Setting assignable scope to root scope ("/") is not supported.
 
 1. Click **Add assignable scopes** to open the Add assignable scopes pane.
 
@@ -252,7 +255,7 @@ On the **Assignable scopes** tab, you specify where your custom role is availabl
 
 ## Step 6: JSON
 
-On the **JSON** tab, you see your custom role formatted in JSON. If you want, you can directly edit the JSON. If you want to add a wildcard (`*`) permission, you must use this tab.
+On the **JSON** tab, you see your custom role formatted in JSON. If you want, you can directly edit the JSON.
 
 1. To edit the JSON, click **Edit**.
 
@@ -290,7 +293,7 @@ On the **Review + create** tab, you can review your custom role settings.
 
 Follow these steps to view your custom roles.
 
-1. Open a subscription or resource group and then open **Access control (IAM)**.
+1. Open a management group, subscription, or resource group and then open **Access control (IAM)**.
 
 1. Click the **Roles** tab to see a list of all the built-in and custom roles.
 

articles/role-based-access-control/custom-roles-powershell.md

@@ -11,18 +11,13 @@ ms.service: role-based-access-control
 ms.topic: how-to
 ms.tgt_pltfrm: na
 ms.workload: identity
-ms.date: 07/28/2022
+ms.date: 04/05/2023
 ms.author: rolyon
 ms.reviewer: bagovind 
 ms.custom: devx-track-azurepowershell
 ---
 # Create or update Azure custom roles using Azure PowerShell
 
-> [!IMPORTANT]
-> Adding a management group to `AssignableScopes` is currently in preview.
-> This preview version is provided without a service level agreement, and it's not recommended for production workloads. Certain features might not be supported or might have constrained capabilities.
-> For more information, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).
-
 If the [Azure built-in roles](built-in-roles.md) don't meet the specific needs of your organization, you can create your own custom roles. This article describes how to list, create, update, or delete custom roles using Azure PowerShell.
 
 For a step-by-step tutorial on how to create a custom role, see [Tutorial: Create an Azure custom role using Azure PowerShell](tutorial-custom-role-powershell.md).
@@ -297,7 +292,7 @@ AssignableScopes : {/subscriptions/00000000-0000-0000-0000-000000000000,
                    /subscriptions/22222222-2222-2222-2222-222222222222}
 ```
 
-The following example adds a management group to `AssignableScopes` of the *Virtual Machine Operator* custom role. Adding a management group to `AssignableScopes` is currently in preview.
+The following example adds a management group to `AssignableScopes` of the *Virtual Machine Operator* custom role.
 
 ```azurepowershell
 Get-AzManagementGroup

articles/role-based-access-control/custom-roles-rest.md

@@ -12,18 +12,13 @@ ms.service: role-based-access-control
 ms.workload: multiple
 ms.tgt_pltfrm: rest-api
 ms.topic: how-to
-ms.date: 03/20/2023
+ms.date: 04/05/2023
 ms.author: rolyon
 ms.reviewer: bagovind
 
 ---
 # Create or update Azure custom roles using the REST API
 
-> [!IMPORTANT]
-> Adding a management group to `AssignableScopes` is currently in preview.
-> This preview version is provided without a service level agreement, and it's not recommended for production workloads. Certain features might not be supported or might have constrained capabilities.
-> For more information, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).
-
 If the [Azure built-in roles](built-in-roles.md) don't meet the specific needs of your organization, you can create your own custom roles. This article describes how to list, create, update, or delete custom roles using the REST API.
 
 ## Prerequisites
@@ -381,7 +376,7 @@ To create a custom role, use the [Role Definitions - Create Or Update](/rest/api
 
 1. If `assignableScopes` is a subscription or resource group, replace the *{subscriptionId}* or *{resourceGroup}* instances with your identifiers.
 
-1. If `assignableScopes` is a management group, replace the *{groupId}* instance with your management group identifier. Adding a management group to `assignableScopes` is currently in preview.
+1. If `assignableScopes` is a management group, replace the *{groupId}* instance with your management group identifier.
 
 1. In the `actions` property, add the actions that the role allows to be performed.
 

articles/role-based-access-control/custom-roles.md

@@ -7,17 +7,12 @@ manager: amycolannino
 ms.service: role-based-access-control
 ms.topic: conceptual
 ms.workload: identity
-ms.date: 09/13/2022
+ms.date: 04/05/2023
 ms.author: rolyon
 ---
 
 # Azure custom roles
 
-> [!IMPORTANT]
-> Adding a management group to `AssignableScopes` is currently in preview.
-> This preview version is provided without a service level agreement, and it's not recommended for production workloads. Certain features might not be supported or might have constrained capabilities.
-> For more information, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).
-
 If the [Azure built-in roles](built-in-roles.md) don't meet the specific needs of your organization, you can create your own custom roles. Just like built-in roles, you can assign custom roles to users, groups, and service principals at management group (in preview only), subscription, and resource group scopes.
 
 Custom roles can be shared between subscriptions that trust the same Azure AD tenant. There is a limit of **5,000** custom roles per tenant. (For Azure China 21Vianet, the limit is 2,000 custom roles.) Custom roles can be created using the Azure portal, Azure PowerShell, Azure CLI, or the REST API.
@@ -154,7 +149,7 @@ The following table describes what the custom role properties mean.
 | `Description`</br>`description` | Yes | String | The description of the custom role. Can include letters, numbers, spaces, and special characters. Maximum number of characters is 2048. |
 | `Actions`</br>`actions` | Yes | String[] | An array of strings that specifies the control plane actions that the role allows to be performed. For more information, see [Actions](role-definitions.md#actions). |
 | `NotActions`</br>`notActions` | No | String[] | An array of strings that specifies the control plane actions that are excluded from the allowed `Actions`. For more information, see [NotActions](role-definitions.md#notactions). |
-| `DataActions`</br>`dataActions` | No | String[] | An array of strings that specifies the data plane actions that the role allows to be performed to your data within that object. If you create a custom role with `DataActions`, that role cannot be assigned at the management group scope. For more information, see [DataActions](role-definitions.md#dataactions). |
+| `DataActions`</br>`dataActions` | No | String[] | An array of strings that specifies the data plane actions that the role allows to be performed to your data within that object. If you create a custom role with `DataActions`, that role can't be assigned at the management group scope. For more information, see [DataActions](role-definitions.md#dataactions). |
 | `NotDataActions`</br>`notDataActions` | No | String[] | An array of strings that specifies the data plane actions that are excluded from the allowed `DataActions`. For more information, see [NotDataActions](role-definitions.md#notdataactions). |
 | `AssignableScopes`</br>`assignableScopes` | Yes | String[] | An array of strings that specifies the scopes that the custom role is available for assignment. Maximum number of `AssignableScopes` is 2,000. For more information, see [AssignableScopes](role-definitions.md#assignablescopes). |
 
@@ -178,7 +173,8 @@ Instead of adding all of these strings, you could just add a wildcard string. Fo
 Microsoft.CostManagement/exports/*
 ```
 
-It's recommended that you specify `Actions` and `DataActions` explicitly instead of using the wildcard (`*`) character. The additional access and permissions granted through future `Actions` or `DataActions` may be unwanted behavior using the wildcard.
+> [!NOTE]
+> It's recommended that you specify `Actions` and `DataActions` explicitly instead of using the wildcard (`*`) character. The additional access and permissions granted through future `Actions` or `DataActions` may be unwanted behavior using the wildcard.
 
 ## Who can create, delete, update, or view a custom role
 
@@ -210,9 +206,9 @@ The following list describes the limits for custom roles.
 - Azure China 21Vianet can have up to 2000 custom roles for each tenant.
 - You cannot set `AssignableScopes` to the root scope (`"/"`).
 - You cannot use wildcards (`*`) in `AssignableScopes`. This wildcard restriction helps ensure a user can't potentially obtain access to a scope by updating the role definition.
-- You can only define one management group in `AssignableScopes` of a custom role. Adding a management group to `AssignableScopes` is currently in preview.
+- You can define only one management group in `AssignableScopes` of a custom role.
 - You can have only one wildcard in an action string.
-- Custom roles with `DataActions` cannot be assigned at the management group scope.
+- Custom roles with `DataActions` can't be assigned at the management group scope.
 - Azure Resource Manager doesn't validate the management group's existence in the role definition's `AssignableScopes`.
 
 For more information about custom roles and management groups, see [What are Azure management groups?](../governance/management-groups/overview.md#azure-custom-role-definition-and-assignment).

articles/role-based-access-control/media/custom-roles-portal/add-custom-role-menu.png

@@ -8,7 +8,7 @@ manager: amycolannino
 ms.service: role-based-access-control
 ms.topic: conceptual
 ms.workload: identity
-ms.date: 08/19/2022
+ms.date: 04/05/2023
 ms.author: rolyon
 ms.custom:
 ---
@@ -353,7 +353,7 @@ Examples of valid assignable scopes include:
 > | Management group and a subscription | `"/providers/Microsoft.Management/managementGroups/{groupId1}", "/subscriptions/{subscriptionId1}",` |
 > | All scopes (applies only to built-in roles) | `"/"` |
 
-You can define only one management group in `AssignableScopes` of a custom role. Adding a management group to `AssignableScopes` is currently in preview.
+You can define only one management group in `AssignableScopes` of a custom role.
 
 Although it's possible to create a custom role with a resource instance in `AssignableScopes` using the command line, it's not recommended. Each tenant supports a maximum of 5000 custom roles. Using this strategy could potentially exhaust your available custom roles. Ultimately, the level of access is determined by the custom role assignment (scope + role permissions + security principal) and not the `AssignableScopes` listed in the custom role. So, create your custom roles with `AssignableScopes` of management group, subscription, or resource group, but assign the custom roles with narrow scope, such as resource or resource group.