Merge pull request #233461 from rolyon/rolyon-aadroles-assignments-groups-update

[Azure AD roles] Refactor assign roles to groups

Author: ttorble

.openpublishing.redirection.active-directory.json

@@ -7234,7 +7234,7 @@
     {
       "source_path_from_root": "/articles/active-directory/active-directory-privileged-identity-management-how-to-add-role-to-user.md",
       "redirect_url": "/azure/active-directory/privileged-identity-management/pim-how-to-add-role-to-user",
-      "redirect_document_id": true
+      "redirect_document_id": false
     },
     {
       "source_path_from_root": "/articles/active-directory/active-directory-privileged-identity-management-how-to-change-default-settings.md",
@@ -7551,6 +7551,11 @@
       "redirect_url": "/azure/active-directory/roles/view-assignments",
       "redirect_document_id": false
     },
+    {
+      "source_path_from_root": "/articles/active-directory/roles/groups-pim-eligible.md",
+      "redirect_url": "/azure/active-directory/privileged-identity-management/pim-how-to-add-role-to-user",
+      "redirect_document_id": true
+    },
     {
       "source_path_from_root": "/articles/active-directory/users-groups-roles/directory-administrative-units.md",
       "redirect_url": "/azure/active-directory/roles/administrative-units",
@@ -7668,8 +7673,8 @@
     },
     {
       "source_path_from_root": "/articles/active-directory/users-groups-roles/roles-groups-pim-eligible.md",
-      "redirect_url": "/azure/active-directory/roles/groups-pim-eligible",
-      "redirect_document_id": true
+      "redirect_url": "/azure/active-directory/privileged-identity-management/pim-how-to-add-role-to-user",
+      "redirect_document_id": false
     },
     {
       "source_path_from_root": "/articles/active-directory/users-groups-roles/roles-groups-remove-assignment.md",

articles/active-directory/roles/TOC.yml

@@ -54,8 +54,6 @@
       href: groups-create-eligible.md
     - name: Assign roles to groups
       href: groups-assign-role.md
-    - name: Make a group eligible for a role in PIM
-      href: groups-pim-eligible.md
     - name: Assign roles with scope using PowerShell
       href: custom-assign-powershell.md
     - name: Assign roles using Microsoft Graph

articles/active-directory/roles/assign-roles-different-scopes.md

@@ -16,7 +16,7 @@ ms.collection: M365-identity-device-management
 ---
 # Assign Azure AD roles at different scopes
 
-In Azure Active Directory (Azure AD), you typically assign Azure AD roles so that they apply to the entire tenant. However, you can also assign Azure AD roles for different resources, such as administrative units or application registrations. For example, you could assign the Helpdesk Administrator role so that it just applies to a particular administrative unit and not the entire tenant. The resources that a role assignment applies to is also call the scope. This article describes how to assign Azure AD roles at tenant, administrative unit, and application registration scopes. For more information about scope, see [Overview of RBAC in Azure AD](custom-overview.md#scope).
+In Azure Active Directory (Azure AD), you typically assign Azure AD roles so that they apply to the entire tenant. However, you can also assign Azure AD roles for different resources, such as administrative units or application registrations. For example, you could assign the Helpdesk Administrator role so that it just applies to a particular administrative unit and not the entire tenant. The resources that a role assignment applies to is also called the scope. This article describes how to assign Azure AD roles at tenant, administrative unit, and application registration scopes. For more information about scope, see [Overview of RBAC in Azure AD](custom-overview.md#scope).
 
 ## Prerequisites
 
@@ -36,7 +36,7 @@ This section describes how to assign roles at the tenant scope.
 
 1. Select **Azure Active Directory** > **Roles and administrators** to see the list of all available roles.
 
-    ![Roles and administrators page in Azure Active Directory.](./media/manage-roles-portal/roles-and-administrators.png)
+    ![Roles and administrators page in Azure Active Directory.](./media/common/roles-and-administrators.png)
 
 1. Select a role to see its assignments. To help you find the role you need, use **Add filters** to filter the roles.
 

articles/active-directory/roles/custom-overview.md

@@ -8,7 +8,7 @@ ms.service: active-directory
 ms.workload: identity
 ms.subservice: roles
 ms.topic: overview
-ms.date: 10/06/2021
+ms.date: 04/10/2023
 ms.author: rolyon
 ms.reviewer: abhijeetsinha
 ms.custom: it-pro
@@ -18,15 +18,17 @@ ms.collection: M365-identity-device-management
 
 # Overview of role-based access control in Azure Active Directory
 
-This article describes how to understand Azure Active Directory (Azure AD) role-based access control. Azure AD roles allow you to grant granular permissions to your admins, abiding by the principle of least privilege. Azure AD built-in and custom roles operate on concepts similar to those you will find in [the role-based access control system for Azure resources](../../role-based-access-control/overview.md) (Azure roles). The [difference between these two role-based access control systems](../../role-based-access-control/rbac-and-directory-admin-roles.md) is:
+This article describes how to understand Azure Active Directory (Azure AD) role-based access control. Azure AD roles allow you to grant granular permissions to your admins, abiding by the principle of least privilege. Azure AD built-in and custom roles operate on concepts similar to those you find in [the role-based access control system for Azure resources](../../role-based-access-control/overview.md) (Azure roles). The [difference between these two role-based access control systems](../../role-based-access-control/rbac-and-directory-admin-roles.md) is:
 
 - Azure AD roles control access to Azure AD resources such as users, groups, and applications using the Microsoft Graph API
 - Azure roles control access to Azure resources such as virtual machines or storage using Azure Resource Management
 
 Both systems contain similarly used role definitions and role assignments. However, Azure AD role permissions can't be used in Azure custom roles and vice versa.
 
 ## Understand Azure AD role-based access control
-Azure AD supports 2 types of roles definitions:
+
+Azure AD supports two types of roles definitions:
+
 * [Built-in roles](./permissions-reference.md)
 * [Custom roles](./custom-create.md)
 
@@ -62,7 +64,7 @@ The following diagram shows an example of a role assignment. In this example, Ch
 
 ### Security principal
 
-A security principal represents a user, group, or service principal that is assigned access to Azure AD resources. A user is an individual who has a user profile in Azure Active Directory. A group is a new Microsoft 365 or security group with the isAssignableToRole property set to true (currently in preview). A service principal is an identity created for use with applications, hosted services, and automated tools to access Azure AD resources.
+A security principal represents a user, group, or service principal that is assigned access to Azure AD resources. A user is an individual who has a user profile in Azure Active Directory. A group is a new Microsoft 365 or security group that has been set as a [role-assignable group](groups-concept.md). A service principal is an identity created for use with applications, hosted services, and automated tools to access Azure AD resources.
 
 ### Role definition
 
@@ -89,9 +91,17 @@ If you specify an Azure AD resource as a scope, it can be one of the following:
 
 For more information, see [Assign Azure AD roles at different scopes](assign-roles-different-scopes.md).
 
+## Role assignment options
+
+Azure AD provides multiple options for assigning roles:
+
+- You can assign roles to users directly, which is the default way to assign roles. Both built-in and custom Azure AD roles can be assigned to users, based on access requirements. For more information, see [Assign Azure AD roles to users](manage-roles-portal.md).
+- With Azure AD Premium P1, you can create role-assignable groups and assign roles to these groups. Assigning roles to a group instead of individuals allows for easy addition or removal of users from a role and creates consistent permissions for all members of the group. For more information, see [Assign Azure AD roles to groups](groups-assign-role.md).
+- With Azure AD Premium P2, you can use Azure AD Privileged Identity Management (Azure AD PIM) to provide just-in-time access to roles. This feature allows you to grant time-limited access to a role to users who require it, rather than granting permanent access. It also provides detailed reporting and auditing capabilities. For more information, see [Assign Azure AD roles in Privileged Identity Management](../privileged-identity-management/pim-how-to-add-role-to-user.md).
+
 ## License requirements
 
-Using built-in roles in Azure AD is free, while custom roles requires an Azure AD Premium P1 license. To find the right license for your requirements, see [Comparing generally available features of the Free and Premium editions](https://www.microsoft.com/security/business/identity-access-management/azure-ad-pricing).
+Using built-in roles in Azure AD is free, while custom roles require an Azure AD Premium P1 license. To find the right license for your requirements, see [Comparing generally available features of the Free and Premium editions](https://www.microsoft.com/security/business/identity-access-management/azure-ad-pricing).
 
 ## Next steps
 

articles/active-directory/roles/groups-assign-role.md

@@ -1,14 +1,14 @@
 ---
 title: Assign Azure AD roles to groups
-description: Assign Azure AD roles to role-assignable groups in the Azure portal, PowerShell, or Graph API.
+description: Assign Azure AD roles to role-assignable groups in the Azure portal, PowerShell, or Microsoft Graph API.
 services: active-directory
 author: rolyon
 manager: amycolannino
 ms.service: active-directory
 ms.workload: identity
 ms.subservice: roles
 ms.topic: how-to
-ms.date: 02/04/2022
+ms.date: 04/10/2023
 ms.author: rolyon
 ms.reviewer: vincesm
 ms.custom: it-pro
@@ -18,62 +18,111 @@ ms.collection: M365-identity-device-management
 
 # Assign Azure AD roles to groups
 
-This section describes how an IT admin can assign Azure Active Directory (Azure AD) role to an Azure AD group.
+To simplify role management, you can assign Azure AD roles to a group instead of individuals. This article describes how to assign Azure AD roles to [role-assignable groups](groups-concept.md) using the Azure portal, PowerShell, or Microsoft Graph API.
 
 ## Prerequisites
 
-- Azure AD Premium P1 or P2 license
-- Privileged Role Administrator or Global Administrator
-- AzureAD module when using PowerShell
+- Azure AD Premium P1 license
+- [Privileged Role Administrator](./permissions-reference.md#privileged-role-administrator) role
+- Microsoft.Graph module when using [Microsoft Graph PowerShell](/powershell/microsoftgraph/installation?branch=main)
+- AzureAD module when using [Azure AD PowerShell](/powershell/azure/active-directory/overview?branch=main)
 - Admin consent when using Graph explorer for Microsoft Graph API
 
 For more information, see [Prerequisites to use PowerShell or Graph Explorer](prerequisites.md).
 
 ## Azure portal
 
-Assigning a group to an Azure AD role is similar to assigning users and service principals except that only groups that are role-assignable can be used. In the Azure portal, only groups that are role-assignable are displayed.
+Assigning an Azure AD role to a group is similar to assigning users and service principals except that only groups that are role-assignable can be used.
 
-1. Sign in to the [Azure portal](https://portal.azure.com).
+> [!TIP]
+> These steps apply to customers that have an Azure AD Premium P1 license. If you have an Azure AD Premium P2 license in your tenant, you should instead follow steps in [Assign Azure AD roles in Privileged Identity Management](../privileged-identity-management/pim-how-to-add-role-to-user.md).
 
-1. Select **Azure Active Directory** > **Roles and administrators** and select the role you want to assign.
+1. Sign in to the [Azure portal](https://portal.azure.com) or [Microsoft Entra admin center](https://entra.microsoft.com).
 
-1. On the ***role name*** page, select > **Add assignment**.
+1. Select **Azure Active Directory** > **Roles and administrators** to see the list of all available roles.
 
-   ![Add the new role assignment](./media/groups-assign-role/add-assignment.png)
+    :::image type="content" source="media/common/roles-and-administrators.png" alt-text="Screenshot of Roles and administrators page in Azure Active Directory." lightbox="media/common/roles-and-administrators.png":::
 
-1. Select the group. Only the groups that can be assigned to Azure AD roles are displayed.
+1. Select the role name to open the role. Don't add a check mark next to the role.
 
-    [![Only groups that are assignable are shown for a new role assignment.](./media/groups-assign-role/eligible-groups.png "Only groups that are assignable are shown for a new role assignment.")](./media/groups-assign-role/eligible-groups.png#lightbox)
+    :::image type="content" source="media/common/role-select-mouse.png" alt-text="Screenshot that shows selecting a role." lightbox="media/common/role-select-mouse.png":::
 
-1. Select **Add**.
+1. Select **Add assignments**.
 
-For more information on assigning role permissions, see [Assign administrator and non-administrator roles to users](../fundamentals/active-directory-users-assign-role-azure-portal.md).
+    If you see something different from the following screenshot, you might have Azure AD Premium P2. For more information, see [Assign Azure AD roles in Privileged Identity Management](../privileged-identity-management/pim-how-to-add-role-to-user.md).
+
+    :::image type="content" source="media/groups-assign-role/add-assignments.png" alt-text="Screenshot of Add assignments pane to assign role to users or groups." lightbox="media/groups-assign-role/add-assignments.png":::
+
+1. Select the group you want to assign to this role. Only role-assignable groups are displayed.
+
+    If group isn't listed, you will need to create a role-assignable group. For more information, see [Create a role-assignable group in Azure Active Directory](groups-create-eligible.md).
+
+1. Select **Add** to assign the role to the group.
 
 ## PowerShell
 
-### Create a group that can be assigned to role
+# [Microsoft Graph PowerShell](#tab/ms-powershell)
+
+### Create a role-assignable group
+
+Use the [New-MgGroup](/powershell/module/microsoft.graph.groups/new-mggroup?branch=main) command to create a role-assignable group.
+
+```powershell
+Connect-MgGraph -Scopes "Group.ReadWrite.All","RoleManagement.ReadWrite.Directory"
+$group = New-MgGroup -DisplayName "Contoso_Helpdesk_Administrators" -Description "This group has Helpdesk Administrator built-in role assigned to it in Azure AD." -MailEnabled:$false -SecurityEnabled -MailNickName "contosohelpdeskadministrators" -IsAssignableToRole:$true
+```
+
+### Get the role definition you want to assign
+
+Use the [Get-MgRoleManagementDirectoryRoleDefinition](/powershell/module/microsoft.graph.devicemanagement.enrolment/get-mgrolemanagementdirectoryroledefinition?branch=main) command to get a role definition.
+
+```powershell
+$roleDefinition = Get-MgRoleManagementDirectoryRoleDefinition -Filter "displayName eq 'Helpdesk Administrator'"
+```
+
+### Create a role assignment
+
+Use the [New-MgRoleManagementDirectoryRoleAssignment](/powershell/module/microsoft.graph.devicemanagement.enrolment/new-mgrolemanagementdirectoryroleassignment?branch=main) command to assign the role.
+
+```powershell
+$roleAssignment = New-MgRoleManagementDirectoryRoleAssignment -DirectoryScopeId '/' -RoleDefinitionId $roleDefinition.Id -PrincipalId $group.Id
+```
+
+# [Azure AD PowerShell](#tab/aad-powershell)
+
+### Create a role-assignable group
+
+Use the [New-AzureADMSGroup](/powershell/module/azuread/new-azureadmsgroup?branch=main) command to create a role-assignable group.
 
 ```powershell
 $group = New-AzureADMSGroup -DisplayName "Contoso_Helpdesk_Administrators" -Description "This group is assigned to Helpdesk Administrator built-in role in Azure AD." -MailEnabled $false -SecurityEnabled $true -MailNickName "contosohelpdeskadministrators" -IsAssignableToRole $true 
 ```
 
-### Get the role definition for the role you want to assign
+### Get the role definition you want to assign
+
+Use the [Get-AzureADMSRoleDefinition](/powershell/module/azuread/get-azureadmsroledefinition?branch=main) command to get a role definition.
 
 ```powershell
 $roleDefinition = Get-AzureADMSRoleDefinition -Filter "displayName eq 'Helpdesk Administrator'" 
 ```
 
 ### Create a role assignment
 
+Use the [New-AzureADMSRoleAssignment](/powershell/module/azuread/new-azureadmsroleassignment?branch=main) command to assign the role.
+
 ```powershell
 $roleAssignment = New-AzureADMSRoleAssignment -DirectoryScopeId '/' -RoleDefinitionId $roleDefinition.Id -PrincipalId $group.Id 
 ```
 
+---
+
 ## Microsoft Graph API
 
-### Create a group that can be assigned Azure AD role
+### Create a role-assignable group
 
-Use the [Create group](/graph/api/group-post-groups) API to create a group.
+Use the [Create group](/graph/api/group-post-groups?branch=main) API to create a role-assignable group.
+
+**Request**
 
 ```http
 POST https://graph.microsoft.com/v1.0/groups
@@ -91,28 +140,74 @@ POST https://graph.microsoft.com/v1.0/groups
 }
 ```
 
-### Get the role definition
+**Response**
+
+```http
+HTTP/1.1 201 Created
+```
+
+### Get the role definition you want to assign
+
+Use the [List unifiedRoleDefinitions](/graph/api/rbacapplication-list-roledefinitions?branch=main) API to get a role definition.
 
-Use the [List unifiedRoleDefinitions](/graph/api/rbacapplication-list-roledefinitions) API to get a role definition.
+**Request**
 
 ```http
 GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleDefinitions?$filter = displayName eq 'Helpdesk Administrator'
 ```
 
+**Response**
+
+```json
+{
+    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#roleManagement/directory/roleDefinitions",
+    "value": [
+        {
+            "id": "729827e3-9c14-49f7-bb1b-9608f156bbb8",
+            "description": "Can reset passwords for non-administrators and Helpdesk Administrators.",
+            "displayName": "Helpdesk Administrator",
+            "isBuiltIn": true,
+            "isEnabled": true,
+            "resourceScopes": [
+                "/"
+            ],
+
+    ...
+
+```
+
 ### Create the role assignment
 
-Use the [Create unifiedRoleAssignment](/graph/api/rbacapplication-post-roleassignments) API to assign the role.
+Use the [Create unifiedRoleAssignment](/graph/api/rbacapplication-post-roleassignments?branch=main) API to assign the role.
+
+**Request**
 
 ```http
 POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments
 
 {
     "@odata.type": "#microsoft.graph.unifiedRoleAssignment",
-    "principalId": "<Object Id of Group>",
+    "principalId": "<Object ID of Group>",
+    "roleDefinitionId": "<ID of role definition>",
+    "directoryScopeId": "/"
+}
+```
+
+**Response**
+
+```json
+HTTP/1.1 201 Created
+Content-type: application/json
+{
+    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#roleManagement/directory/roleAssignments/$entity",
+    "id": "<Role assignment ID>",
     "roleDefinitionId": "<ID of role definition>",
+    "principalId": "<Object ID of Group>",
     "directoryScopeId": "/"
 }
+
 ```
+
 ## Next steps
 
 - [Use Azure AD groups to manage role assignments](groups-concept.md)