Configure permissions filtering for Content Search

You can use search permissions filtering to let an eDiscovery manager search only a subset of mailboxes and sites in your Office 365 organization. You can also use permissions filtering to let that same eDiscovery manager search only for mailbox or site content that meets a specific search criteria. For example, you might let an eDiscovery manager search only the mailboxes of users in a specific location or department. You do this by creating a filter that uses a supported recipient filter to limit which mailboxes can be searched. You can also create a filter that specifies what mailbox content can be searched. This is done by creating a filter that uses a searchable message property. Similarly, you might let an eDiscovery manager only search specific SharePoint sites in your organization. You do this by creating a filter that limits which site can be searched. You can also create a filter that specifies what site content can be searched. This is done by creating a filter that uses a searchable site property.

Search permissions filtering is supported by the Content Search feature in the Office 365 Security & Compliance Center. These four cmdlets let you configure and manage security filtering:

New-ComplianceSecurityFilter

Get-ComplianceSecurityFilter

Set-ComplianceSecurityFilter

Remove-ComplianceSecurityFilter

For more information about these cmdlets, see the "Content search cmdlets" section in Office 365 Security & Compliance Center cmdlets.

Before you begin

  • To run the compliance security filter cmdlets, you have to be a member of the Organization Management role group in the Security & Compliance Center. For more information, see Permissions in the Office 365 Security & Compliance Center.

  • You have to connect Windows PowerShell to both the Security & Compliance Center and to your Exchange Online organization to use the compliance security filter cmdlets. This is necessary because these cmdlets require access to mailbox properties, which is why you have to connect to Exchange Online. See the steps in the next section.

  • See the More information section for additional information about search permissions filters.

  • Search permissions filtering is applicable to inactive mailboxes, which means you can use mailbox and mailbox content filtering to limit who can search an inactive mailbox. See the More information section for additional information about permissions filtering and inactive mailboxes.

Connect to the Security & Compliance Center and Exchange Online in a single remote PowerShell session

  1. Save the following text to a Windows PowerShell script file by using a filename suffix of .ps1. For example, you could save it to a file named ConnectEXO-CC.ps1.

    $UserCredential = Get-Credential
    $Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://ps.outlook.com/powershell-liveid -Credential $UserCredential -Authentication Basic -AllowRedirection
    Import-PSSession $Session -DisableNameChecking
    $Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://ps.compliance.protection.outlook.com/powershell-liveid -Credential $UserCredential -Authentication Basic -AllowRedirection
    Import-PSSession $Session -AllowClobber -DisableNameChecking
    $Host.UI.RawUI.WindowTitle = $UserCredential.UserName + " (Exchange Online + Compliance Center)"
  2. On your local computer, open Windows PowerShell, go to the folder where the script that you created in the previous step is located, and then run the script; for example:

    .\ConnectEXO-CC.ps1

How do you know if this worked? After you run the script, cmdlets from the Security & Compliance Center and Exchange Online are imported into your local Windows PowerShell session. If you don’t receive any errors, you connected successfully. A quick test is to run a Security & Compliance Center cmdlet—for example, Install-UnifiedCompliancePrerequisite—and an Exchange Online cmdlet, such as Get-Mailbox.

If you receive errors, check the following requirements:

  • A common problem is an incorrect password. Run the two steps again and pay close attention to the user name and password you enter in Step 1.

  • Verify that your account has permission to access the Security & Compliance Center. For details, see Give users access to the Security & Compliance Center.

  • To help prevent denial-of-service (DoS) attacks, you're limited to three open remote PowerShell connections to the Security & Compliance Center.

  • Windows PowerShell needs to be configured to run scripts. You need to configure this setting only once on your computer, not every time you connect. To enable Windows PowerShell to run signed scripts, run the following command in an elevated Windows PowerShell window (a Windows PowerShell window you opened by selecting Run as administrator).

    Set-ExecutionPolicy RemoteSigned
  • TCP port 80 traffic needs to be open between your local computer and Office 365. It's probably open, but it’s something to consider if your organization has a restrictive Internet access policy.

Return to top

New-ComplianceSecurityFilter

The New-ComplianceSecurityFilter is used to create a new search permissions filter. The following table describes the parameters for this cmdlet. All parameters are required to create a compliance security filter.

Parameter

Description

Action

The Action parameter specifies that type of search action that the filter is applied to. The possible Content Search actions are:

  • Export   The filter is applied when exporting search results.

  • Preview   The filter is applied when previewing search results.

  • Purge   The filter is applied when purging search results.

  • Search   The filter is applied when running a search.

  • All   The filter is applied to all search actions.

FilterName

The FilterName parameter specifies the name of the permissions filter. This name is used to identity a filter when using the Get-ComplianceSecurityFilter, Set-ComplianceSecurityFilter, and Remove-ComplianceSecurityFilter cmdlets.

Filters

The Filters parameter specifies the search criteria for the compliance security filter. You can create three different kind of filters:

  • Mailbox filtering      This type of filter specifies the mailboxes the assigned users (specified by the Users parameter) can search. The syntax for this type of filter is Mailbox_MailboxPropertyName, where MailboxPropertyName specifies a mailbox property used to scope the mailboxes that can be searched. For example, the mailbox filter "Mailbox_CustomAttribute10 -eq 'OttawaUsers'" would allow the user assigned this filter to only search mailboxes that have the value "OttawaUsers" in the CustomAttribute10 property.

    Any supported filterable recipient property can be used for the MailboxPropertyName property. For a list of supported properties, see Filterable properties for the -RecipientFilter parameter.

  • Mailbox content filtering      This type of filter is applied on the content that can be searched. It specifies the mailbox content the assigned users can search for. The syntax for this type of filter is MailboxContent_SearchablePropertyName:value, where SearchablePropertyName specifies a Keyword Query Language (KQL) property that can be specified in a Content Search. For example, the mailbox content filter MailboxContent_recipients:contoso.com would allow the user assigned this filter to only search for messages sent to recipients in the contoso.com domain.

    For a list of searchable message properties, see Keyword queries for Content Search.

  • Site and site content filtering      There are two SharePoint and OneDrive for Business site-related filters that you can use to specify what site or site content the assigned users can search:

    • Site_SearchableSiteProperty

    • SiteContent_SearchableSiteProperty

    These two filters are interchangeable; for example "Site_Site -eq 'https://contoso.sharepoint.com/sites/doctors'" and "SiteContent_Site -eq 'https://contoso.sharepoint.com/sites/doctors'" are the same filter. But to help you identify what a filter does, you can use Site_ to specify site-related properties (such as a site URL) and SiteContent_ to specify content-related properties (such as document types. For example, the filter "Site_Site -eq 'https://contoso.sharepoint.com/sites/doctors'" would allow the user assigned this filter to only search for content in the https://contoso.sharepoint.com/sites/doctors'" site collection. The filter "SiteContent_FileExtension -eq 'docx'" would allow the user assigned this filter to only search for Word documents (Word 2007 and later).

    For a list of searchable site properties, see Overview of crawled and managed properties in SharePoint. Properties marked with a Yes in the Queryable column can be used to create a site or site content filter.

Important: A single search filter can only have one type of filter; it can't contain a mailbox filter and a site filter; similarly, it can't contain a mailbox filter and a mailbox content filter. However, a filter can contain a more complex query of the same type. For example, "Mailbox_CustomAttribute10 -eq 'FTE' -and Mailbox_MemberOfGroup -eq '$($DG.DistinguishedName)'"

Users

The Users parameter specifies the users who get this filter applied to their Content Searches. Identify users by their alias or primary SMTP address. You can specify multiple values separated by commas, or you can assign the filter to all users by using the value All.

You can also use the Users parameter to specify a Security & Compliance Center role group. This lets you create a custom role group and then assign that role group a search permissions filter. For example, let's say you have a custom role group for eDiscovery managers for the U.S. subsidiary of a multi-national corporation. You can use the Users parameter to specify this role group (by using the Name property of the role group) and then use the Filter parameter to allow only mailboxes in the U.S. to be searched.

You can't specify distribution groups with this parameter.

Return to top

Examples

Here are examples of using the New-ComplianceSecurityFilter cmdlet to create a search permissions filter.

This example allows the user annb@contoso.com to perform all Content Search actions only for mailboxes in Canada. This filter contains the three-digit numeric country code for Canada from ISO 3166-1.

New-ComplianceSecurityFilter -FilterName CountryFilter  -Users annb@contoso.com -Filters "Mailbox_CountryCode  -eq '124'" -Action All

This example allows the users donh and suzanf to search only the mailboxes that have the value 'Marketing' for the CustomAttribute1 mailbox property.

New-ComplianceSecurityFilter -FilterName MarketingFilter  -Users donh,suzanf -Filters "Mailbox_CustomAttribute1  -eq 'Marketing'" -Action Search

This example allows members of the "US Discovery Managers" role group to perform all Content Search actions only on mailboxes in the United States. This filter contains the three-digit numeric country code for the United States from ISO 3166-1.

New-ComplianceSecurityFilter -FilterName USDiscoveryManagers  -Users "US Discovery Managers" -Filters "Mailbox_CountryCode  -eq '840'" -Action All

This example assigns allows members of the eDiscovery Manager role group to only search the mailboxes of members of the Ottawa Users distribution group.

$DG = Get-DistributionGroup "Ottawa Users"
New-ComplianceSecurityFilter -FilterName DGFilter  -Users eDiscoveryManager -Filters "Mailbox_MemberOfGroup -eq '$($DG.DistinguishedName)'" -Action Search

This example prevents any user from deleting content from the mailboxes of members of the Executive Team distribution group.

$DG = Get-DistributionGroup "Executive Team"
New-ComplianceSecurityFilter -FilterName NoExecutivesPreview  -Users all -Filters "Mailbox_MemberOfGroup -ne '$($DG.DistinguishedName)'" -Action Purge

This example allows members of the OneDrive eDiscovery Managers custom role group to only search for content in OneDrive for Business locations in the organization.

New-ComplianceSecurityFilter -FilterName OneDriveOnly  -Users "OneDrive eDiscovery Managers" -Filters "Site_Site -eq 'https://contoso-my.sharepoint.com/'" -Action Search

This example restricts the user to performing all Content Search actions only on email messages sent during the calendar year 2015.

New-ComplianceSecurityFilter -FilterName EmailDateRestrictionFilter -Users donh@contoso.com -Filters "MailboxContent_Received -ge '01-01-2015' -and MailboxContent_Received -le '12-31-2015'" -Action All

Similar to the previous example, this example restricts the user to performing all Content Search actions on documents that were last changed sometime in the calendar year 2015.

New-ComplianceSecurityFilter -FilterName DocumentDateRestrictionFilter -Users donh@contoso.com -Filters "SiteContent_LastModifiedTime -ge '01-01-2015' -and SiteContent_LastModifiedTime -le '12-31-2015'" -Action All

Return to top

Get-ComplianceSecurityFilter

The Get-ComplianceSecurityFilter is used to return a list of search permissions filters. Use the FilterName parameter to return information for a specific search filter.

Set-ComplianceSecurityFilter

The Set-ComplianceSecurityFilter is used to modify an existing search permissions filter. The only required parameter is FilterName.

Parameter

Description

Action

The Action parameter specifies that type of search action that the filter is applied to. The possible Content Search actions are:

  • Export   The filter is applied when exporting search results.

  • Preview   The filter is applied when previewing search results.

  • Purge   The filter is applied when purging search results.

  • Search   The filter is applied when running a search.

  • All   The filter is applied to all search actions.

FilterName

The FilterName parameter specifies the name of the permissions filter.

Filters

The Filters parameter specifies the search criteria for the compliance security filter. You can create two different kind of filters:

  • Mailbox filtering      This type of filter specifies the mailboxes the assigned users (specified by the Users parameter) can search. The syntax for this type of filter is Mailbox_MailboxPropertyName, where MailboxPropertyName specifies a mailbox property used to scope the mailboxes that can be searched. For example, the mailbox filter "Mailbox_CustomAttribute10 -eq 'OttawaUsers'" would allow the user assigned this filter to only search mailboxes that have the value "OttawaUsers" in the CustomAttribute10 property.

    Any supported filterable recipient property can be used for the MailboxPropertyName property. For a list of supported properties, see Filterable properties for the -RecipientFilter parameter.

  • Mailbox content filtering      This type of filter is applied on the content that can be searched. It specifies the mailbox content the assigned users can search for. The syntax for this type of filter is MailboxContent_SearchablePropertyName:value, where SearchablePropertyName specifies a Keyword Query Language (KQL) property that can be specified in a Content Search. For example, the mailbox content filter MailboxContent_recipients:contoso.com would allow the user assigned this filter to only search for messages sent to recipients in the contoso.com domain.

    For a list of searchable message properties, see Keyword queries for Content Search.

  • Site and site content filtering      There are two SharePoint and OneDrive for Business site-related filters that you can use to specify what site or site content the assigned users can search:

    • Site_SearchableSiteProperty

    • SiteContent_SearchableSiteProperty

    These two filters are interchangeable; for example "Site_Site -eq 'https://contoso.spoppe.com/sites/doctors'" and "SiteContent_Site -eq 'https://contoso.spoppe.com/sites/doctors'" are the same filter. But to help you identify what a filter does, you can use Site_ to specify site-related properties (such as a site URL) and SiteContent_ to specify content-related properties (such as document types. For example, the filter "Site_Site -eq 'https://contoso.spoppe.com/sites/doctors'" would allow the user assigned this filter to only search for content in the https://contoso.spoppe.com/sites/doctors'" site collection. The filter "SiteContent_FileExtension -eq 'docx'" would allow the user assigned this filter to only search for Word documents (Word 2007 and later).

    For a list of searchable site properties, see Overview of crawled and managed properties in SharePoint. Properties marked with a Yes in the Queryable column can be used to create a site or site content filter.

Important: A single search filter can only have one type of filter; it can't contain a mailbox filter and a site filter; similarly, it can't contain a mailbox filter and a mailbox content filter. However, a filter can contain a more complex query of the same type. For example, "Mailbox_CustomAttribute10 -eq 'FTE' -and Mailbox_MemberOfGroup -eq '$($DG.DistinguishedName)'"

Users

The Users parameter specifies the users who get this filter applied to their Content Searches. Because this is a multi-value property, specifying a user or group of users with this parameter will overwrite the existing list of users. See the following examples for the syntax for adding and removing selected users.

You can also use the Users parameter to specify a Security & Compliance Center role group. This lets you create a custom role group and then assign that role group a search permissions filter. For example, let's say you have a custom role group for eDiscovery managers for the U.S. subsidiary of a multi-national corporation. You can use the Users parameter to specify this role group (by using the Name property of the role group) and then use the Filter parameter to allow only mailboxes in the U.S. to be searched.

You can't specify distribution groups with this parameter.

Return to top

Examples

These examples show how to use the Get-ComplianceSecurityFilter and Set-ComplianceSecurityFilter cmdlets to add or remove a user to the existing list of users that the filter is assigned to. When you add or remove users from a filter, specify the user by using their SMTP address.

This example adds a user to the filter.

$filterusers = Get-ComplianceSecurityFilter -FilterName OttawaUsersFilter
$filterusers.users.add("pilarp@contoso.com")
Set-ComplianceSecurityFilter -FilterName OttawaUsersFilter -Users $filterusers.users

This example removes a user from the filter.

$filterusers = Get-ComplianceSecurityFilter -FilterName OttawaUsersFilter
$filterusers.users.remove("annb@contoso.com")
Set-ComplianceSecurityFilter -FilterName OttawaUsersFilter -Users $filterusers.users

Return to top

Remove-ComplianceSecurityFilter

The Remove-ComplianceSecurityFilter is used to delete a search filter. Use the FilterName parameter to specify the filter you want to delete.

More information

  • How does search permissions filtering work?      The permissions filter is added to the search query when a Content Search is run. The permissions filter is essentially joined to the search query by the AND Boolean operator. For example, say you have a permissions filter that allows Bob to perform all search actions on the mailboxes of members of the Workers distribution group. Then Bob runs a Content Search on all mailboxes in the organization with the search query sender:jerry@adatum.com. Because the permissions filter and the search query are logically combined by an AND operator, the search will return any message sent by jerry@adatum.com to any member of the Workers distribution group.

  • What happens if you have multiple search permissions filters?      In a Content Search query, multiple permissions filters are combined by OR Boolean operators. So results will be returned if any of the filters are true. In a Content Search, all filters (combined by OR operators) are then combined with the search query by the AND operator. Let's take the previous example, where a search filter allows Bob to only search the mailboxes of the members of the Workers distribution group. Then we create another filter that prevents Bob from searching Phil's mailbox ("Mailbox_Alias -ne 'Phil'"). And let's also assume that Phil is a member of the Workers group. When Bob runs a Content Search (from the previous example) on all mailboxes in the organization, search results will be returned for Phil's mailbox even though you applied filter to prevent Bob from searching Phil’s mailbox. This is because the first filter, which allows Bob to search the Workers group, is true. And because Phil is a member of the Workers group, Bob can search Phil's mailbox.

  • Does search permissions filtering work for inactive mailboxes?    You can use mailbox and mailbox content filters to limit who can search inactive mailboxes in your organization. Like a regular mailbox, an inactive mailbox has to be configured with the recipient property that's used to create a permissions filter. If necessary, you can use the Get-Mailbox -InactiveMailboxOnly command to display the properties of inactive mailboxes. For more information, see Manage inactive mailboxes in Exchange Online.

Return to top

Share Facebook Facebook Twitter Twitter Email Email

Was this information helpful?

Great! Any other feedback?

How can we improve it?

Thank you for your feedback!

×