The essential admin's guide to Office 365 PowerShell
A comprehensive collection of articles, videos and more, hand-picked by our editors
Businesses of almost any size must deal with regulations that dictate how they handle data flowing in and out of...
By submitting your personal information, you agree that TechTarget and its partners may contact you regarding relevant content, products and special offers.
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
$Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://outlook.office365.com/powershell-liveid/ -Credential $UserCredential -Authentication Basic -AllowRedirection
Connect-MSOLService -Credential $UserCredential
Run that script and enter your credentials at the prompt to get connected to all the services.
To start managing discovery we can look at the cmdlets in our session for managing Office 365 compliance:
Get-Command -noun "compliance*"
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.
Use PowerShell to add mailboxes to Office 365
Create DLP policies in Exchange 2013
Take steps to protect your Office 365 data