Merge pull request #238542 from rolyon/rolyon-aadroles-admin-units-restricted-management-preview-v2

[Azure AD roles] Restricted management administrative units v2 (Preview)

Author: ttorble

articles/active-directory/roles/TOC.yml

@@ -20,8 +20,12 @@
       href: m365-workload-docs.md
   - name: Use groups to manage role assignments
     href: groups-concept.md
-  - name: Administrative units  
-    href: administrative-units.md
+  - name: Administrative units
+    items:
+    - name: Administrative units
+      href: administrative-units.md
+    - name: Restricted management
+      href: admin-units-restricted-management.md
   - name: Best practices
     href: best-practices.md
   - name: Security

articles/active-directory/roles/admin-units-faq-troubleshoot.yml

@@ -10,7 +10,7 @@ metadata:
   ms.topic: faq
   ms.subservice: roles
   ms.workload: identity
-  ms.date: 06/30/2022
+  ms.date: 06/09/2023
   ms.author: rolyon
   ms.reviewer: anandy
   ms.custom: oldportal;it-pro;
@@ -117,6 +117,21 @@ sections:
         answer: |
           No.
 
+  - name: Restricted management administrative units (Preview)
+    questions:
+      - question: |
+          I am the owner of a group that is a member of a restricted management administrative unit. How are my permissions affected?
+        answer: |
+          As an owner of a protected group, you won't be able to manage it just based on ownership. Managing protected resources currently require a role to be assigned at the restricted management administrative unit scope of the protected resource.
+      - question: |
+          How are my Microsoft 365 resources affected by using restricted management administrative units?
+        answer: |
+          Currently, securing Azure AD resources in restricted management administrative units is supported. Resources managed outside of Azure AD aren't supported.
+      - question: |
+          I'm unable to modify a member of a restricted management administrative unit.
+        answer: |
+          The user, group, or device is a member of restricted management administrative unit. Management rights are limited to administrators scoped to that administrative unit.
+
 additionalContent: |
 
   ## Next steps

articles/active-directory/roles/admin-units-manage.md

@@ -9,7 +9,7 @@ ms.service: active-directory
 ms.topic: how-to
 ms.subservice: roles
 ms.workload: identity
-ms.date: 01/25/2023
+ms.date: 06/09/2023
 ms.author: rolyon
 ms.reviewer: anandy
 ms.custom: oldportal;it-pro;
@@ -18,6 +18,10 @@ ms.collection: M365-identity-device-management
 
 # Create or delete administrative units
 
+> [!IMPORTANT]
+> Restricted management administrative units are currently in PREVIEW.
+> See the [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) for legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.
+
 Administrative units let you subdivide your organization into any unit that you want, and then assign specific administrators that can manage only the members of that unit. For example, you could use administrative units to delegate permissions to administrators of each school at a large university, so they could control access, manage users, and set policies only in the School of Engineering.
 
 This article describes how to create or delete administrative units to restrict the scope of role permissions in Azure Active Directory (Azure AD).
@@ -26,8 +30,10 @@ This article describes how to create or delete administrative units to restrict
 
 - Azure AD Premium P1 or P2 license for each administrative unit administrator
 - Azure AD Free licenses for administrative unit members
-- Privileged Role Administrator or Global Administrator
+- Privileged Role Administrator role
+- Microsoft.Graph module when using [Microsoft Graph PowerShell](/powershell/microsoftgraph/installation)
 - AzureAD module when using PowerShell
+- AzureADPreview module when using PowerShell and restricted management administrative units
 - Admin consent when using Graph explorer for Microsoft Graph API
 
 For more information, see [Prerequisites to use PowerShell or Graph Explorer](prerequisites.md).
@@ -48,6 +54,8 @@ You can create a new administrative unit by using either the Azure portal, Power
 
 1. In the **Name** box, enter the name of the administrative unit. Optionally, add a description of the administrative unit.
 
+1. If you don't want tenant-level administrators to be able to access this administrative unit, set the **Restricted management administrative unit** toggle to **Yes**. For more information, see [Restricted management administrative units](admin-units-restricted-management.md).
+
     ![Screenshot showing the Add administrative unit page and the Name box for entering the name of the administrative unit.](./media/admin-units-manage/add-new-admin-unit.png)
 
 1. Optionally, on the **Assign roles** tab, select a role and then select the users to assign the role to with this administrative unit scope.
@@ -60,29 +68,59 @@ You can create a new administrative unit by using either the Azure portal, Power
 
 ### PowerShell
 
-Use the [New-AzureADMSAdministrativeUnit](/powershell/module/azuread/new-azureadmsadministrativeunit) command to create a new administrative unit.
+# [Microsoft Graph PowerShell](#tab/ms-powershell)
+
+Use the [Connect-MgGraph](/powershell/microsoftgraph/authentication-commands?branch=main#using-connect-mggraph) command to sign in to your tenant and consent to the required permissions.
 
 ```powershell
-New-AzureADMSAdministrativeUnit -Description "West Coast region" -DisplayName "West Coast"
+Connect-MgGraph -Scopes "AdministrativeUnit.ReadWrite.All"
 ```
 
-### Microsoft Graph PowerShell
+Use the [New-MgDirectoryAdministrativeUnit](/powershell/module/microsoft.graph.identity.directorymanagement/new-mgdirectoryadministrativeunit?branch=main) command to create a new administrative unit.
 
-Use the [New-MgDirectoryAdministrativeUnit](/powershell/module/microsoft.graph.identity.directorymanagement/new-mgdirectoryadministrativeunit) command to create a new administrative unit.
+```powershell
+$params = @{
+    DisplayName = "Seattle District Technical Schools"
+    Description = "Seattle district technical schools administration"
+    Visibility = "HiddenMembership"
+}
+$adminUnitObj = New-MgDirectoryAdministrativeUnit -BodyParameter $params
+```
+
+Use the [New-MgDirectoryAdministrativeUnit (beta)](/powershell/module/microsoft.graph.identity.directorymanagement/new-mgdirectoryadministrativeunit?view=graph-powershell-beta&preserve-view=true&branch=main) command to create a new restricted management administrative unit. Set the `IsMemberManagementRestricted` property to `$true`.
 
 ```powershell
-Import-Module Microsoft.Graph.Identity.DirectoryManagement
+Select-MgProfile -Name beta
 $params = @{
-	DisplayName = "Seattle District Technical Schools"
-	Description = "Seattle district technical schools administration"
-	Visibility = "HiddenMembership"
+    DisplayName = "Contoso Executive Division"
+    Description = "Contoso Executive Division administration"
+    Visibility = "HiddenMembership"
+    IsMemberManagementRestricted = $true
 }
-New-MgDirectoryAdministrativeUnit -BodyParameter $params
+$restrictedAU = New-MgDirectoryAdministrativeUnit -BodyParameter $params
 ```
 
+# [Azure AD PowerShell](#tab/aad-powershell)
+
+[!INCLUDE [Azure AD PowerShell migration](../includes/aad-powershell-migration-include.md)]
+
+Use the [New-AzureADMSAdministrativeUnit](/powershell/module/azuread/new-azureadmsadministrativeunit?branch=main) command to create a new administrative unit.
+
+```powershell
+$adminUnitObj = New-AzureADMSAdministrativeUnit -Description "West Coast region" -DisplayName "West Coast"
+```
+
+Use the [New-AzureADMSAdministrativeUnit (preview)](/powershell/module/azuread/new-azureadmsadministrativeunit?view=azureadps-2.0-preview&preserve-view=true&branch=main) command to create a new restricted management administrative unit. Set the `IsMemberManagementRestricted` parameter to `$true`.
+
+```powershell
+$restrictedAU = New-AzureADMSAdministrativeUnit -DisplayName "Contoso Executive Division" -IsMemberManagementRestricted $true
+```
+
+---
+
 ### Microsoft Graph API
 
-Use the [Create administrativeUnit](/graph/api/administrativeunit-post-administrativeunits) API to create a new administrative unit.
+Use the [Create administrativeUnit](/graph/api/administrativeunit-post-administrativeunits?branch=main) API to create a new administrative unit.
 
 Request
 
@@ -99,6 +137,24 @@ Body
 }
 ```
 
+Use the [Create administrativeUnit (beta)](/graph/api/directory-post-administrativeunits?view=graph-rest-beta&preserve-view=true&branch=main) API to create a new restricted management administrative unit. Set the `isMemberManagementRestricted` property to `true`.
+
+Request
+
+```http
+POST https://graph.microsoft.com/beta/administrativeUnits
+```
+
+Body
+
+```http
+{ 
+  "displayName": "Contoso Executive Division",
+  "description": "This administrative unit contains executive accounts of Contoso Corp.", 
+  "isMemberManagementRestricted": true
+}
+```
+
 ## Delete an administrative unit
 
 In Azure AD, you can delete an administrative unit that you no longer need as a unit of scope for administrative roles. Before you delete the administrative unit, you should remove any role assignments with that administrative unit scope.
@@ -125,13 +181,28 @@ In Azure AD, you can delete an administrative unit that you no longer need as a
 
 ### PowerShell
 
-Use the [Remove-AzureADMSAdministrativeUnit](/powershell/module/azuread/remove-azureadmsadministrativeunit) command to delete an administrative unit.
+# [Microsoft Graph PowerShell](#tab/ms-powershell)
+
+Use the [Remove-MgDirectoryAdministrativeUnit](/powershell/module/microsoft.graph.identity.directorymanagement/remove-mgdirectoryadministrativeunit?branch=main) command to delete an administrative unit.
+
+```powershell
+$adminUnitObj = Get-MgDirectoryAdministrativeUnit -Filter "DisplayName eq 'Seattle District Technical Schools'"
+Remove-MgDirectoryAdministrativeUnit -AdministrativeUnitId $adminUnitObj.Id
+```
+
+# [Azure AD PowerShell](#tab/aad-powershell)
+
+[!INCLUDE [Azure AD PowerShell migration](../includes/aad-powershell-migration-include.md)]
+
+Use the [Remove-AzureADMSAdministrativeUnit](/powershell/module/azuread/remove-azureadmsadministrativeunit?branch=main) command to delete an administrative unit.
 
 ```powershell
-$adminUnitObj = Get-AzureADMSAdministrativeUnit -Filter "displayname eq 'DeleteMe Admin Unit'"
+$adminUnitObj = Get-AzureADMSAdministrativeUnit -Filter "DisplayName eq 'Seattle District Technical Schools'"
 Remove-AzureADMSAdministrativeUnit -Id $adminUnitObj.Id
 ```
 
+---
+
 ### Microsoft Graph API
 
 Use the [Delete administrativeUnit](/graph/api/administrativeunit-delete) API to delete an administrative unit.
@@ -144,3 +215,4 @@ DELETE https://graph.microsoft.com/v1.0/directory/administrativeUnits/{admin-uni
 
 - [Add users, groups, or devices to an administrative unit](admin-units-members-add.md)
 - [Assign Azure AD roles with administrative unit scope](admin-units-assign-roles.md)
+- [Azure AD administrative units: Troubleshooting and FAQ](admin-units-faq-troubleshoot.yml)

articles/active-directory/roles/admin-units-members-add.md

@@ -9,7 +9,7 @@ ms.service: active-directory
 ms.topic: how-to
 ms.subservice: roles
 ms.workload: identity
-ms.date: 10/05/2022
+ms.date: 06/09/2023
 ms.author: rolyon
 ms.reviewer: anandy
 ms.custom: oldportal;it-pro;
@@ -18,7 +18,7 @@ ms.collection: M365-identity-device-management
 
 # Add users, groups, or devices to an administrative unit
 
-In Azure Active Directory (Azure AD), you can add users, groups, or devices to an administrative unit to restrict the scope of role permissions. Adding a group to an administrative unit brings the group itself into the management scope of the administrative unit, but **not** the members of the group. For additional details on what scoped administrators can do, see [Administrative units in Azure Active Directory](administrative-units.md).
+In Azure Active Directory (Azure AD), you can add users, groups, or devices to an administrative unit to limit the scope of role permissions. Adding a group to an administrative unit brings the group itself into the management scope of the administrative unit, but **not** the members of the group. For additional details on what scoped administrators can do, see [Administrative units in Azure Active Directory](administrative-units.md).
 
 This article describes how to add users, groups, or devices to administrative units manually. For information about how to add users or devices to administrative units dynamically using rules, see [Manage users or devices for an administrative unit with dynamic membership rules](admin-units-members-dynamic.md).
 

articles/active-directory/roles/admin-units-members-list.md

@@ -9,7 +9,7 @@ ms.service: active-directory
 ms.topic: how-to
 ms.subservice: roles
 ms.workload: identity
-ms.date: 06/01/2022
+ms.date: 06/09/2023
 ms.author: rolyon
 ms.reviewer: anandy
 ms.custom: oldportal;it-pro;
@@ -82,6 +82,20 @@ You can list the users, groups, or devices in administrative units using the Azu
 
     ![Screenshot of All devices page with an administrative unit filter.](./media/admin-units-members-list/device-admin-unit-filter.png)
 
+### List the restricted management administrative units for a single user or group
+
+1. Sign in to the [Azure portal](https://portal.azure.com).
+
+1. Select **Azure Active Directory**.
+
+1. Select **Users** or **Groups** and then select the user or group you want to list their restricted management administrative units.
+
+1. Select **Administrative units** to list all the administrative units where the user or group is a member.
+
+1. In the **Restricted management** column, look for administrative units that are set to **Yes**.
+
+    ![Screenshot of the Administrative units page with the Restricted management column.](./media/admin-units-members-list/list-restricted-management-admin-unit.png)
+
 ## PowerShell
 
 Use the [Get-AzureADMSAdministrativeUnit](/powershell/module/azuread/get-azureadmsadministrativeunit) and [Get-AzureADMSAdministrativeUnitMember](/powershell/module/azuread/get-azureadmsadministrativeunitmember) commands to list users or groups for an administrative unit.
@@ -146,40 +160,55 @@ foreach ($member in (Get-AzureADMSAdministrativeUnitMember -Id $adminUnitObj.Id)
 
 ## Microsoft Graph API
 
-Use the [List members](/graph/api/administrativeunit-list-members) API to list users or groups for an administrative unit.
-
-Use the [List members (Beta)](/graph/api/administrativeunit-list-members?view=graph-rest-beta&preserve-view=true) API to list devices for an administrative unit.
-
 ### List the administrative units for a user
 
+Use the user [List memberOf](/graph/api/user-list-memberof) API to list the administrative units a user is a direct member of.
+
 ```http
 GET https://graph.microsoft.com/v1.0/users/{user-id}/memberOf/$/Microsoft.Graph.AdministrativeUnit
 ```
 
 ### List the administrative units for a group
 
+Use the group [List memberOf](/graph/api/group-list-memberof) API to list the administrative units a group is a direct member of.
+
 ```http
 GET https://graph.microsoft.com/v1.0/groups/{group-id}/memberOf/$/Microsoft.Graph.AdministrativeUnit
 ```
 
 ### List the administrative units for a device
 
+Use the [List device memberships](/graph/api/device-list-memberof) API to list the administrative units a device is a direct member of.
+
 ```http
-GET https://graph.microsoft.com/beta/devices/{device-id}/memberOf/$/Microsoft.Graph.AdministrativeUnit
+GET https://graph.microsoft.com/v1.0/devices/{device-id}/memberOf/$/Microsoft.Graph.AdministrativeUnit
 ```
 
-### List the groups for an administrative unit
+### List the users, groups, or devices for an administrative unit
+
+Use the [List members](/graph/api/administrativeunit-list-members) API to list the users, groups, or devices for an administrative unit. For member type, specify `microsoft.graph.user`, `microsoft.graph.group`, or `microsoft.graph.device`.
 
 ```http
 GET https://graph.microsoft.com/v1.0/directory/administrativeUnits/{admin-unit-id}/members/$/microsoft.graph.group
 ```
 
-### List the devices for an administrative unit
+### List whether a single user is in a restricted management administrative unit
+
+Use the [Get a user (beta)](/graph/api/user-get?view=graph-rest-beta&preserve-view=true) API to determine whether a user is in a restricted management administrative unit. Look at the value of the `isManagementRestricted` property. If the property is `true`, it is in a restricted management administrative unit. If the property is `false`, empty, or null, it is not in a restricted management administrative unit.
 
 ```http
-GET https://graph.microsoft.com/beta/administrativeUnits/{admin-unit-id}/members/$/microsoft.graph.device
+GET https://graph.microsoft.com/beta/users/{user-id}
 ```
 
+Response
+
+```
+{ 
+  "displayName": "John",
+  "isManagementRestricted": true,
+  "userPrincipalName": "[email protected]", 
+}
+```
 
 ## Next steps
 

articles/active-directory/roles/admin-units-members-remove.md

@@ -9,7 +9,7 @@ ms.service: active-directory
 ms.topic: how-to
 ms.subservice: roles
 ms.workload: identity
-ms.date: 03/22/2022
+ms.date: 06/09/2023
 ms.author: rolyon
 ms.reviewer: anandy
 ms.custom: oldportal;it-pro;
@@ -128,26 +128,12 @@ Remove-AzureADMSAdministrativeUnitMember -ObjectId $adminUnitId -MemberId $devic
 ```
 ## Microsoft Graph API
 
-Use the [Remove a member](/graph/api/administrativeunit-delete-members) API to remove users or groups from an administrative unit.
+Use the [Remove a member](/graph/api/administrativeunit-delete-members) API to remove users, groups, or devices from an administrative unit. For `{member-id}`, specify the user, group, or device ID.
 
-Use the [Remove a member (Beta)](/graph/api/administrativeunit-delete-members?view=graph-rest-beta&preserve-view=true) API to remove devices from an administrative unit.
-
-### Remove users from an administrative unit
-
-```http
-DELETE https://graph.microsoft.com/v1.0/directory/administrativeUnits/{admin-unit-id}/members/{user-id}/$ref
-```
-
-### Remove groups from an administrative unit
-
-```http
-DELETE https://graph.microsoft.com/v1.0/directory/administrativeUnits/{admin-unit-id}/members/{group-id}/$ref
-```
-
-### Remove devices from an administrative unit
+### Remove users, groups, or devices from an administrative unit
 
 ```http
-DELETE https://graph.microsoft.com/beta/administrativeUnits/{admin-unit-id}/members/{device-id}/$ref
+DELETE https://graph.microsoft.com/v1.0/directory/administrativeUnits/{admin-unit-id}/members/{member-id}/$ref
 ```
 
 ## Next steps