In this article

Dynamic membership rules for groups in Azure Active Directory

08/01/2018

11 minutes to read

Contributors

In this article

In Azure Active Directory (Azure AD), you can create complex attribute-based rules to enable dynamic memberships for groups. Dynamic group membership reduces the administrative overhead of adding and removing users. This article details the properties and syntax to create dynamic membership rules for users or devices. You can set up a rule for dynamic membership on security groups or Office 365 groups.

When any attributes of a user or device change, the system evaluates all dynamic group rules in a directory to see if the change would trigger any group adds or removes. If a user or device satisfies a rule on a group, they are added as a member of that group. If they no longer satisfy the rule, they are removed.

You can create a dynamic group for devices or for users, but you can't create a rule that contains both users and devices.

You can't create a device group based on the device owners' attributes. Device membership rules can only reference device attributes.

Note

This feature requires an Azure AD Premium P1 license for each unique user that is a member of one or more dynamic groups. You don't have to assign licenses to users for them to be members of dynamic groups, but you must have the minimum number of licenses in the tenant to cover all such users. For example, if you had a total of 1,000 unique users in all dynamic groups in your tenant, you would need at least 1,000 licenses for Azure AD Premium P1 to meet the license requirement.

Constructing the body of a membership rule

A membership rule that automatically populates a group with users or devices is a binary expression that results in a true or false outcome. The three parts of a simple rule are:

Property

Operator

Value

The order of the parts within an expression are important to avoid syntax errors.

Rules with a single expression

A single expression is the simplest form of a membership rule and only has the three parts mentioned above. A rule with a single expression looks similar to this: Property Operator Value, where the syntax for the property is the name of object.property.

The following is an example of a properly constructed membership rule with a single expression:

user.department -eq "Sales"

Parentheses are optional for a single expression. The total length of the body of your membership rule cannot exceed 2048 characters.

Supported properties

There are three types of properties that can be used to construct a membership rule.

Boolean

String

String collection

The following are the user properties that you can use to create a single expression.

Properties of type boolean

Properties

Allowed values

Usage

accountEnabled

true false

user.accountEnabled -eq true

dirSyncEnabled

true false

user.dirSyncEnabled -eq true

Properties of type string

Properties

Allowed values

Usage

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")(user.employeeId -ne null)

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

Any string value or null (SMTP address of the user)

(user.mail -eq "value")

mailNickName

Any string value (mail alias of the user)

(user.mailNickName -eq "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")

onPremisesSecurityIdentifier

On-premises security identifier (SID) for users who were synchronized from on-premises to the cloud.

Supported operators

The following table lists all the supported operators and their syntax for a single expression. Operators can be used with or without the hyphen (-) prefix.

Operator

Syntax

Not Equals

-ne

Equals

-eq

Not Starts With

-notStartsWith

Starts With

-startsWith

Not Contains

-notContains

Contains

-contains

Not Match

-notMatch

Match

-match

In

-in

Not In

-notIn

Using the -In and -notIn operators

If you want to compare the value of a user attribute against a number of different values you can use the -In or -notIn operators. Use the bracket symbols "[" and "]" to begin and end the list of values.

In the following example, the expression evaluates to true if the value of user.department equals any of the values in the list:

The following is an example of operator precedence where two expressions are being evaluated for the user:

user.department –eq "Marketing" –and user.country –eq "US"

Parentheses are needed only when precedence does not meet your requirements. For example, if you want department to be evaluated first, the following shows how parentheses can be used to determine order:

Using the -any and -all operators

You can use -any and -all operators to apply a condition to one or all of the items in the collection, respectively.

-any (satisfied when at least one item in the collection matches the condition)

-all (satisfied when all items in the collection match the condition)

Example 1

assignedPlans is a multi-value property that lists all service plans assigned to the user. The following expression selects users who have the Exchange Online (Plan 2) service plan (as a GUID value) that is also in Enabled state:

Using the underscore (_) syntax

The underscore (_) syntax matches occurrences of a specific value in one of the multivalued string collection properties to add users or devices to a dynamic group. It is used with the -any or -all operators.

Here's an example of using the underscore (_) in a rule to add members based on user.proxyAddress (it works the same for user.otherMails). This rule adds any user with proxy address that contains "contoso" to the group.

(user.proxyAddresses -any (_ -contains "contoso"))

Other properties and common rules

Create a "Direct reports" rule

You can create a group containing all direct reports of a manager. When the manager's direct reports change in the future, the group's membership is adjusted automatically.

The direct reports rule is constructed using the following syntax:

Direct Reports for "{objectID_of_manager}"

Here's an example of a valid rule where “62e19b97-8b3d-4d4a-a106-4ce66896a863” is the objectID of the manager:

Direct Reports for "62e19b97-8b3d-4d4a-a106-4ce66896a863"

The following tips can help you use the rule properly.

The Manager ID is the object ID of the manager. It can be found in the manager's Profile.

For the rule to work, make sure the Manager property is set correctly for users in your tenant. You can check the current value in the user's Profile.

This rule supports only the manager's direct reports. In other words, you can't create a group with the manager's direct reports and their reports.

This rule can't be combined with any other membership rules.

Create an "All users" rule

You can create a group containing all users within a tenant using a membership rule. When users are added or removed from the tenant in the future, the group's membership is adjusted automatically.

The “All users” rule is constructed using single expression using the -ne operator and the null value. This rule adds B2B guest users as well as member users to the group.

user.objectid -ne null

Create an “All devices” rule

You can create a group containing all devices within a tenant using a membership rule. When devices are added or removed from the tenant in the future, the group's membership is adjusted automatically.

The “All Devices” rule is constructed using single expression using the -ne operator and the null value:

device.objectid -ne null

Extension properties and custom extension properties

Extension attributes and custom extenson properties are supported as string properties in dynamic membership rules. Extension attributes are synced from on-premises Window Server AD and take the format of "ExtensionAttributeX", where X equals 1 - 15. Here's an example of a rule that uses an extension attribute as a property:

(user.extensionAttribute15 -eq "Marketing")

Custom extension properties are synced from on-premises Windows Server AD or from a connected SaaS application and are of the format of user.extension_[GUID]__[Attribute], where:

[GUID] is the unique identifier in Azure AD for the application that created the property in Azure AD