7 Compliance
_______________________________
In This Chapter
Introduction
Compliance Cases
Compliance Searches
Retention Compliance
_______________________________
Introduction
Compliance is a hot topic for those who have their data stored in Office 365 with concerns with GDPR and business compliance regulations. No longer are we worried about just mailbox data, we now worry about what people store in SharePoint, OneDrive, Teams and more. Because of this change in data concern, Microsoft is now working to add all of these data sources to its list of tools. In addition to this, Microsoft has also pulled some tools from Exchange Online into the Security and Compliance Center in terms of holds, retention and labeling.
Permissions and access into this data is also important to Microsoft and their tenants. Utilizing Role-Based Access Control (RBAC) to help isolate and drive secure access to data, the Role Groups that are available have increased to accommodate the increased focus on centralized data gathering and security in general.
In the realm of Compliance Microsoft uses a layered approach with Compliance Cases, Compliance Searches and Compliance Holds. This chapter will show that this allows for a more complex and also more flexible solution for creating discovery and compliance cases.
In this chapter we will explore all of these layers and decipher how these can be managed with PowerShell. We will also review the connection between PowerShell and the Security and Compliance Center website.
** Reminder **
When working with Compliance Cases in PowerShell, remember from Chapter 5:
- eDiscovery Manager only has access to cases that they were assigned rights.
- eDiscovery Administrator has access to all cases.
Compliance Cases
If we review the PowerShell cmdlets that are available for Compliance Cases in the Security and Compliance Center we will see this:
Add-ComplianceCaseMember
Get-ComplianceCase
Get-ComplianceCaseMember
Get-ComplianceCaseStatistics
New-ComplianceCase
Remove-ComplianceCase
Remove-ComplianceCaseMember
Set-ComplianceCase
Update-ComplianceCaseMember
By default an Office 365 tenant will not have any cases defined. However, our test tenant does and we can use this tenant to illustrate PowerShell functionality. Let’s start off with the Get-ComplianceCase to see what we can reveal:
Get-ComplianceCase
What about using ‘| Fl’, does it reveal useful information?
Get-ComplianceCase “Hold for some mailboxes” | Fl
Well. Not really. How are we going to extract the extra information we need from these cases? Since PowerShell and the Security and Compliance Center are tied together, we need to review what is configured in the SCC to find these cases. However, the SCC interface does not specifically display a section called Compliance Cases. Where do we find these cases? With a bit of exploration of the interface we see that the Compliance Cases are actually listed under the Search & Investigation tab and then the eDiscovery option under that section:
For this example, the case we are looking at is in the red rectangle above. Opening up the case we’ll see that the case contains two holds and one search.
Compliance Case: A collection of Holds and/or Searches that are grouped together for a common purpose.
What if we want to create a new case in the SCC? The most obvious use is for litigation.
New-ComplianceCase
What options do we have for creating a case?
Reviewing the Parameters that are also available, we can provide a Description as well if needed for compliance or to keep track of the purpose for the case.
New-ComplianceCase -Name “Merger Dispute” -Description “Legal case with Shareholders (Merger)”
This would simply create a shell for us to use for this particular case. We also have Remove-ComplianceCase and Set-ComplianceCase if we need to work with the cases after they are created. The Remove cmdlet would completely remove the case from the SCC as well as any holds or searches. A better option might be to use ‘Set-ComplianceCase’ to close the case leaving it for historical purposes and the possibility of reopening it later on. This leaves the case present for later examination.
Set-ComplianceCase ‘Merger Dispute’ -Close
Set-ComplianceCase ‘Merger Dispute’ -Reopen
** Note ** neither of these commands requires you to confirm closing or reopening the case!
Once we have a case, we can manage users who will handle this case. The PowerShell cmdlets are:
Add-ComplianceCaseMember
Get-ComplianceCaseMember
Remove-ComplianceCaseMember
Update-ComplianceCaseMember
The first member of the case is the creator of the case and can be found with:
Get-ComplianceCaseMember -Case ‘Merger Dispute’
Now, if we have a legal team to handle the case, we can assign these users to the case:
Add-ComplianceCaseMember -Case ‘Merger Dispute’ -Member [email protected]
We can the verify this user has been added:
To further manage case members, we can use the ‘Update-ComplianceCaseMember’ cmdlet to completely replace all members with a new list or we can use ‘Remove-ComplianceCaseMember’ to remove a particular member from the case.
Compliance Searches
What is a Compliance Search?
A Compliance Search is also known as an eDiscovery Search in the SCC. This type of search is used to find data that could be used in a legal case, for general content discover and even cleanup work (Phishing emails). Compliance Searches can be limited to certain locations (Exchange or SharePoint) and even down to an individual user as well as to all Public Folders in Exchange Online. Compliance Searches are controlled by RBAC so make sure that whoever is creating the Compliance Searches has the appropriate rights to do so, as well as the people that may need access to the content at the end of the search.
PowerShell
For PowerShell, we can start off with two nouns in our search for available cmdlets - ‘Compliance’ and ‘Search’:
Get-Command *ComplianceSearch*
This provides us with a set of commands we can use to work with Compliance Searches:
Get-ComplianceSearch
Get-ComplianceSearchAction
New-ComplianceSearch
New-ComplianceSearchAction
Remove-ComplianceSearch
Remove-ComplianceSearchAction
Set-ComplianceSearch
Set-ComplianceSearchAction
Start-ComplianceSearch
Stop-ComplianceSearch
By default we should have no Compliance Searches or Compliance Search Actions.
Requirements
In order to perform a Compliance Search we need to meet the following requirements:
Security - Be a member of the Discovery Search Group or assigned the Mailbox Search Role as the Organization Management group does not have this permission by default.
Start the Search - Once a Compliance Search is created, it has to be started as well.
Apply an Action - determine what is to be done with the search results.
New-ComplianceSearch
Well, let’s go ahead and start creating Compliance. Since we are new to the cmdlet, we can review Get-Help to see if we have any relevant examples to work with:
Get-Help New-ComplianceSearch -Examples
If we look at the available parameters for this cmdlet we can see we have a lot of options to choose from:
AllowNotFoundExchangeLocationsEnabled
Case
ContentMatchQuery
ExchangeLocation
ExchangeLocationExclusion
Force
HoldNames
IncludeOrgContent
IncludeUserAppContent
PublicFolderLocation
RefinerNames
SharePointLocation
SharePointLocationExclusion
With the available parameters, we can create searches in Exchange, SharePoint and more. When reviewing the full help for the cmdlet, you will note that there are quite a few parameters that are relegated to Internal Microsoft use:
LogLevel
OneDriveLocation
OneDriveLocationExclusion
PublicFolderLocationExclusion
RefinerNames
SearchNames
StatusMailRecipients
WhatIf
Now that we have that out of the way, let’s work through some example Compliance Searches.
Example One - Exchange-Only Compliance Search
Your Compliance Administrator just received notice that a few people in Research and Development (RnD) are involved in a patent dispute and specifically she needs to search emails of a group of users. She hands you a list of employees in RnD that are to be searched. Keywords for the search are ‘Patent’ , ‘US 8,965,465 B2’ and ‘SmartPhone’. All of the searches need to be associated with a case called ‘SmartPhone Patent Dispute’.
First, we need to read the CSV file in and store it in a variable called $CSV. The file is stored on a server called FS01 and the Compliance Administrator provides the entire path to be used:
$CSV = Import-CSV ‘\fs01ComplianceSmartphonePatentDisputeRnDUserList.csv’
The case name is also stored in a new variable called $Case:
$Case = ‘SmartPhone Patent Dispute’
Then, using the criteria provided from the Compliance Administrator, we can store that in a variable to be used later as well:
$Criteria = “’Patent’ AND ‘US 8,965,465 B2’ AND ‘SmartPhone’”
We can then use a Foreach loop to process each name in the CSV, create a search for one user and associate it with an eDiscovery case:
Foreach ($Line in $CSV) {
$User = $Line.User
$Name = “$Case - $User”
New-ComplianceSearch -Name $Name -ExchangeLocation $User -ContentMatchQuery $Criteria -Case $Case
}
Before we run this code, we need to make sure we create a Compliance Case:
New-ComplianceCase -Name $Case
The output from our script churns out this:
Once completed we can check our results with a couple of cmdlets:
Get-ComplianceCase ‘SmartPhone Patent Dispute’ | Fl
Get-ComplianceSearch -Case $Case
Notice that all of the searches show a Status of ‘NotStarted’. We can use Start-ComplianceSearch to start them.
Get-ComplianceSearch -Case $Case | Start-ComplianceSearch
We can see our searches are all complete now as well. The next step for a Compliance Search is to assign some sort of action for the search to take. This will be assigned via the New-ComplianceSearchAction cmdlet:
New-ComplianceSearchAction
What about this cmdlet New-CompilanceSearchAction? Compliance Search Actions determine what action the search performs (Preview, Export, etc.):
Get-Help New-ComplianceSearchAction -Examples
This cmdlet would be used after a search were created.
Example Two - Phishing Email removal
In this example your organization has received a series of Phishing emails that have been delivered to everyone’s mailbox. Each mailbox has 10 copies of the same messages. We need to be able to clean up all of these messages, without any user interaction. What can we do?
First, we need to construct a Compliance Search. This search will not be connected to a Compliance Case as we don’t need this feature.
$Name = ‘Phishing Email Search’
$Criteria = “subject:’Wire Transfer Request’”
New-ComplianceSearch -Name $Name -ExchangeLocation All -ContentMatchQuery $Criteria
Once this is created, we can then start the search:
Start-ComplianceSearch -Identity $Name
Once the search is started, we can now create an action. Since these are Phishing emails, we need to remove them and not allow the end user any access to the emails once we complete this task. The New-ComplianceSearchAction has a couple of options we can utilize - Purge and PurgeType. The Get-Help description for the ‘PurgeType’ parameter is a bit deceptive as only one option is available and the other option listed is not correct as it is called ‘Unknown’. This value should be ‘HardDelete’ according to online help for the cmdlet.
We need to run the Compliance Search Action with the same name as the Compliance Search. We will also use both purge actions:
New-ComplianceSearchAction -SearchName $Name -Purge -PurgeType SoftDelete
Make sure this is what you want to do before hitting yes to this question:
Once this starts, any matching items will be SoftDeleted from the mailbox. Now, what if we needed to modify the search?
Set-ComplianceSearch
Once we have Compliance Searches created, we can manipulate some of their details. In order to do so, we need to utilize the ‘Set-ComplianceSearch’ cmdlet. Let’s review what we can do with this cmdlet:
Get-Help Set-ComplianceSearch -Examples
One possible use would be changing the language of the search when it was realized that the mailboxes within scope were not native English speakers.
Set-ComplianceSearch -Identity $Name -Language fr-ch
The above would then change the search language to French (Switzerland) from US (English).
Set-ComplianceSearchAction
In addition to changing the Compliance Search, we can also manipulate the Compliance Search Action. We can do that with the ‘Set-ComplianceSearchAction’ cmdlet. Let’s check out the ‘Set-ComplianceSearchAction’ cmdlet and see what we can do with it:
Get-Help Set-ComplianceSearchAction -Examples
Interesting, not much there. Let’s check out the full help for the cmdlet:
Okay. So we won’t be able to use this cmdlet in the Security and Compliance Center… on to the next cmdlet!
Get-CaseHold Cmdlets
These cmdlets will allow us to work with Case Holds in the SCC. Let’s see what PowerShell has for us:
Get-Command *hold*
We get these commands:
Get-CaseHoldPolicy
Get-CaseHoldRule
Get-HoldCompliancePolicy
Get-HoldComplianceRule
Running Get-CaseHoldPolicy gives us an error:
It looks like we need to actually specify a Case Hold Policy in order to query it.
Okay. What about ‘Get-CaseHoldRule’ ?
That matches what we need, so let’s explore the Case Hold Rules:
If we want, we can export these for later reference/documentation when building new Case Hold Rules:
Get-CaseHoldRule | Export-CSV -Notype c:scccompliancecaseholdrules.csv
Now that we have the Case Hold Rules documented, we can document the search. Again, we can search for any cmdlet with ‘search’ in it to see what is available in the ‘Get-’ based cmdlets:
Get-Command *search*
We find that there are two available to be used:
Get-ComplianceSearch
Get-ComplianceSearchAction
Since this is a search and not and action, we will run the first cmdlet:
Well, that was certainly unexpected as we have a previously created search. How do we find the search then? If we look back at the previous screenshots, we have the name of the search.
Let’s use that to see what we can find:
Much better. However, this can make a more automated approach. Maybe there is a work around? Let’s review the available parameters for the Get-ComplianceSearch cmdlet:
Get-ComplianceSearch [-Identity <ComplianceSearchIdParameter>] [-Case <String>] [-DomainController <Fqdn>] [-ResultSize <Unlimited>] [<CommonParameters>]
There is a parameter ‘Case’ that might be useful. Let’s verify what we can do with this parameter:
That’s convenient. So we have an option that could make this discovery process work, but one cmdlet gives us no results and another has useful parameters that is for Microsoft use. Let’s try this parameter, just remember that Your Mileage May Vary (YMMV) on whether it works 100% of the time:
It was successful. So this would make things a bit easier for discovery. We can get all of the searches for a particular Compliance Case and then export those details for importing in our test tenant.
Get-ComplianceSearch -Case “Hold for some mailboxes” | Export-CSV -NoTypeInformation “c:scccompliancesearches.csv”
Opening the output in Notepad would look like this:
Now we have our holds and searches documented for our Compliance Case. The only other information that was not exported was the Exports tab, but that is not as important as those are exported results. We should not need those for the QA environment.
Putting it all together
Now that we have pulled the information in piece meal, we need a way to pull all of the cases, searches and holds and then store them in a manner that would make it easier to restore in the QA tenant. How are we going to do that?
The most difficult piece to pull together is how do we link the Case Holds to a Compliance Case so we can bundle like this:
Compliance Case
|-- Case Hold Rule
|-- Compliance Search
The problem is that when we review a Case Hold Rule we do not see a Case in the details of the hold. However, if we look closer at the resulting properties of the Case Hold Rule (Get-CaseHoldRule), we see a parameter called ‘Policy’ as seen below:
There was another cmdlet we saw before called ‘Get-CaseHoldPolicy’. Possibly this would help us track down the Case link? Let’s see:
Get-CaseHoldPolicy 0c70eac9-adfb-4574-b66f-c41ff4df80a8 | Fl
Now we have the Case Hold Rule, linked to the Case Hold Policy which is linked to the Compliance Case. If we check that Case ID against our cases, we see it matches what we originally started with:
The only issue becomes how we can match a Case Hold Rule to the Case if we do not have a direct link (via the Policy ID)? Well, we use PowerShell as show below with this script for Compliance Cases, Case Hold Rules and Compliance Searches:
# Clear The Screen
CLS
$Path = (Get-Item -Path “.” -Verbose).FullName
$ComplianceCasesNames = (Get-ComplianceCase).Name
$CaseHoldRules = Get-CaseHoldRule
Foreach ($ComplianceCasesName in $ComplianceCasesNames) {
Write-Host “Examining Compliance Case $ComplianceCasesName” -ForegroundColor Cyan
Write-Host “----------------------------------------------” -ForegroundColor Cyan
# Variables for Loop
$Found1 = $False
$Found2 = $True
# Document Compliance Case
$CurrentCaseID = (Get-ComplianceCase $ComplianceCasesName ).Identity
$Destination = “$Path”+“”+“$CurrentCaseID”+“-ComplianceCase.csv”
$ComplianceCase = Get-ComplianceCase $ComplianceCasesName | Export-CSV -Notype $Destination
# Document any Case Hold Rules
Foreach ($CaseHoldRule in $CaseHoldRules) {
$Policy = $CaseHoldRule.Policy
$PolicyID = Get-CaseHoldPolicy $Policy
$CaseID = $PolicyID.CaseID
$ValueToCheck = (Get-ComplianceCase $CaseID).Identity
$CaseHoldRuleName = $CaseHoldRule.Name
# Write-host “CaseID = $CaseID / ValueToCheck = $ValueToCheck” -ForegroundColor Red
If ($ValueToCheck -eq $CurrentCaseID) {
$Destination2 = “$Path”+“$CurrentCaseID-CaseHoldRule-”+“$CaseHoldRuleName”+“.csv”
$CaseHoldRule = Get-CaseHoldRule $CaseHoldRuleName | Export-CSV -Notype $Destination2
$Found1 = $True
}
}
If ($Found1) {
Write-host “Found Case Hold Rules for $ComplianceCasesName.” -ForegroundColor Green
} Else {
Write-host “No Case Hold Rules found for Compliance Case - $ComplianceCasesName.” -ForegroundColor Yellow
}
# Document searches
$Destination3 = “$Path”+“”+“$CurrentCaseID”+“-Searches-”+“$CaseHoldRuleName”+“.csv”
$Search = Get-ComplianceSearch -Case $ComplianceCasesName
If ($Search -eq $Null) {
$Found2 = $False
}
If ($Found2) {
Write-Host “Compliance Searches were found for Compliance Case - $ComplianceCasesName.” -ForegroundColor Green
$Search | Export-CSV -NoTypeInformation $Destination3
} Else {
Write-Host “No Compliance Searches found for Compliance Case - $ComplianceCasesName.” -ForegroundColor Yellow
}
Write-Host ‘ ’
}
The output from the script results in these files:
When running the script, you should see something like this:
Retention Compliance
Previously there was a set of cmdlets dedicated to Hold Compliance Rules and Policies. However, these were replaced with Retention Compliance Policies and Rules. With this change were accommodations for Teams holds as well.
PowerShell
Again, we can see what cmdlets are available for Compliance Hold PowerShell cmdlets:
Get-Command *RetentionCompliance*
This provides us with eight PowerShell cmdletS:
Get-RetentionCompliancePolicy
Get-RetentionComplianceRule
Get-TeamsRetentionCompliancePolicy
Get-TeamsRetentionComplianceRule
New-RetentionCompliancePolicy
New-RetentionComplianceRule
New-TeamsRetentionCompliancePolicy
New-TeamsRetentionComplianceRule
Remove-RetentionCompliancePolicy
Remove-RetentionComplianceRule
Remove-TeamsRetentionCompliancePolicy
Remove-TeamsRetentionComplianceRule
Set-RetentionCompliancePolicy
Set-RetentionComplianceRule
Set-TeamsRetentionCompliancePolicy
Set-TeamsRetentionComplianceRule
We see that there is a series of cmdlets for Teams and non-Teams Compliance Rules and Policies.
Retention Compliance Policy - refers to the location and content to be retained
Retention Compliance Rule - refers to the created policy and determines the retention time
As we have Teams and non-Teams related cmdlets, we will start with the more generic cmdlets (without the ‘Teams’ noun in the cmdlet) to explore those first. Then we will explore the Teams related cmdlets at the end of this section.
Get-RetentionCompliancePolicy and Get-RetentionComplianceRule
By default, neither of these Get cmdlets should reveal anything in a new tenant as these are not pre-created items in Office 365. That being said, once we have Policies and Rules created we can list them with these two cmdlets:
Now, let’s go create some Retention Compliance Policies and Rules to get a better understanding of what is possible.
New-RetentionCompliancePolicy and New-RetentionComplianceRule
In order to create a function rule we need to run both of these cmdlets in series. The first is a policy, which will define what we are retaining with options or exceptions, while the other applies that policy and enforces a time for the policy to be in place. We will run through some scenarios to help guide us in a real way to use these PowerShell cmdlets.
Scenario One
A company is moving to Office 365. Their plan is to use Exchange and OneDrive initially. All other services will be turned off (i.e. users will not have licenses for any other products on the cloud). As part of their on-premises retention policies, they are required to retain information for three years. At that point the Exchange data will be removed, but files will no longer be protected from deletion.
In order to accomplish these tasks we will have to create two sets of policies and rules for compliance. This will allow us to accommodate both options when retention ends. Let’s review an example of each PowerShell cmdlet to see what we options we need to configure for these policies and rules.
New-RetentionCompliancePolicy
New-RetentionComplianceRule
In the above examples we see we can specify Exchange locations, but the example shows individual mailboxes not all mailboxes. So how do we specify all mailboxes? We can see the syntax needed in the Get-Help for the cmdlet here:
Looks like we can specify ‘-ExchangeLocation All’ to apply this policy to all mailboxes in Exchange Online.
If we wish this policy to be locked where no one can undo the settings, we need to use the RestrictiveRetention parameter (-RestrictiveRetention $true ) as this locks out the administrator as well. Be sure this is what is required as the policy cannot be reduced, disabled or turned off.
New-RetentionCompliancePolicy -Name ‘3 Year Exchange’ -Comment ‘Exchange three year retention policy.’ -ExchangeLocation All
The same Policy could be expanded to include Modern Groups with this parameter ‘-ModernGroupLocation All’. While Modern Groups are not technically mailboxes, their data is stored within Exchange. It would be up to the Compliance Officer at a company to decide what needs to be covered and if Modern Groups fits the definition of what is required.
With a Retention Compliance Policy in place, we can now create a rule that will set the three year clock for items in Exchange Online. The example provided is a good starter, but not nearly enough for what we need. Yes, we can give the rule a name; yes we can provide the affected Policy ; what about duration and action? How do we specify those? We can either look at Get-Help or Microsoft Docs, whichever you’re more comfortable with.
From the Help for the cmdlet, we see there are two options we need to work with - RetentionComplianceAction and RetentionDuration. With these we can specify three years and deletion of the mailbox content. Here is our new one-liner to create our Retention Compliance Rule:
New-RetentionComplianceRule -Name ‘Three Year Keep and Delete - Exchange’ -Policy ‘Three Year Exchange’ -RetentionDuration 1095 -RetentionComplianceAction KeepAndDelete
Note that the ‘RetentionDuration’ parameter is listed in the number of days, which in this case is 3*365 = 1095 days. The RetentionComplianceAction is set to Keep and Delete as the items will be held and then at 1095 they will be removed from the mailbox.
Scenario Two
For this scenario, we need to place everyone in the HR and Legal departments in a seven year hold. For the data, we need to cover Exchange, OneDrive, ModernGroups and more. After the seven year period has expired the items are no longer helped for retention, but they do not need to be deleted. After seven years, no retention policy needs to apply as it is out of the legally required range for these users.
How do we get a full list of all OneDrive sites. Microsoft provides us with a site from which we can pull a list of all OneDrive URLs from this site:
https://docs.microsoft.com/en-us/onedrive/list-onedrive-urls
Assuming we ran the script, we will use these OneDrive locations for our example:
https://bigcompany-my.sharepoint.com/personal/nicholas_bigcompany_net
https://bigcompany-my.sharepoint.com/personal/john_bigcompany_net
https://bigcompany-my.sharepoint.com/personal/damian_bigcompany_net
https://bigcompany-my.sharepoint.com/personal/sarah_bigcompany_net
https://bigcompany-my.sharepoint.com/personal/pyra_bigcompany_net
https://bigcompany-my.sharepoint.com/personal/max_bigcompany_net
https://bigcompany-my.sharepoint.com/personal/sandra_bigcompany_net
Next, we will need a list of Groups that need to be covered by this policy as well. For our example, we have two Modern Groups - ‘HR’ and ‘Legal’ - that need to be covered by this policy.
New-RetentionCompliancePolicy -Name ‘7 Year Office 365 - HR and Legal’ -Comment ‘Legally required hold for HR and Legal departmental users.’ -ModernGroupLocation HR,Legal -ExchangeLocation HR,Legal -OneDriveLocation ‘https://bigcompany-my.sharepoint.com/personal/nicholas_bigcompany_net;https://bigcompany-my.sharepoint.com/personal/john_bigcompany_net;https://bigcompany-my.sharepoint.com/personal/damian_bigcompany_net;https://bigcompany-my.sharepoint.com/personal/sarah_bigcompany_net;https://bigcompany-my.sharepoint.com/personal/pyra_bigcompany_net;https://bigcompany-my.sharepoint.com/personal/max_bigcompany_net;https://bigcompany-my.sharepoint.com/personal/sandra_bigcompany_net’
** Note ** It might be worth using a variable for the OneDrive Location.
We can then use this Retention Compliance Policy and create a Retention Compliance Rule:
New-RetentionComplianceRule -Name ‘Seven Year Keep - Office 365 - HR/Legal’ -Policy ‘Seven Year Office 365 - HR and Legal’’ -RetentionDuration 2555 -RetentionComplianceAction Keep
If we look at the Advanced Options of the New-RetentionComplianceRule PowerShell cmdlet we see these options:
ApplyComplianceTag - this parameter will specify a tag that is applied to all affected content
PublishComplianceTag - specifies a label that is now visible to user apps
ContentContainsSensitiveInformation - specifies a sensitive information type as a condition for matching
ContentMatchQuery - specifies a Keyword Query Language (KQL) query for matching content **
ExcludedItemClasses - excludes certain types of messages - like ‘IPM.Note.Microsoft.Voicemail.UM’
RetentionDurationDisplayHint - changes the duration display to unit of your choice in the Security and Compliance Center console - Days, Months, or Years
** Note ** More information on KQL query syntax can be found here - https://go.microsoft.com/fwlink/?LinkId=269603
Now that we’ve created some Retention Compliance Policies and Rules, let’s explore how we can manage these with Get, Remove and Set cmdlets.
Remove-RetentionCompliancePolicy and Remove-RetentionComplianceRule
In theory, since we created our Rules and Policies in a certain order, we should remove them in the same order. However, we do not have to do that. We can remove them in either order. When you remove a Policy first, we noticed that the Policy does not actually get removed at first. It hangs around:
Why did the Policy not delete? It’s not because the Rule was still in place, but it is in a ‘PendingDeletion’ Mode:
Eventually both the Rule and Policy will be removed from the tenant after background responses are run.
Set-RetentionCompliancePolicy
After creating a Policy, we can modify quite a few settings. We can remove OneDrive locations, SharePoint locations, Exchange Locations, SkypeLocations, TeamsLocations and ModernGroupLocation as well as add additional locations for all those Office 365 workloads as well.
For a real world example, if we have a retention policy for a list of mailboxes, we can add more users as they are required by a Legal department. Or we could remove mailboxes as users leave a company or are no longer required, say for legal reasons.
Set-RetentionComplianceRule
Now, for an existing Retention Compliance Rule, we can modify the duration, excluded item classes, add sensitive information types, add tags and more. A practical example of a good usage for Set-RetentionComplianceRule is to add an ExcludedItemClass. For example, maybe we do not need to retain Voicemails, this can be changed post creation of the rule by simply running a line like this:
Set-RetentionComplianceRule -Name ExcludedItemClasses IPM.Note.Microsoft.Voicemail
** Note ** Items that are excluded will not be retained or protected once they are excluded.
Now they will be excluded as they were not legally required (for this scenario). MSDN has classes definitions here:
Teams Retention Compliance Policies and Rules
As was explained before, we have regular Retention Compliance Policies and Rules and Teams-centric Retention Compliance Policies and Rules. For this section we’ll explore the Teams-centric ones to see what the difference is. As with the above regular cmdlets, the Teams-centric ones have the same verbs (Get, New, Remove and Set) as well as the same nouns with Retention Compliance Policies and Rules.
Get-TeamsRetentionCompliancePolicy
Get-TeamsRetentionComplianceRule
New-TeamsRetentionCompliancePolicy
New-TeamsRetentionComplianceRule
Remove-TeamsRetentionCompliancePolicy
Remove-TeamsRetentionComplianceRule
Set-TeamsRetentionCompliancePolicy
Set-TeamsRetentionComplianceRule
Just like the regular Policies and Rules, there are no Teams-centric Policies or Rules pre-created in your new Office 365 tenant. If we want to use these, we’ll need to create our own. Let’s explore the New-* cmdlets and their examples to see what we can do with these cmdlets. Get-Help for either cmdlet reveals no cmdlet examples:
All is not lost though as Microsoft Docs contains examples for both:
New-TeamsRetentionCompliancePolicy -Name “Teams - Regulation 123 Compliance” -TeamsChannelLocation “Engineering Team”, “UX Design Team” -TeamsChatLocation “Kitty Petersen”, “Scott Nakamura”
and
New-TeamsRetentionComplianceRule -Name “Teams - SeptOneYear” -Policy “Teams - Internal Company Policy” -RetentionComplianceAction Keep -RetentionDuration Unlimited
We can see from the above examples that in a sense only the New-TeamsRetentionCompliancePolicy cmdlet is materially different because we have Teams specify parameters. The Retention Compliance Rule cmdlet performs the same function as it assigns a particular action and time to a particular policy that was already created. Let’s work through some scenarios to see how we can apply a Retention Compliance Hold to our Teams data.
New-TeamsRetentionCompliancePolicy
First, what do we have for available options for this cmdlet? We can find these in the Get-Help or by hitting Ctrl-Space after typing in the cmdlet name. Here are ones we can use:
Name, Comment, TeamsChannelLocation, TeamsChannelLocationException, TeamsChatLocation and TeamsChatLocationException
Be aware that some parameters specified in the Get-Help are not available and are not listed as Internal Use or Microsoft Only. Let’s start with two criteria that we can use to select content to be retained.
TeamsChannelLocation - We can chose individual Teams in a list or use ‘All’
TeamsChatLocation - We can chose individual users in a list or select all users with ‘All’
Scenario One
For this case, we have a company that needs to retain all conversations by C-Level executives in Teams for an indefinite period of time. We need to create a Policy and Rule to handle this. Remember that a Compliance Rule will need to reference an existing Compliance Policy. We have a list of users who need to be covered:
Sandy Shu, Grant Gunther and Ron West
First we will create the Retention Compliance Policy:
New-TeamsRetentionCompliancePolicy -Name ‘C-Level Indefinite Teams Hold’ -TeamsChannelLocation All -TeamsChatLocation ‘Sandy Shu’, ‘Grant Gunther’,‘Ron West’
Then we can create our Rule with an indefinite hold:
New-TeamsRetentionComplianceRule -Name ‘C-Level Teams Hold Rule’ -Policy ‘C-Level Indefinite Teams Hold’ -RetentionComplianceAction Keep -RetentionDuration Unlimited
To verify that we’ve created our Policy correctly we can get use the Get-RetentionCompliancePolicy cmdlet. Make sure to use the -DistributionDetail Switch otherwise we won’t see these fields at all:
Scenario Two
We have a financial company that has a seven year retention policy for most content. Teams are now being deployed and Legal wishes to protect all teams and all chats in those Teams. The same seven year retention period needs to be applied. How can we do this in two one-liners?
New-TeamsRetentionCompliancePolicy -Name ‘All Teams / Channels Retention’ -TeamsChannelLocation All -TeamsChatLocation All
Now we can take the Policy, put it into a seven year Rule that does Keep and Delete for its retention action:
New-TeamsRetentionComplianceRule -Name ‘Seven Years All Teams / Channels’ -Policy ‘All Teams / Channels Retention’ -RetentionComplianceAction KeepAndDelete -RetentionDuration 2555
Now we’ve met the requirements passed down from Legal.