Create dynamic groups using Microsoft Entra rule builder

  • 10 minutes

Organizations can use rules to determine group membership. You can base these rules on user or device properties in Microsoft Entra ID. Microsoft 365 supports dynamic membership for Security groups and Microsoft 365 Groups.

When you create a group with dynamic membership, the system evaluates user and device attributes for matches with the membership rule. When an attribute changes for a user or device, the system examines all dynamic group rules in the organization for membership changes. It then adds or removes users and devices if they meet the conditions for a group.

Important

Organizations that implement dynamic groups must either have a Microsoft Entra Premium P1 license or a Microsoft Intune for Education license for each unique user that's a member of a dynamic group. 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 Microsoft Entra organization to cover all such users. For example, if you had a total of 1,000 unique users in all dynamic groups in your organization, you would need at least 1,000 licenses for Microsoft Entra Premium P1 to meet the license requirement. Organizations don't need a license for devices that are members of a dynamic device group.

Rule builder in the Microsoft Entra admin center

Microsoft Entra ID provides a rule builder tool to create and update your important rules more quickly. The rule builder supports the construction of up to five expressions. The rule builder makes it easier to form a rule with a few simple expressions. However, you can't use it to reproduce every rule. If the rule builder expressions don't support the rule you want to create, you can use the rule syntax text box.

The following list provides some examples of advanced rules or syntax that you should construct using the rule syntax text box:

Note

The rule builder may not be able to display some rules constructed in the text box. You may receive a message when the rule builder can't display the rule. The rule builder doesn't change the supported syntax, validation, or processing of dynamic group rules in any way.

Additional reading. For examples of syntax, supported properties, operators, and values for a membership rule, see Dynamic membership rules for groups in Microsoft Entra ID.

Perform the following steps to create a group membership rule:

  1. Navigate to the Microsoft Entra admin center (enter https://entra.microsoft.com, or from the Microsoft 365 admin center, select Show all, and then under Admin centers section select Identity). Sign in with an account that's either a Global administrator, Intune administrator, or User administrator in the Microsoft Entra organization.

  2. In the left-hand navigation pane, select Groups and then select All groups.

  3. On the Groups | All Groups window, select New group on the menu bar.

    Screenshot showing the All groups window in the Microsoft Entra admin center with the New group option highlighted.

  4. On the New Group page, enter the following information:

    • Group name
    • Group description
    • Microsoft Entra roles can be assigned to the group. Set the toggle switch to Yes or No.
    • Membership type. Select either Dynamic user or Dynamic device.

  5. Under the Owners section, select No owners selected. On the Add owners pane that appears, select the owners of the group.

  6. Under Dynamic user members, select Add dynamic query.

    Screenshot showing the New group window with the Add dynamic query option highlighted.

  7. On the Dynamic membership rules window that appears, the Configure Rules tab displays by default. You can use the rule builder or the rule syntax text box to create or edit a dynamic membership rule. The rule builder supports up to five expressions. To add more than five expressions, you must use the rule syntax text box.

    Screenshot showing the Dynamic membership rules window.

  8. To see the custom extension properties available for your membership query:

    1. Select +Get custom extension properties.
    2. In the Get custom extension properties pane that appears, enter the application ID and then select Refresh properties. Doing so displays the full list of custom extension properties to use when creating a dynamic membership rule. For more information on this feature, see the section at the end of this unit titled Extension properties and custom extension properties.

  9. After creating the rule, select Save.

  10. Select Create on the New group page to create the group.

If the rule you entered isn't valid, the system displays an explanation as to why it couldn't process the rule. This notification typically provides instruction on how to fix the rule.

Create a dynamic membership rule

Tip

This training introduces you to the basics of creating dynamic membership rules. It outlines the basic syntax used in a single expression, the supported values for expressions, rules for multiple and complex expressions, and extension properties. It also provides some basic examples of commonly used rules. If you're interested in more advanced guidance on rule syntax and various supported properties, see Dynamic membership rules for groups in Microsoft Entra ID.

Attribute-based rules enable dynamic membership for a group in Microsoft Entra ID. You can set up a rule for dynamic membership on security groups or Microsoft 365 groups. When a user or device's attributes 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 the rule for a group, the system automatically adds them as a member of that group. The system automatically removes them from group membership if they no longer satisfy the rule.

The following rules govern dynamic membership:

  • You can't manually add or remove a member of a dynamic group.
  • You can create a dynamic group for devices or users, but you can't create a rule that contains both users and devices.
  • You can't create a device group based on the user attributes of the device owner. Device membership rules can reference only device attributes.

Rule syntax for a single expression

A single expression is the simplest form of a membership rule. A rule with a single expression looks similar to this example: Property Operator Value, where the syntax for the property is the name of object.property.

The following example illustrates 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 can't exceed 3072 characters.

Supported expression operators

The following table lists all the supported operators and their syntax for a single expression. You can use operators with or without the hyphen (-) prefix. The Contains operator does partial string matches but not item matches in a collection.

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

If you want to compare the value of a user attribute against multiple 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:

user.department -in ["50001","50002","50003","50005","50006","50007","50008","50016","50020","50024","50038","50039","51100"]

You can use the -match operator for matching any regular expression.

Example 1:

user.displayName -match "Da.*"

In this example, "Da", "Dav", and "David" evaluate to True, while "aDa" evaluates to False.

Example 2:

user.displayName -match ".*vid"

In this example, "David" evaluates to True, while "Da" evaluates to False.

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

Tip

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

Supported properties

You can use three types of properties to construct a membership rule.

  • Boolean
  • String
  • String collection

Supported values

The values used in an expression can consist of several types, including:

  • Strings
  • Boolean – true, false
  • Numbers
  • Arrays – number array, string array

When specifying a value within an expression, it's important to use the correct syntax to avoid errors. Some syntax tips are:

  • Double quotes are optional unless the value is a string.
  • String and regex operations aren't case sensitive.
  • When a string value contains double quotes, you should escape both quotes using the ` character. For example, the proper syntax when “Sales “ is the value is: user.department -eq ` “Sales“ '
  • You should escape single quotes using two single quotes instead of one each time.
  • You can also perform Null checks, using null as a value. For example: user.department -eq null

Rules with multiple expressions

A group membership rule can consist of more than one single expression connected by the -and, -or, and -not logical operators. You can also use logical operators in combination.

The following are examples of properly constructed membership rules with multiple expressions:

(user.department -eq “Sales“) -or (user.department -eq “Marketing“)

(user.department -eq “Sales“) -and -not (user.jobTitle -contains “SDE“)

Rules with complex expressions

A membership rule can consist of complex expressions where the properties, operators, and values take on more complex forms. The system considers an expression complex when any of the following are true:

  • The property consists of a collection of values; specifically, multi-valued properties.
  • The expressions use the -any and -all operators.
  • The value of the expression can itself be one or more expressions.

Examples of 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 system automatically adjusts the group's membership.

You can construct the direct reports rule 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. You can find the Manager ID in the manager's Profile.
  • For the rule to work, ensure you correctly set the Manager property for users in your organization. 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.
  • You can't combine this rule with any other membership rules.

Create an All Users rule

You can create a group containing all users within an organization using a membership rule. When you add or remove users in the future, the system automatically adjusts the group's membership.

You construct the All Users rule using a single expression containing the -ne operator and the null value. This rule adds B2B guest users and member users to a group.

user.objectId -ne null

If you want your group to exclude guest users and include only members of your organization, you can use the following syntax:

(user.objectId -ne null) -and (user.userType -eq “Member“)

Create an All devices rule

You can create a group containing all devices within an organization using a membership rule. As with users, when you add or remove devices in the future, the system automatically adjusts the group's membership.

You construct the All Devices rule using a single expression containing the -ne operator and the null value:

device.objectId -ne null

Extension properties and custom extension properties

The system supports extension attributes and custom extension properties as string properties in dynamic membership rules. It syncs Extension attributes from on-premises Window Server Active Directory or updates using Microsoft Graph. These attributes take the format of extensionAttributeX, where X equals 1 - 15.

Caution

The system doesn't support multi-value extension properties in dynamic membership rules.

The following example displays a rule that uses an extension attribute as a property:

(user.extensionAttribute15 -eq “Marketing“)

You can sync custom extension properties from:

  • on-premises Windows Server Active Directory
  • a connected SaaS application
  • created using Microsoft Graph

Custom extension properties must use the format of user.extension_[GUID]_[Attribute], where:

  • [GUID] is the stripped version of the unique identifier in Microsoft Entra ID for the application that created the property. It contains only characters 0-9 and A-Z.
  • [Attribute] is the name of the property when originally created.

An example of a rule that uses a custom extension property is:

user.extension_c272a57b722d4eb29bfe327874ae79cb_OfficeNumber -eq "123"

Custom extension properties are also called directory or Microsoft Entra extension properties.

You can find the custom property name in the directory by querying a user's property using Graph Explorer and searching for the property name. Also, you can now select the Get custom extension properties link in the dynamic user group rule builder to enter a unique app ID. Doing so displays the full list of custom extension properties to use when creating a dynamic membership rule. You can refresh this list to get any new custom extension properties for that app. Extension attributes and custom extension properties must be from applications in your tenant.