Administrative unit with dynamic membership rules

Administrative units

Microsoft Entra administrative unit is a feature that allows you to subdivide your organization into any unit that you want, and then assign specific administrators that can manage only the members of that unit.

Members of administrative units can be

• users
• groups
• devices

They are used to define scopes within an organization and restrict permissions accordingly.

You can manage administrative units using either the Microsoft Entra admin center, or with the Microsoft Graph.

Users can be added to an administrative unit either manually or automatically based on some rules. Let's focus this time only on dynamic membership rules.

Dynamic membership rules

With dynamic membership rules, you can create attribute-based rules for users who automatically become members of an administrative unit. Later, when some user doesn't match the rule, then the user is automatically removed from an administrative unit.

The criterion is described by an expression which contains user's properties.

Supported properties

Properties that can be used in rule expression are described in the table below. Most of them are identical with the properties defined on user resource type

Properties	Allowed values	Usage
accountEnabled	true, false	user.accountEnabled -eq true
dirSyncEnabled	true, false	user.dirSyncEnabled -eq true
employeeHireDate	DateTimeOffset or keyword system.now	user.employeeHireDate -eq "value"
city	Any string value or null	user.city -eq "value"
country	Any string value or null	user.country -eq "value"
companyName	Any string value or null	user.companyName -eq "value"
department	Any string value or null	user.department -eq "value"
displayName	Any string value	user.displayName -eq "value"
employeeId	Any string value	user.employeeId -eq "value"
facsimileTelephoneNumber	Any string value or null	user.facsimileTelephoneNumber -eq "value"
givenName	Any string value or null	user.givenName -eq "value"
jobTitle	Any string value or null	user.jobTitle -eq "value"
mail	SMTP address of the user	user.mail -eq "value"
mailNickName	mail alias of the user	user.mailNickName -eq "value"
memberOf	valid group object ID	user.memberof -any (group.objectId -in ['value'])
mobile	Any string value or null	user.mobile -eq "value"
objectId	GUID of the user object	user.objectId -eq "11111111-1111-1111-1111-111111111111"
onPremisesDistinguishedName	Any string value or null	user.onPremisesDistinguishedName -eq "value"
onPremisesSecurityIdentifier	On-premises security id (SID)	user.onPremisesSecurityIdentifier -eq "S-1-1-11-1111111111-1111111111-1111111111-1111111"
passwordPolicies	None, DisableStrongPassword, DisablePasswordExpiration, DisablePasswordExpiration, DisableStrongPassword	user.passwordPolicies -eq "DisableStrongPassword"
physicalDeliveryOfficeName	Any string value or null	user.physicalDeliveryOfficeName -eq "value"
postalCode	Any string value or null	user.postalCode -eq "value"
preferredLanguage	ISO 639-1 code	user.preferredLanguage -eq "en-US"
sipProxyAddress	Any string value or null	user.sipProxyAddress -eq "value"
state	Any string value or null	user.state -eq "value"
streetAddress	Any string value or null	user.streetAddress -eq "value"
surname	Any string value or nul	user.surname -eq "value"
telephoneNumber	Any string value or null	user.telephoneNumber -eq "value"
usageLocation	Two letter country or region code	user.usageLocation -eq "US"
userPrincipalName	Any string value	user.userPrincipalName -eq "alias@domain"
userType	member, guest, null	user.userType -eq "Member"
otherMails	Any string value	user.otherMails -contains "alias@domain"
proxyAddresses	SMTP: alias@domain smtp: alias@domain	user.proxyAddresses -contains "SMTP: alias@domain"

Supported expression operators

The table below contains expression operators that can be used

Operator	Syntax
Equals	-eq
Not equals	-ne
Starts with	-startsWith
Not starts with	-notStartsWith
Contains	-contains
Not contains	-notContains
Match	-match
Not match	-notMatch
In	-in
Not in	-notIn
Less than	-le
Greater than	-ge

For more rules check the documentation

Manage dynamic membership with the PowerShell SDK

Currently, dynamic membership rules are supported in beta version, so you need to use Microsoft.Graph.Beta module.

To create a new administrative unit, use New-MgBetaAdministrativeUnit cmdlet. Let's say, we want to create an administrative unit for all employess from the United States.

Import-Module Microsoft.Graph.Beta.Identity.DirectoryManagement

$params = @{
	displayName = 'USA'
	description = 'All employees from United States'
	membershipType = 'Dynamic'
	membershipRule = '(user.country -eq "United States") -or (user.country -eq "US")'
	membershipRuleProcessingState = "On"
}

New-MgBetaAdministrativeUnit -BodyParameter $params

It can take a few seconds until you will see a new administrative unit in the Microsoft Entra portal

To update an administrative unit, use Update-MgBetaAdministrativeUnit cmdlet. Update the existing administrative unit and reduce the members to managers from the United States only.

Import-Module Microsoft.Graph.Beta.Identity.DirectoryManagement

$params = @{
	displayName = "USA Managers"
	description = "All managers from United States"
	membershipRule = '((user.country -eq "United States") -or (user.country -eq "US")) -and (user.jobTitle -contains "Manager")'
}

Update-MgBetaAdministrativeUnit -AdministrativeUnitId $administrativeUnitId -BodyParameter $params