Adaptive scopes

Microsoft 365 licensing guidance for security & compliance.

When you create a communication compliance policy or a policy for retention, you can add an adaptive scope for your policy. A single policy can have one or many adaptive scopes.

• An adaptive scope uses a query that you specify, so you can define the membership of users or groups included in that query. These dynamic queries run daily against the attributes or properties that you specify for the selected scope. You can use one or more adaptive scopes with a single policy.
• For example, you can assign different policy settings to users according to their department by using existing Microsoft Entra attributes without the administrative overhead of creating and maintaining groups for this purpose.

Advantages of using adaptive scopes

The advantages of using adaptive scopes include:

• No limits on the number of items per policy. Although adaptive policies are still subject to the maximum number of policies per tenant limitations, the more flexible configuration will likely result in far fewer policies.
• More powerful targeting for your policies. For example, you can assign different settings to users according to their geographical location without the administrative overhead of creating and maintaining groups.
• Query-based scopes provide resilience against business changes that might not be reliably reflected in group membership or external processes that rely on cross-department communication.
• A single policy can include locations for both Microsoft Teams and Viva Engage, whereas when you don’t use an adaptive scope, each location requires its own policy.
• Support for Microsoft Entra administrative units.

For specific advantages of using adaptive scopes specific to policies for retention, see Learn about retention policies and retention labels.

For configuration information, see Configuring adaptive scopes.

How adaptive scopes work with Microsoft Entra administrative units

Whereas adaptive scopes are created and configured in Microsoft Purview to support the dynamic targeting of policies for compliance, administrative units are created and configured in Microsoft Entra ID. They provide the ability to assign admins to one or more administrative units, with the result that these now restricted admins can manage only the users in their assigned administrative units. This configuration supports the security best practice of least privilege. Typically, administrative units are designed around specific geography, department, or business divisions.

This boundary of management flows into Microsoft Purview for supported solutions to ensure that restricted admins can manage only the users they have been assigned to manage.

As an example to show how administrative units integrate with adaptive scopes, where a restricted compliance admin wants to create an adaptive user scope just for users in France:

1. A compliance admin is assigned two administrative units, All users in Europe and All users in North America. When they create an adaptive scope, they can select and assign only these administrative units. They can't create an adaptive scope to manage users from other administrative units.
2. They create a new adaptive scope for users and select the administrative unit All users in Europe. Then, because they want the adaptive scope to be only for users in France, they use the Microsoft Entra ID Country or region attribute to specify France (CountryOrRegion = France). If they misconfigure this attribute and specify a valid value in Microsoft Entra ID, such as India, but the users with that value aren't included in the All users in Europe administrative unit, the scope won't contain any users.
3. When just this adaptive scope is selected for a policy that's targeted to all users, the policy is applied just to users in France.
4. As a reusable configuration element, the same adaptive scope can be used for other compliance policies.

If the compliance admin had added both of the administrative units to this adaptive scope, the end result would still be the same because users in the North America administrative scope don't have France specified as their country or region attribute. However, the compliance admin knew that they needed to target just users in France, so it's more efficient to run the query against just the Europe administrative unit. If requirements change, you can always add or remove administrative units from an existing adaptive scope.

Maximums for adaptive policy scopes

There's no limit to the number of adaptive policy scopes that you can add to a policy, but there are some maximum limits for the query that defines each adaptive scope:

• String length for attribute or property values: 200
• Number of attributes or properties without a group, or within a group: 10
• Number of groups: 10
• Number of characters in an advanced query: 10,000
• Grouping attributes or properties within a group isn't supported. This means that the maximum number of properties or attributes supported within a single adaptive scope is 100.

Configure adaptive scopes

When you choose to use adaptive scopes, you're prompted to select what type of adaptive scope you want. There are three different types of adaptive scopes and each one supports different attributes or properties:

Adaptive scope type	Attributes or properties supported include
Users - applies to: - Exchange mailboxes - OneDrive accounts - Teams chats and Copilot interactions - Teams private channel messages - Viva Engage user messages	First Name Last name Display name Job title Department Office Street address City State or province Postal code Country or region Email addresses Alias Exchange custom attributes: CustomAttribute1 - CustomAttribute15
SharePoint sites - applies to: - SharePoint sites * - OneDrive accounts	Site URL Site name Custom properties (SharePoint only): RefinableString00 - RefinableString99
Microsoft 365 Groups - applies to: - Microsoft 365 Group mailboxes & sites - Teams channel messages (standard and shared) - Viva Engage community messages	Name Display name Description Email addresses Alias Exchange custom attributes: CustomAttribute1 - CustomAttribute15

^* Currently, shared channel SharePoint sites aren't supported for adaptive scopes.

Note

For communication compliance policies:

• SharePoint sites and OneDrive accounts aren't supported.
• Excluded users and Microsoft 365 groups are supported.

The property names for sites are based on SharePoint site managed properties. For information about the custom attributes, see Using Custom SharePoint Site Properties to Apply Microsoft 365 Retention with Adaptive Policy Scopes.

The attribute names for users and groups are based on filterable recipient properties that map to Microsoft Entra attributes. For example:

• Alias maps to the LDAP name mailNickname that displays as Email in the Microsoft Entra admin center.
• Email addresses maps to the LDAP name proxyAddresses that displays as Proxy address in the Microsoft Entra admin center.

The attributes and properties listed in the table can be easily specified when you configure an adaptive scope by using the simple query builder. Additional attributes and properties are supported with the advanced query builder, as described in the following section.

How to configure an adaptive scope

Before you configure your adaptive scope, use the previous section to identify what type of scope to create and what attributes and values you'll use. You might need to work with other administrators to confirm this information.

You'll need to assign the correct role groups to admins to create an adaptive scope. Any role group with the Scope Manager role is allowed to create an adaptive scope. The Scope Manger role is included in the following built-in role groups:

• Compliance Administrator
• Compliance Data Administrator
• Organization Management
• Records Management
• Communication Compliance
• Communication Compliance Admins

Specifically for SharePoint sites, there might be additional SharePoint configuration needed if you plan to use custom site properties.

To create and configure adaptive scopes, you can use either the Microsoft Purview portal or the Microsoft Purview compliance portal.

1. Depending on the portal you're using, navigate to one of the following locations:

   • Sign in to the Microsoft Purview portal > Settings card > Roles and scopes > Adaptive scopes.

     If the Settings solution card isn't displayed, select View all solutions and then select Settings from the Core section.

   • Sign in to the Microsoft Purview compliance portal > Roles & scopes > Adaptive scopes.

2. Select Adaptive scopes, and then + Create scope.

3. Follow the prompts in the configuration where you'll first be asked to assign an administrative unit. If your account has been assigned administrative units, you must select one administrative unit that will restrict the scope membership.

   Note

   Because administrative units don't yet support SharePoint sites, you won't be able to create an adaptive scope for SharePoint sites if you select administrative units.

   If you don't want to restrict the adaptive scope by using administrative units, or your organization hasn't configured administrative units, keep the default of Full directory.

4. Select the type of scope, and then select the attributes or properties you want to use to build the dynamic membership, and type in the attribute or property values.

   For example, to configure an adaptive scope that will be used to identify users in Europe, first select Users as the scope type, and then select the Country or region attribute, and type in Europe:

   

   Once daily, this query will run against Microsoft Entra ID and identify all users who have the value Europe specified for in their account for the Country or region attribute.

   Important

   Because the query doesn't run immediately, there's no validation that you typed in the value correctly.

   Select Add attribute (for users and groups) or Add property (for sites) to use any combination of attributes or properties that are supported for their scope type, together with logical operators to build queries. The operators supported are is equal to, is not equal to, starts with and not starts with, and you can group selected attributes or properties. For example:

   

   Alternatively, you can select Advanced query builder to specify your own queries:

   • For User and Microsoft 365 Group scopes, use OPATH filtering syntax. For example, to create a user scope that defines its membership by department, country/region, and state:

     

     One of the advantages of using the advanced query builder for these scopes is a wider choice of query operators:

     • and
     • or
     • not
     • eq (equals)
     • ne (not equals)
     • lt (less than)
     • gt (greater than)
     • like (string comparison)
     • notlike (string comparison)

   • For SharePoint sites scopes, use Keyword Query Language (KQL). You might already be familiar with using KQL to search SharePoint by using indexed site properties. To help you specify these KQL queries, see Keyword Query Language (KQL) syntax reference.

     For example, because SharePoint site scopes automatically include all SharePoint site types, which include Microsoft 365 group-connected and OneDrive sites, you can use the indexed site property SiteTemplate to include or exclude specific site types. The templates you can specify:

     • SITEPAGEPUBLISHING for modern communication sites
     • GROUP for Microsoft 365 group-connected sites
     • TEAMCHANNEL for Microsoft Teams private channel sites
     • STS for a classic SharePoint team site
     • SPSPERS for OneDrive sites

     So to create an adaptive scope that includes only modern communication sites and excludes Microsoft 365 goup-connected and OneDrive sites, specify the following KQL query:

     SiteTemplate=SITEPAGEPUBLISHING
     

     You can validate these advanced queries independently from the scope configuration.

     Tip

     You must use the advanced query builder if you want to exclude inactive mailboxes. Or conversely, target just inactive mailboxes. For this configuration, use the OPATH property IsInactiveMailbox:

     • To exclude inactive mailboxes, make sure the query includes: (IsInactiveMailbox -eq "False")
     • To target just inactive mailboxes, specify: (IsInactiveMailbox -eq "True")

5. Create as many adaptive scopes as you need. You can select one or more adaptive scopes when you create your policy.

Note

It can take up to five days for the queries to fully populate and changes will not be immediate. Factor in this delay by waiting a few days before you add a newly created scope to a policy.

To confirm the current membership and membership changes for an adaptive scope:

1. Double-click (or select and press Enter) the scope on the Adaptive scopes page

2. From the flyout Details pane, select Scope details.

   Review the information that identifies all the users, sites, or groups currently in the scope, if they were automatically added or removed, and the date and time of that membership change.

Tip

For the data lifecycle management and records management solutions, use the policy lookup option to help you identify solution policies that are currently assigned to specific users, sites, and Microsoft 365 groups.

Validate advanced queries

You can manually validate advanced queries by using PowerShell and SharePoint search:

• Use PowerShell for the scope types Users and Microsoft 365 Groups
• Use SharePoint search for the scope type SharePoint sites

To run a query using PowerShell:

1. Connect to Exchange Online PowerShell using an account with appropriate Exchange Online Administrator permissions.

2. Use either Get-Recipient, Get-Mailbox, or Get-User with the -Filter parameter and your OPATH query for the adaptive scope enclosed in curly brackets ({,}). If your attribute values are strings, enclose these values in double or single quotes.

   You can determine whether to use Get-Mailbox, Get-Recipient, or Get-User for validation by identifying which cmdlet is supported by the OPATH property that you choose for your query.

   Important

   Get-Mailbox does not support the MailUser recipient type, so Get-Recipient or Get-User must be used to validate queries that include on-premises mailboxes in a hybrid environment.

   To validate a User scope, use the appropriate command:

   • Get-Mailbox with -RecipientTypeDetails UserMailbox,SharedMailbox,RoomMailbox,EquipmentMailbox
   • Get-Recipient with -RecipientTypeDetails UserMailbox,MailUser,SharedMailbox,RoomMailbox,EquipmentMailbox

   To validate a Microsoft 365 Group scope, use:

   • Get-Mailbox with -GroupMailbox or Get-Recipient with -RecipientTypeDetails GroupMailbox

   For example, to validate a User scope related to the Department attribute set to the value Marketing, you could use:

   Get-Recipient -RecipientTypeDetails UserMailbox,MailUser -Filter {Department -eq "Marketing"} -ResultSize Unlimited
   

   To validate a User scope related to the EmailAddresses attribute generally requires the value to include the smtp: prefix. For example to exclude a user where EmailAddresses includes admin@contoso.com:

   Get-Mailbox -RecipientTypeDetails UserMailbox -Filter {EmailAddresses -notlike "smtp:admin@contoso.com"} -ResultSize Unlimited
   

   To validate a Microsoft 365 Group scope related to the group's CustomAttribute15 attribute set to Marketing as the value, you could use:

   Get-Mailbox -RecipientTypeDetails GroupMailbox -Filter {CustomAttribute15 -eq "Marketing"} -ResultSize Unlimited
   

   Tip

   When you use these commands to validate a user scope, if the number of recipients returned is higher than expected, it might be because it includes users who don't have a valid license for adaptive scopes. These users won't have the policy settings applied to them.

   For example, in a hybrid environment, you might have unlicensed synchronized user accounts without an Exchange mailbox on-premises or in Exchange Online. You can identify these users by running the following command: Get-User -RecipientTypeDetails User

3. Verify that the output matches the expected users or groups for your adaptive scope. If it doesn't, check your query and the values with the relevant administrator for Microsoft Entra ID or Exchange.

   Tip

   The output from these commands may not match the member list for the same filter within the scope details on the Adaptive Scopes page. The member list in scope details shows arbitration mailboxes in scope whereas the command output does not. Moreover, adaptive scope query changes can take up to 5 days to become effective and reflected in the scope details view of the Adaptive Scopes page.

To run a query using SharePoint search:

1. Using an account that has the SharePoint admin role, go to https://<your_tenant>.sharepoint.com/search.
2. Use the search bar to specify your KQL query.
3. Verify that the search results match the expected site URLs for your adaptive scope. If they don't, check your query and the URLs with the relevant administrator for SharePoint.