Merge pull request #25498 from microsoftgraph/rbac-AUs

Entra admin roles - AUs

Author: Lauragra

api-reference/beta/api/administrativeunit-delta.md

@@ -25,6 +25,8 @@ Choose the permission or permissions marked as least privileged for this API. Us
 <!-- { "blockType": "permissions", "name": "administrativeunit_delta" } -->
 [!INCLUDE [permissions-table](../includes/permissions/administrativeunit-delta-permissions.md)]
 
+[!INCLUDE [rbac-admin-units-apis-read](../includes/rbac-for-apis/rbac-admin-units-apis-read.md)]
+
 ## HTTP request
 
 To begin tracking changes, you make a request that includes the delta function on the **administrativeUnit** resource.
@@ -44,7 +46,7 @@ You only need to specify any query parameters once up front.
 In subsequent requests, copy and apply the `@odata.nextLink` or `@odata.deltaLink` URL from the previous response. That URL already
 includes the encoded parameters.
 
-| Query parameter	   | Type	|Description|
+| Query parameter       | Type    |Description|
 |:---------------|:--------|:----------|
 | $deltatoken | string | A [state token](/graph/delta-query-overview) returned in the `@odata.deltaLink` URL of the previous **delta** function call for the same resource collection, indicating the completion of that round of change tracking. Save and apply the entire `@odata.deltaLink` URL including this token in the first request of the next round of change tracking for that collection.|
 | $skiptoken | string | A [state token](/graph/delta-query-overview) returned in the `@odata.nextLink` URL of the previous **delta** function call, indicating there are further changes to be tracked in the same resource collection. |

api-reference/beta/api/administrativeunit-get-members.md

@@ -24,6 +24,8 @@ Choose the permission or permissions marked as least privileged for this API. Us
 <!-- { "blockType": "permissions", "name": "administrativeunit_get_members" } -->
 [!INCLUDE [permissions-table](../includes/permissions/administrativeunit-get-members-permissions.md)]
 
+[!INCLUDE [rbac-admin-units-apis-read](../includes/rbac-for-apis/rbac-admin-units-apis-read.md)]
+
 ## HTTP request
 
 ```http

api-reference/beta/api/administrativeunit-get-scopedrolemembers.md

@@ -24,6 +24,8 @@ Choose the permission or permissions marked as least privileged for this API. Us
 <!-- { "blockType": "permissions", "name": "administrativeunit_get_scopedrolemembers" } -->
 [!INCLUDE [permissions-table](../includes/permissions/administrativeunit-get-scopedrolemembers-permissions.md)]
 
+[!INCLUDE [rbac-admin-units-apis-read](../includes/rbac-for-apis/rbac-admin-units-apis-read.md)]
+
 ## HTTP request
 <!-- { "blockType": "ignored" } -->
 ```http

api-reference/beta/api/administrativeunit-list-scopedrolemembers.md

@@ -24,6 +24,8 @@ Choose the permission or permissions marked as least privileged for this API. Us
 <!-- { "blockType": "permissions", "name": "administrativeunit_list_scopedrolemembers" } -->
 [!INCLUDE [permissions-table](../includes/permissions/administrativeunit-list-scopedrolemembers-permissions.md)]
 
+[!INCLUDE [rbac-admin-units-apis-read](../includes/rbac-for-apis/rbac-admin-units-apis-read.md)]
+
 ## HTTP request
 <!-- { "blockType": "ignored" } -->
 ```http

api-reference/beta/api/administrativeunit-post-members.md

@@ -30,7 +30,7 @@ One of the following permissions is required to call this API. To learn more, in
 |Delegated (personal Microsoft account) | Not supported.    |
 |Application | AdministrativeUnit.ReadWrite.All |
 
-To add a user, group, or device to an administrative unit, the calling user must be assigned the *Privileged Role Administrator* [Microsoft Entra role](/entra/identity/role-based-access-control/permissions-reference?toc=%2Fgraph%2Ftoc.json).
+[!INCLUDE [rbac-admin-units-apis-write](../includes/rbac-for-apis/rbac-admin-units-apis-write.md)]
 
 ### Permissions to create a new group
 <!-- { "blockType": "ignored"  } // Note: Removing this line will result in the permissions autogeneration tool overwriting the table. -->
@@ -40,12 +40,12 @@ To add a user, group, or device to an administrative unit, the calling user must
 |Delegated (personal Microsoft account) | Not supported.    |
 |Application | Group.Create and AdministrativeUnit.Read.All, Group.ReadWrite.All and AdministrativeUnit.Read.All, Directory.ReadWrite.All |
 
-To create a new group in an administrative unit, the calling principal must be assigned at least one of the following [Microsoft Entra roles](/entra/identity/role-based-access-control/permissions-reference?toc=%2Fgraph%2Ftoc.json) at the scope of the administrative unit:
-
-* Groups Administrator
-* User Administrator
-
-When these roles are assigned to a service principal, additional permissions are required to read the directory, such as assignment to the Directory Readers role, or having Microsoft Graph application permissions, such as Directory.Read.All.
+> [!IMPORTANT]
+> To create a new group in an administrative unit, the calling principal must be assigned at least one of the following [Microsoft Entra roles](/entra/identity/role-based-access-control/permissions-reference?toc=%2Fgraph%2Ftoc.json) at the scope of the administrative unit:
+> - Groups Administrator
+> - User Administrator
+>
+> For app-only scenarios - apart from these roles, the service principal requires additional permissions to read the directory. These permissions can be granted via assignment of supported Microsoft Entra roles, such the Directory Readers role; or they can be granted via Microsoft Graph application permissions that allow reading the directory, such as *Directory.Read.All*.
 
 ## HTTP request
 

api-reference/beta/api/administrativeunit-update.md

@@ -24,7 +24,7 @@ Choose the permission or permissions marked as least privileged for this API. Us
 <!-- { "blockType": "permissions", "name": "administrativeunit_update" } -->
 [!INCLUDE [permissions-table](../includes/permissions/administrativeunit-update-permissions.md)]
 
-In delegated scenarios, the signed-in user must also be assigned a supported [Microsoft Entra role](/entra/identity/role-based-access-control/permissions-reference?toc=%2Fgraph%2Ftoc.json) or a custom role with the `microsoft.directory/administrativeUnits/allProperties/allTasks` role permission. *Privileged Role Administrator* is the least privileged role for this operation.
+[!INCLUDE [rbac-admin-units-apis-write](../includes/rbac-for-apis/rbac-admin-units-apis-write.md)]
 
 ## HTTP request
 <!-- { "blockType": "ignored" } -->

api-reference/beta/api/directory-post-administrativeunits.md

@@ -24,7 +24,7 @@ Choose the permission or permissions marked as least privileged for this API. Us
 <!-- { "blockType": "permissions", "name": "directory_post_administrativeunits" } -->
 [!INCLUDE [permissions-table](../includes/permissions/directory-post-administrativeunits-permissions.md)]
 
-In delegated scenarios, the signed-in user must also be assigned a supported [Microsoft Entra role](/entra/identity/role-based-access-control/permissions-reference?toc=%2Fgraph%2Ftoc.json) or a custom role with the `microsoft.directory/administrativeUnits/allProperties/allTasks` role permission. *Privileged Role Administrator* is the least privileged role for this operation.
+[!INCLUDE [rbac-admin-units-apis-write](../includes/rbac-for-apis/rbac-admin-units-apis-write.md)]
 
 ## HTTP request
 <!-- { "blockType": "ignored" } -->

api-reference/beta/includes/rbac-for-apis/rbac-admin-units-apis-read.md

@@ -3,11 +3,9 @@ author: DougKirschner
 ms.topic: include
 ---
 
-In delegated scenarios with work or school accounts, the signed-in user must be a member user or be assigned a supported [Microsoft Entra role](/entra/identity/role-based-access-control/permissions-reference?toc=%2Fgraph%2Ftoc.json) or a custom role with a supported role permission. The following least privileged roles are supported for this operation.
-
-| Microsoft Entra role | Limitations | Key role permission |
-|--|--|--|
-| Directory Readers | Read basic properties on administrative units | microsoft.directory/administrativeUnits/standard/read |
-| Directory Readers | Read members of administrative units | microsoft.directory/administrativeUnits/members/read |
-| Global Reader | Read all properties of administrative units, including members | microsoft.directory/administrativeUnits/allProperties/read |
-| Privileged Role Administrator | Create and manage administrative units (including members) | microsoft.directory/administrativeUnits/allProperties/allTasks |
+> [!IMPORTANT]
+> 
+> In delegated scenarios with work or school accounts, the signed-in user must be a member user or be assigned a supported [Microsoft Entra role](/entra/identity/role-based-access-control/permissions-reference?toc=%2Fgraph%2Ftoc.json) or a custom role with a supported role permission. The following least privileged roles are supported for this operation.
+> - Directory Readers - Read *basic* properties and members of administrative units
+> - Global Reader - Read *all* properties of administrative units, including members 
+> - Privileged Role Administrator - Fully manage administrative units, including members, but excluding restricted administrative units. For more information, see [Restricted management administrative units in Microsoft Entra ID](/entra/identity/role-based-access-control/admin-units-restricted-management)

api-reference/beta/includes/rbac-for-apis/rbac-admin-units-apis-write.md

@@ -3,4 +3,6 @@ author: DougKirschner
 ms.topic: include
 ---
 
-In delegated scenarios with work or school accounts, the signed-in user must be a member user or be assigned a supported [Microsoft Entra role](/entra/identity/role-based-access-control/permissions-reference?toc=%2Fgraph%2Ftoc.json) or a custom role with the `microsoft.directory/administrativeUnits/allProperties/allTasks` role permission. *Privileged Role Administrator* is the least privileged role supported for this operation.
+> [!IMPORTANT]
+> 
+> In delegated scenarios with work or school accounts, the signed-in user must be a member user or be assigned a supported [Microsoft Entra role](/entra/identity/role-based-access-control/permissions-reference?toc=%2Fgraph%2Ftoc.json) or a custom role with a supported role permission. *Privileged Role Administrator* is the least privileged role supported for this operation.

api-reference/beta/resources/administrativeunit.md

@@ -95,6 +95,7 @@ The following JSON representation shows the resource type.
   "description": "String",
   "displayName": "String",
   "id": "String (identifier)",
+  "isMemberManagementRestricted": "Boolean",
   "visibility": "String",
   "membershipType": "String",
   "membershipRule": "String",