Essential Guide

The essential admin's guide to Office 365 PowerShell

A comprehensive collection of articles, videos and more, hand-picked by our editors
Problem solve Get help with specific problems with your technologies, process and projects.

Set Office 365 data loss prevention policies with PowerShell

Exchange administrators can use PowerShell to manage Office 365 compliance, e-discovery and data loss prevention.

Businesses of almost any size must deal with regulations that dictate how they handle data flowing in and out of...

the email servers. You can never tell what someone is going to send in an email that goes against corporate policy. If you're using Office 365, you can enforce corporate policy by finding users that are violating it and even set rules to ensure Office 365 data loss prevention. In this article we will use PowerShell from our local computer to set up these types of searches.

Connect to Exchange Online

To manage Office 365 compliance and discovery through PowerShell, we need to do a little preparation. First, download and install the Azure PowerShell Module. After that is installed, connect to Exchange Online and the Office 365 Security and Compliance Center at the same time to get the full suite of necessary cmdlets and functions. Use the code below to start a session with both, and to connect to a generic Office 365 PowerShell service to get access to cmdlets for managing users and permissions:

$UserCredential = Get-Credential

$Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://ps.compliance.protection.outlook.com/powershell-liveid/ -Credential $UserCredential -Authentication Basic -AllowRedirection

Import-PSSession $session

$Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://outlook.office365.com/powershell-liveid/ -Credential $UserCredential -Authentication Basic -AllowRedirection

Import-PSSession $session

Connect-MSOLService -Credential $UserCredential

Run that script and enter your credentials at the prompt to get connected to all the services.

Compliance search

To start managing discovery we can look at the cmdlets in our session for managing Office 365 compliance:

Get-Command -noun "compliance*"

With DLP we prevent users from violating data loss policies in the first place, but we can also be flexible in how we do that.

By issuing the Get-Command cmdlet, we can search through all of the cmdlets and functions we have available in our current session. When you invoke that command you should get a list of compliance cmdlets. For an actual reference to the compliance center cmdlets, you can look here. Pay special attention to each cmdlet's Detailed Description section as it will give you details about the permissions needed to run the cmdlet.

If nothing shows up, you may need to check your permissions in the Office 365 Compliance Center. Permissions can be complex, so to keep things simple we'll just make sure you are a compliance administrator. If you don't have permission to do this yourself, then you may need to ask other admins to help you out.

$role = Get-MsolRole -RoleName "Compliance Administrator"

$user = Get-MSOlUser -UserPrincipalName "<user>@<tenant>.onmicrosoft.com"

Add-MsolRoleMember -RoleObjectId $role.ObjectId -RoleMemberType User -RoleMemberObjectId $user.ObjectId

For this example we are going to do a simple compliance search of all of our mailboxes. This will simulate a standing search we can use to identify mailboxes that might cause issues with compliance, and that we can regularly rerun and update without having to reissue the full search command. Invoke Get-ComplianceSearch to find the stored search and pass it to the Start-ComplianceSearch cmdlet to update the results.

Run the code below to create the search:

$searchName = "DangerousToys"

New-ComplianceSearch -Name $searchName -ExchangeLocation "All" -ContentMatchQuery 'Subject:"Dangerous Toys"'

I previously set up my demo environment to deliberately trigger this compliance search based on the subject you see in the script above by sending suspicious emails with the term Dangerous Toys in the subject. Dangerous toys should violate some kind of corporate email policy, right? Note the -contentMatchQuery parameter uses KQL syntax so you can get pretty fancy with how you construct the query for that parameter. Now that the search has been set up, we can execute it and let it find any offending emails.

Start-ComplianceSearch -Identity $searchName

Use the -AsJob parameter if you expect the search to take a while. Using that parameter will spin off the long running task to a background job. It's still going to take a while, but your session won't be locked up while it runs. Once the searches are created you can also start them repeatedly to update their results using PowerShell, rather than using the slower web interface repeatedly. If you manage a large number of mailboxes in your Exchange subscription and the query takes a long time, you can keep track of the status of your search by executing Get-ComplianceSearch and looking at the Status column.

Of course, just doing the search isn't enough. We need to be able to see the results. The way we do that is a little bit roundabout, but we have to assign a new Compliance Search Action to the search we just created. We do that with the following code in two statements which will also export the results to a file.

New-ComplianceSearchAction -SearchName $searchName –Preview

Get-ComplianceSearchAction -Identity "$searchName_Preview" | Select-Object Results | Export-Csv c:\results.csv –NoTypeInformation

If you get an error that the –Preview parameter is not available to you, it's because you have not been assigned the Preview role in your organization. Work with your administrators to get that role.

Enforcement and logging through DLP

Now that we've seen how to run content queries for e-discovery and compliance, let's see if we can prevent leaks in the first place using data loss prevention. With DLP we prevent users from violating data loss policies in the first place, but we can also be flexible in how we do that.

Office 365 data loss prevention is a complicated subject if you want to know it thoroughly. Take a look here to learn more about DLP. We aren't going to cover all of the options available, but if you want to get up and running, Microsoft has made it easy to start with templates. The code below will start enforcing filters when it looks like people might be sending out data that violates U.S. Health Insurance Portability and Accountability Act (HIPAA) regulations.

New-DLPPolicy -Name "HIPAA Policy" -Template "U.S. Health Insurance Act (HIPAA)" -Mode Enforce

That policy will be enforced immediately, but you can use modes like Audit to gives the templates a try to see what they catch, without intruding on your users' workflows until you are sure they're working the way you want them to. If you aren't impacted by HIPAA, or if you aren't in the United States, there are other templates to choose from out of the box.

If the mode is Enforce, you can test this rule by attempting to send an email with 10 or more fake social security numbers in it, or use key words and phrases 10 or more times such as Social Security Number or SSN. This is because templates by default have low count and high count rules. If the pattern the rule is looking for only happens between one and nine times, then this template by default will only warn the user, but send the email anyway. Ten or more hits will result in the email getting blocked and a notice getting sent to the user that his message was blocked and how to override it. You can turn off the ability to override as well turn off or tweak those low and high count thresholds.

Microsoft recommends you use either Audit or AuditAndNotify for a while first. To review what's getting caught, you can either check the Exchange admin portal online, or you can run Get-MailDetailDLPPolicyReport for a listing of hits against the new policy. To download the Azure PowerShell Module, visit this MSDN page.

Next Steps

Use PowerShell to add mailboxes to Office 365

Create DLP policies in Exchange 2013

Take steps to protect your Office 365 data

This was last published in July 2016

PRO+

Content

Find more PRO+ content and other member only offers, here.

Essential Guide

The essential admin's guide to Office 365 PowerShell

Join the conversation

1 comment

Send me notifications when other members comment.

By submitting you agree to receive email from TechTarget and its partners. If you reside outside of the United States, you consent to having your personal data transferred to and processed in the United States. Privacy

Please create a username to comment.

What kinds of Office 365 data loss prevention policies will you set with PowerShell?
Cancel

-ADS BY GOOGLE

SearchWindowsServer

SearchEnterpriseDesktop

SearchCloudComputing

SearchSQLServer

Close