This article is contributed. See the original author and article here.
Azure Information Protection (AIP) Unified Labeling (UL) client allows administrators to enable pop-up messages in Outlook that can warn users before sending an email, ask them to provide justification why they are sending an email, or prevent them from sending an email for either of the following scenarios:
- Their email or attachment for the email has a specific label:
- The attachment can be any file type.
- Their email or attachment for the email doesn’t have a label:
- The attachment can be an Office document or PDF document.
Please review this article to learn more about how to implement this configuration.
Based on our customers’ feedback, in the latest release of the AIP UL (version 2.8.85.0) client, we added the ability to customize pop-up messages. AIP administrators are now able to better align those messages to their company culture, and honor legal, security, and other requirements. Please take a moment to review our official documentation here.
Let’s review examples of those pop-up messages before and after customization.
The goal of this article was to use one of the most common scenarios to explain the deployment process in more detail as well as share lessons learned while helping our customers implement these customizations.
Let’s review the implementation process using the following requirements as an example:
- Emails and/or attached documents labeled as Confidential All Employees, Highly Confidential All Employees, and Highly Confidential Project Poseidon cannot be sent to external recipients.
- Emails and/or attached documents labeled as Highly Confidential Project Zeus require user’s consent before sending to external recipients.
- Emails and/or attached documents labeled as Highly Confidential Project Apollo require user’s justification before sending to external recipients.
- Use wording for the pop-up messages provided by the company’s legal team.
- Internal domains contoso.onmicrosoft.com and microsoft.com should be excluded from the detection logic.
We highly recommend creating a dedicated label policy for this configuration as opposed to using one of the existing policies. This will significantly simplify testing and implementation by targeting new configuration to only limited and controlled groups of users. Please make sure that this policy publishes the sensitivity labels you would like to use for your Outlook pop-ups controls.
Important: Once you have enabled customization options, your existing Outlook pop-up configuration will be ignored
and only settings configured in the new customization policy will be evaluated for users and groups this policy
was published to.
First, we need to find out the labels’ GUIDs that we are going to use later. As of this writing (October 2020) you can find this information in the Azure Portal on the label configuration page:
Alternatively, you may use PowerShell and retrieve all label’s GUIDs at once:
$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 -DisableNameChecking
Get-Label | Format-Table name,guid -AutoSize
We are going to use a separate policy rule for each action: block, warn, and justify. For each rule we are going to create a corresponding JSON file (you can find downloadable examples in the end of the article).
The general syntax for configuration of these rules is:
$filedata = Get-Content "<Path to json file>"
Set-LabelPolicy -Identity <Policy name> -AdvancedSettings @{<Key> ="$filedata"}
You can name those files whatsoever you want but the <Key> name has to be OutlookCollaborationRule_<#>, where <#> is the serial number used to define the order in which rules are processed.
In our example, the order is going to be: Block, Warn, Justify:
# Pop-up customizations
# Block rule customization.
$filedata = Get-Content "block.json"
Set-LabelPolicy -Identity "Outlook Pop-ups Customization" -AdvancedSettings @{OutlookCollaborationRule_1 ="$filedata"}
# Warn rule customization.
$filedata = Get-Content "warn.json"
Set-LabelPolicy -Identity "Outlook Pop-ups Customization" -AdvancedSettings @{OutlookCollaborationRule_2 ="$filedata"}
# Justify rule customization.
$filedata = Get-Content "justify.json"
Set-LabelPolicy -Identity "Outlook Pop-ups Customization" -AdvancedSettings @{OutlookCollaborationRule_3 ="$filedata"}
And to confirm that the customizations have been added:
(Get-LabelPolicy -Identity "Outlook Pop-ups Customization").Settings
Now we are going to take a close look at these three JSON files because this is where you configure all the conditions and requirements for your rules.
We can’t emphasize enough that the JSON parser in the AIP client is very sensitive to the right syntax, so be very careful with punctuation marks. If in doubt, please consider using one of the free online tools, e.g. Code Beauty or JSONLint.
Block.json:
{
"type" : "And",
"nodes" : [
{
"type" : "Except" ,
"node" :{
"type" : "SentTo",
"Domains" : [
"contoso.onmicrosoft.com",
"microsoft.com"
]
}
},
{
"type" : "Or",
"nodes" : [
{
"type" : "EmailLabel",
"LabelId" : "0797a8a8-7aca-428e-a0d8-140906176f07"
},{
"type" : "AttachmentLabel",
"LabelId" : "0797a8a8-7aca-428e-a0d8-140906176f07",
"Extensions": [ ".docx", ".doc", ".pptx", ".ppt", ".xlsx", ".xls", ".pdf", ".pfile" ]
},{
"type" : "EmailLabel",
"LabelId" : "387bb92f-ffa8-45e2-ba80-e0e91ccd485b"
},{
"type" : "AttachmentLabel",
"LabelId" : "387bb92f-ffa8-45e2-ba80-e0e91ccd485b",
"Extensions": [ ".docx", ".doc", ".pptx", ".ppt", ".xlsx", ".xls", ".pdf", ".pfile" ]
},{
"type" : "EmailLabel",
"LabelId" : "e879fc3b-5b12-4796-9775-efb8ece57a79"
},{
"type" : "AttachmentLabel",
"LabelId" : "e879fc3b-5b12-4796-9775-efb8ece57a79",
"Extensions": [ ".docx", ".doc", ".pptx", ".ppt", ".xlsx", ".xls", ".pdf", ".pfile" ]
}
]
},
{
"type" : "Block",
"LocalizationData": {
"en-us": {
"Title": "Email Blocked",
"Body": "Your organization's policy does not allow sharing content classified as <Bold>${MatchedLabelName}</Bold> <br>with external recipients:<br><br>${MatchedRecipientsList}<br><br><br>Consider removing these recipients, or replace the content."
},
"es-es": {
"Title": "Correo electrónico bloqueado",
"Body": "La política de su organización no permite compartir contenido clasificado como <Bold>${MatchedLabelName}</Bold> <br>con destinatarios externos:<br><br>${MatchedRecipientsList}<br><br>Considere la posibilidad de quitar estos destinatarios o reemplazar el contenido."
}
},
"DefaultLanguage": "en-us"
}
]
}
Warn.json:
{
"type" : "And",
"nodes" : [
{
"type" : "Except" ,
"node" :{
"type" : "SentTo",
"Domains" : [
"contoso.onmicrosoft.com",
"microsoft.com"
]
}
},
{
"type" : "Or",
"nodes" : [
{
"type" : "EmailLabel",
"LabelId" : "8ffe71cd-04ea-4700-9e5c-30ab2ada2058"
},{
"type" : "AttachmentLabel",
"LabelId" : "8ffe71cd-04ea-4700-9e5c-30ab2ada2058",
"Extensions": [ ".docx", ".doc", ".pptx", ".ppt", ".xlsx", ".xls", ".pdf", ".pfile" ]
}
]
},
{
"type" : "Warn",
"LocalizationData": {
"en-us": {
"Title": "Warning",
"Body": "Your organization's policy requires your confirmation before sharing content classified <br>as <Bold>${MatchedLabelName}</Bold> with external recipients:<br><br>${MatchedRecipientsList}<br>"
},
"es-es": {
"Title": "Advertencia",
"Body": "La política de su organización requiere su confirmación antes de compartir contenido clasificado <br><Bold>${MatchedLabelName}</Bold> con destinatarios externos:<br><br>${MatchedRecipientsList}<br>"
}
},
"DefaultLanguage": "en-us"
}
]
}
Justify.json:
{
"type" : "And",
"nodes" : [
{
"type" : "Except" ,
"node" :{
"type" : "SentTo",
"Domains" : [
"contoso.onmicrosoft.com",
"microsoft.com"
]
}
},
{
"type" : "Or",
"nodes" : [
{
"type" : "EmailLabel",
"LabelId" : "dd52888b-140e-45e1-b2b9-12a7d3631dc5"
},{
"type" : "AttachmentLabel",
"LabelId" : "dd52888b-140e-45e1-b2b9-12a7d3631dc5",
"Extensions": [ ".docx", ".doc", ".pptx", ".ppt", ".xlsx", ".xls", ".pdf", ".pfile" ]
}
]
},
{
"type" : "Justify",
"LocalizationData": {
"en-us": {
"Title": "Justification Required",
"Body": "Your organization's policy requires justification before sharing content classified as <Bold>${MatchedLabelName}</Bold> <br>with external recipients:<br><br>${MatchedRecipientsList}",
"Options": [
"I confirm the recipients are approved for sharing this content",
"My leadership approved sharing of this content",
"Other, as explained"
]
},
"es-es": {
"Title": "Justificación necesaria",
"Body": "La directiva de su organización requiere justificación antes de compartir contenido <br>clasificado como <Bold>${MatchedLabelName}</Bold> con destinatarios externos:<br><br>${MatchedRecipientsList}",
"Options": [
"Confirmo que los destinatarios están aprobados para compartir este contenido.",
"Mi liderazgo aprobó compartir este contenido",
"Otro, como se explicó"
]
}
},
"HasFreeTextOption":"true",
"DefaultLanguage": "en-us"
}
]
}
As you have probably noticed, every file has three main sections. The first one defines domains excluded from the rule. In our example we excluded contoso.onmicrosoft.com and microsoft.com internal domains from all three rules. You can add as many domains to the list as you need. But if you don’t want to make any exceptions, you need to remove the whole “Except” section:
{
"type" : "Except" ,
"node" :{
"type" : "SentTo",
"Domains" : [
"contoso.onmicrosoft.com",
"microsoft.com"
]
}
},
The next section of the files determines which labels (remember GUIDs we found out earlier) and what attachment types are going to be evaluated while processing the rules.
As of this writing (October 2020), you need to explicitly specify files types you want to add to the detection logic. This might change in future client releases and we will update this post accordingly.
"Extensions": [ ".docx", ".doc", ".pptx", ".ppt", ".xlsx", ".xls", ".pdf", ".pfile" ]
The last section determines an action to take on the email if the rule gets triggered: block, warn, or require justification. It also allows you to configure the wording of those messages in different languages if you need so.
If you would like to inform the user which attachment (they may attach multiple ones classified differently) has triggered a rule, you can use ${MatchedAttachmentName} variable and add it to the pop-up message itself, e.g.:
...
"type" : "Block",
"LocalizationData": {
"en-us": {
"Title": "Email Blocked",
"Body": "Your organization's policy does not allow sharing content classified as <Bold>${MatchedLabelName}</Bold> <br>with external recipients:<br><br>${MatchedRecipientsList}<br><br>This attachment is classified as <Bold>${MatchedLabelName}</Bold>:<br><br>${MatchedAttachmentName}<br><br><br>Consider removing these recipients, or replace the content."
},
...
Our official documentation covers several additional scenarios of how this new feature can be used.
If for any reason you would like to remove customization rules from your policy, you need to run the following commands:
Set-LabelPolicy -Identity "Outlook Pop-ups Customization" -AdvancedSettings @{OutlookCollaborationRule_1 =""}
Set-LabelPolicy -Identity "Outlook Pop-ups Customization" -AdvancedSettings @{OutlookCollaborationRule_2 =""}
Set-LabelPolicy -Identity "Outlook Pop-ups Customization" -AdvancedSettings @{OutlookCollaborationRule_3 =""}
And to confirm that the customizations have been removed:
(Get-LabelPolicy -Identity "Outlook Pop-ups Customization").Settings
Note: As of this writing (October 2020), we do not centrally (AIP Analytics) collect users’ responses to the “Justification” requests for future analysis or investigations. This is something we are considering adding to the next releases. Currently, this information can only be found in the local log files on the client.
While testing this, you might notice that it sometimes takes time for the AIP client to update locally cached policies. If you would like to expedite this process, you may consider forcing the client to do so:
- Close all Microsoft Office applications.
- Delete %LocalAppData%MicrosoftMSIP and %LocalAppData%MicrosoftMSIPC folders.
- Re-launch Outlook. If you get a warning saying AIP can’t apply a label because a template can’t be found, just close Outlook and open it again. This should solve the issue.
P.S. Consider joining our Yammer community where you can be one of the first to learn about MIP news, announcements, preview programs, meet information protection experts from around the world, and get your questions answered.
Brought to you by Dr. Ware, Microsoft Office 365 Silver Partner, Charleston SC.
Recent Comments