Practical Graph: Using Dynamic Entra ID Administrative Units

Dynamic Membership Depends on a Well-Maintained Directory

Updated 14-Sep-2023 (the administrative unit cmdlets are in the beta module of the Microsoft Graph PowerShell SDK V2).

Many of you commented positively about my coverage of the importance of having a standard process to create new Azure AD user accounts. The high-level message in the article is that organizations should pay attention to populating account properties because of the many ways that Microsoft 365 apps use these properties. In this article, I want to cover a preview feature called Dynamic Administrative Units.

You’re probably familiar with regular administrative units, containers that can hold user accounts, groups, and devices. Control over administrative units can be delegated to specific accounts or groups to support scenarios like country-level management of user accounts. In other words, if the User Administrator role for an administrative unit is assigned to a group, the members of the group can perform actions authorized by the role (like updating account properties) for any account in the administrative unit.

The Downside of Administrative Units

Administrative units are useful, but they have a downside. That is, the need for manual intervention to populate the members of the administrative unit and to maintain the membership thereafter. It’s perfectly feasible to make sure that administrative units have accurate memberships, perhaps with some PowerShell scripts in the mix, but it’s not interesting work.

Microsoft believes that they have a solution in dynamic administrative units, launched in preview in April 2022. Dynamic administrative units work just like dynamic Azure AD groups by using rules to calculate membership. The point is that if you go the extra mile to make sure that account properties are accurate, membership rules will find the right accounts or devices for a dynamic administrative unit. In the remainder of this article, we focus on using dynamic administrative units for accounts.

The cmdlets to work with administrative units are currently accessed through the beta endpoint. If you connect to V1.0 instead of beta, you won’t see the cmdlets described here.

Creating a Dynamic Administrative Unit

The approach taken to using dynamic administrative units is like dynamic groups. You need to know the appropriate properties to use for the membership rules. Typical choices include:

• Country
• Department
• Office

It’s important to know which account properties provide the foundation for a dynamic administrative unit. If these properties are absent or inaccurate, the membership rules won’t work. After deciding what properties to use, it’s a good idea to audit the properties. For instance, let’s assume that you plan to use the Department property to create a dynamic administrative unit for members of the IT Department. Running this PowerShell code will find the accounts:

Get-MgUser  -Filter "department eq 'IT'" | Format-Table DisplayName, UserPrincipalName -All

If you see the set of accounts you expect, you know that everything works. On the other hand, if some expected accounts aren’t present, it’s an indication that either some accounts need to have their properties updated or the query should be broadened to find those accounts.

To start, select Administrative Units from the Azure AD admin center menu and create a new unit. All administrative units start off as basic containers. When the new unit is available, open its properties and switch its membership type from Assigned (the default) to Dynamic User (Figure 1).

Finding Administrative Unit Members

The next step is to add membership rules to instruct Azure AD how to find the members. In Figure 2, we’ve enhanced the basic query to find accounts with a specific value in the Department property to check the property for two values and to exclude accounts belonging to contractors (using one of the customizable extension properties). Saving the rule forces Azure AD to check its syntax. However, you won’t know if the rule works until Azure AD evaluates the rule against the directory to find matching accounts.

The evaluation process should happen quite quickly (within 30 minutes). When it does, the accounts found by the query can be browsed and validated, as shown in Figure 3.

The underlying query to check the accounts retrieved from Azure AD is a little more complex because the extension attributes are held as a set called onPremisesExtensionAttributes. This kind of Graph request is called an advanced query, so we need to pass the ConsistencyLevel and CountVariable parameters. Here’s the command:

[array]Get-MgUser -Filter "onPremisesExtensionAttributes/extensionAttribute13 ne 'Contractor' and (department eq 'IT' or department eq 'Information Technology')" -All -ConsistencyLevel "eventual" -CountVariable count
Write-Host “Users found by query:” $Users.Value.displayName

After you’re happy that the query finds the correct user accounts, the dynamic administrative unit will continue to work as expected, assuming user account properties are correct. Once again, this underlines the importance of standardization during the account creation process.

Using PowerShell to Work with Administrative Units

The Microsoft Graph PowerShell SDK includes cmdlets to manage Azure AD administrative units. To start, the Get-MgBetaAdministrativeUnit cmdlet lists all the administrative units in the tenant:

Get-MgBetaAdministrativeUnit | Format-Table DisplayName, Description, Id

DisplayName                     Description                         Id
-----------                     -----------                         --
Ireland                         Ireland Region                      0ee53a45-bbee-4571-a407-56acc0b944a1
Information Technology Accounts Accounts for Information Technology 150dccad-f8b8-4e54-9246-89834b8b5a25
Guests AU                       Admin unit for guest accounts       34d9069c-f448-41af-b14e-a8a1f4f42e77
United States                   U.S. Region                         4d3ae8ee-212b-4be4-965c-8b5111d4488e
Engineering                     Engineering                         66faad17-cc6d-45bb-8d88-35789b9b3c00
Finance Department Users        Finance people                      de2615e8-7c99-446c-83bd-e3a80d11ce18

To see more information about the settings for an administrative unit, expand the AdditionalProperties property. This is where Azure AD holds information about the membership type and rule.

Get-MgBetaAdministrativeUnit -AdministrativeUnitId 150dccad-f8b8-4e54-9246-89834b8b5a25 | Select-Object -ExpandProperty AdditionalProperties

Key                           Value
---                           -----
@odata.context                https://graph.microsoft.com/beta/$metadata#administrativeUnits/$entity
membershipRule                (user.department -eq "IT") or (user.department -eq "Information Technology") and (user...
membershipType                Dynamic
membershipRuleProcessingState On

The membership rule is truncated in this output. To be certain to see the full rule, extract the properties and lookup the membership rule:

[array]$Properties = Get-MgBetaAdministrativeUnit -AdministrativeUnitId 150dccad-f8b8-4e54-9246-89834b8b5a25 | Select-Object -ExpandProperty AdditionalProperties
$Properties['membershipRule']

(user.department -eq "IT") or (user.department -eq "Information Technology") and (user.extensionAttribute13 -ne "Contractor")

To find the members of an administrative unit, run the Get-MgAdministrativeUnit cmdlet. This returns the object identifiers for the member accounts:

Get-MgBetaAdministrativeUnitMember -AdministrativeUnitId 150dccad-f8b8-4e54-9246-89834b8b5a25

Id                                   DeletedDateTime
--                                   ---------------
96155a51-6885-4c8f-a8b6-e1614af08675
8f94abd3-b46f-4072-8ef4-af7475401b2f

The other properties for the members are in the AdditionalProperties property. Here’s how to list the display names of the members.

[array]$Members = (Get-MgBetaAdministrativeUnitMember -AdministrativeUnitId 150dccad-f8b8-4e54-9246-89834b8b5a25).AdditionalProperties
$Members.displayName

In most cases, it’s easier to update administrative units through the Azure AD admin center. To do it with PowerShell, run the Update-MgAdministrativeUnit cmdlet. In this example, we first create a hash table to update the membership rule and then run the cmdlet to update the rule and the description and display name for the unit.

$NewRule = @{membershipRule='user.department eq "Group HQ"'}
Update-MgBetaAdministrativeUnit -AdministrativeUnitId  150dccad-f8b8-4e54-9246-89834b8b5a25 -AdditionalProperties $NewRule -Description "Changed because I can" -DisplayName 'Group HQ Users'

Not Email

It’s important to stress that an administrative unit exists purely as an aid for administrative operations. It’s not a source for email or a recipient for email. If you want dynamic membership for email, consider using a dynamic distribution list or a dynamic Microsoft 365 group. However, you could read the list of members from an administrative unit and add them as recipients to a message that’s sent using a Graph API.

The Directory’s the Key

Many benefits flow if an organization’s directory is well-maintained and populated with accurate information about user accounts. This is obvious when you consider administrative automation, but it’s also the case that Microsoft is leveraging the directory in many ways, such as adaptive scopes for retention policies. If you’ve done the hard work to create and maintain a well-managed directory, dynamic administrative units can help delegate user and device management away from tenant administrators.