Edit

Manage users or devices for an administrative unit with dynamic membership rules (Preview)

  • Article

Important

Dynamic membership rules for administrative units are currently in PREVIEW. See the Product Terms for legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.

You can add or remove users or devices for administrative units manually. With this preview, you can add or remove users or devices for administrative units dynamically using rules. This article describes how to create administrative units with dynamic membership rules using the Microsoft Entra admin center, PowerShell, or Microsoft Graph API.

Note

Dynamic membership rules for administrative units can be created using the same attributes available for dynamic groups. For more information about the specific attributes available and examples on how to use them, see Dynamic membership rules for groups in Microsoft Entra ID.

Although administrative units with members assigned manually support multiple object types, such as user, group, and devices, it is currently not possible to create an administrative unit with dynamic membership rules that includes more than one object type. For example, you can create administrative units with dynamic membership rules for users or devices, but not both. Administrative units with dynamic membership rules for groups are currently not supported.

Prerequisites

  • Microsoft Entra ID P1 or P2 license for each administrative unit administrator
  • Microsoft Entra ID P1 or P2 license for each administrative unit member
  • Privileged Role Administrator or Global Administrator
  • Microsoft Graph PowerShell SDK installed when using PowerShell
  • Admin consent when using Graph Explorer for Microsoft Graph API
  • Global Azure cloud (not available in specialized clouds, such as Azure Government or Microsoft Azure operated by 21Vianet)

Note

Dynamic membership rules for administrative units requires a Microsoft Entra ID P1 license for each unique user that is a member of one or more dynamic administrative units. You don't have to assign licenses to users for them to be members of dynamic administrative units, but you must have the minimum number of licenses in the Microsoft Entra organization to cover all such users. For example, if you had a total of 1,000 unique users in all dynamic administrative units in your organization, you would need at least 1,000 licenses for Microsoft Entra ID P1 to meet the license requirement. No license is required for devices that are members of a dynamic device administrative unit.

For more information, see Prerequisites to use PowerShell or Graph Explorer.

Add dynamic membership rules

Follow these steps to create administrative units with dynamic membership rules for users or devices.

Microsoft Entra admin center

Tip

Steps in this article might vary slightly based on the portal you start from.

  1. Sign in to the Microsoft Entra admin center as at least a Privileged Role Administrator.

  2. Select the administrative unit that you want to add users or devices to.

  3. Select Properties.

  4. In the Membership type list, select Dynamic User or Dynamic Device, depending on the type of rule you want to add.

    Screenshot of an administrative unit Properties page with Membership type list displayed.

  5. Select Add dynamic query.

  6. Use the rule builder to specify the dynamic membership rule. For more information, see Rule builder in the Azure portal.

    Screenshot of Dynamic membership rules page showing rule builder with property, operator, and value.

  7. When finished, select Save to save the dynamic membership rule.

  8. On the Properties page, select Save to save the membership type and query.

    The following message is displayed:

    After changing the administrative unit type, the existing membership might change based on the dynamic membership rule you provide.

  9. Select Yes to continue.

For steps on how to edit your rule, see the following Edit dynamic membership rules section.

PowerShell

  1. Create a dynamic membership rule. For more information, see Dynamic membership rules for groups in Microsoft Entra ID.

  2. Use the Connect-MgGraph command to connect with Microsoft Entra ID with a user that has been assigned the Privileged Role Administrator or Global Administrator role.

    Connect-MgGraph -Scopes "AdministrativeUnit.ReadWrite.All"

  3. Use the New-MgDirectoryAdministrativeUnit command to create a new administrative unit with a dynamic membership rule using the following parameters:

    • MembershipType: Dynamic or Assigned
    • MembershipRule: Dynamic membership rule you created in a previous step
    • MembershipRuleProcessingState: On or Paused
    # Create an administrative unit for users in the United States
$params = @{
   displayName = "Example Admin Unit"
   description = "Example Dynamic Membership Admin Unit"
   membershipType = "Dynamic"
   membershipRule = "(user.country -eq 'United States')"
   membershipRuleProcessingState = "On"
}

New-MgDirectoryAdministrativeUnit -BodyParameter $params

Microsoft Graph API

  1. Create a dynamic membership rule. For more information, see Dynamic membership rules for groups in Microsoft Entra ID.

  2. Use the Create administrativeUnit API to create a new administrative unit with a dynamic membership rule.

    The following shows an example of a dynamic membership rule that applies to Windows devices.

    Request

    POST https://graph.microsoft.com/beta/administrativeUnits

    Body

    {
  "displayName": "Windows Devices",
  "description": "All Contoso devices running Windows",
  "membershipType": "Dynamic",
  "membershipRule": "(deviceOSType -eq 'Windows')",
  "membershipRuleProcessingState": "On"
}

Edit dynamic membership rules

When an administrative unit has been configured for dynamic membership, the usual commands to add or remove members for the administrative unit are disabled as the dynamic membership engine retains the sole ownership of adding or removing members. To make changes to the membership, you can edit the dynamic membership rules.

Microsoft Entra admin center

  1. Sign in to the Microsoft Entra admin center as at least a Privileged Role Administrator.

  2. Browse to Identity > Roles & admins > Admin units.

  3. Select the administrative unit that has the dynamic membership rules you want to edit.

  4. Select Membership rules to edit the dynamic membership rules using the rule builder.

    Screenshot of an administrative unit with Membership rules and Dynamic membership rules options to open rule builder.

    You can also open the rule builder by selecting Dynamic membership rules in the left navigation.

  5. When finished, select Save to save the dynamic membership rule changes.

PowerShell

Use the Update-MgDirectoryAdministrativeUnit command to edit the dynamic membership rule.

# Set a new dynamic membership rule for an administrative unit
$adminUnit = Get-MgDirectoryAdministrativeUnit -Filter "displayName eq 'Example Admin Unit'"
$params = @{
   membershipRule = "(user.country -eq 'Germany')"
}

Update-MgDirectoryAdministrativeUnit -AdministrativeUnitId $adminUnit.Id -BodyParameter $params

Microsoft Graph API

Use the Update administrativeUnit API to edit the dynamic membership rule.

Request

PATCH https://graph.microsoft.com/beta/administrativeUnits/{id}

Body

{
  "membershipRule": "(user.country -eq "Germany")"
}

Change a dynamic administrative unit to assigned

Follow these steps to change an administrative unit with dynamic membership rules to an administrative unit where members are manually assigned.

Microsoft Entra admin center

  1. Sign in to the Microsoft Entra admin center as at least a Privileged Role Administrator.

  2. Browse to Identity > Roles & admins > Admin units.

  3. Select the administrative unit that you want to change to assigned.

  4. Select Properties.

  5. In the Membership type list, select Assigned.

    Screenshot of an administrative unit Properties page with Membership type list displayed and Assigned selected.

  6. Select Save to save the membership type.

    The following message is displayed:

    After changing the administrative unit type, the dynamic rule will no longer be processed. Current administrative unit members will remain in the administrative unit and the administrative unit will have assigned membership.

  7. Select Yes to continue.

    When the membership type setting is changed from dynamic to assigned, the current members remain intact in the administrative unit. Additionally, the ability to add groups to the administrative unit is enabled.

PowerShell

Use the Update-MgDirectoryAdministrativeUnit command to edit the dynamic membership rule.

# Change an administrative unit to assigned
$adminUnit = Get-MgDirectoryAdministrativeUnit -Filter "displayName eq 'Example Admin Unit'"
$params = @{
   membershipRuleProcessingState = "Paused"
   membershipType = "Assigned"
}

Update-MgDirectoryAdministrativeUnit -AdministrativeUnitId $adminUnit.Id -BodyParameter $params

Microsoft Graph API

Use the Update administrativeUnit API to change the membership type setting.

Request

PATCH https://graph.microsoft.com/beta/administrativeUnits/{id}

Body

{
  "membershipType": "Assigned"
}

Next steps