In the Microsoft Cloud, Sensitivity Labels have several components, including a label, a label policy, and one (or more) label policy rule(s). Typically, you first create a label and then publish the label so that its available for users, and when publishing a label, one (or more) label policy rule(s) is created.
Auto labeling policies are similar. You still create a label but instead publish it via an auto labeling policy and create auto labeling rule(s) based on one or more conditions. The main difference between auto labeling rules and label policy rules is that with auto labeling, the admin specifies and creates the rule(s) when creating the policy, while on label policies the rules are created based on action(s) you specified on the label.
Label actions are the specific actions that an admin sets on a label. Things like encrypt or placing a footer will generate a new entry under the "LabelActions" parameter of a label. You can see what actions exist on a label using S&C PowerShell:
$LabelName="Intended Label Name"
(Get-Label $AffectedLabel).LabelActions|ConvertFrom-Json|FT Type,SubType
Each action will create a rule for each label added to the label policy. So, if you have 2 labels and each has 3 actions, you will have 6 rules on the policy for those labels (3 per label). In turn, if you place the same 2 labels in 2 policies, you'll have 12 rules (3 actions x 2 labels x 2 policies).
For example, I created the label “TestEncryptUD” which has the following actions:
I then published this label on two label policies (scoped to different sets of users):
Now, let’s see how many rules were created. For you to visualize the label policy rules, you need to specify the policy by Name, ExchangeObjectId or Guid. We’ll also need to filter rules that refer to the label “TestEncryptUd”.
So, for the first policy, we have 2 rules, one per each action. (click to expand):
What about the second policy?
It’s also 2; one per each action. As such, in total there are 4 rules in this example (2 actions x 1 label x 2 policies).
If you create a label without any actions and add it to a label policy, it will still create a rule for the action "ApplyLabel" so that users specified in the policy have it available to use and apply:
If you have an action but remove it after adding it to the policy, the label actions are disabled (but not removed). Once created, actions are either disabled or enabled but they all still generate rules.
In this case, the ApplyLabel is necessary to connect the label to the policy when no action exists.
Above we see how label actions are reflected in the label policy rules upon being added (or published) into a label policy. But that is not the only link. The parameter “settings” on the label policy rule should be the same as what’s defined in the settings of the label policy:
This is true for all rules associated with a specific policy. In other words, if you see a label rule that does not correctly reflect the policy settings, that rule may be causing issues for users.
Troubleshooting using Label Policy Rules and other cmdlets
Each time labels or label policies are updated, the rules are updated in the backend as well. Sometimes, either by tempering with incorrect settings (in labels or label policies) or deleting objects that haven’t finished replicating can lead to orphan label policy rules (e.g., rules that are present but refer to an incorrect label action or a label that doesn’t exist). These can cause problems when a client downloads the policies and labels. In some cases, this can lead to some or all labels not showing, or showing only in certain clients.
Now that we understand how label rules integrate with policies and labels, let’s take a look at how you can use label policy rules to find and address orphaned objects.
The problem: In the following example, Contoso organization engaged Microsoft support because they weren’t able to see labels in any of their Office apps. Changing labeling clients didn’t change the behavior. The only difference was when using the Office (UL) client, the button would not be greyed out:
You can find more information about both clients at The client for Azure Information Protection.
In the web client, the labels were displayed and could be used. Contoso reported that they have 4 labels and 2 label policies. Here’s what we did to troubleshoot this.
Client Logs
The first step was to export and collect logs from the installable UL plugin to assist with troubleshooting the issue. After analyzing the exported logs, especially mip_sdk.miplog, we could see several entries; one was particularly interesting:
But this didn’t help much as the remaining log doesn’t indicate what is inconsistent on the labels, policies, or rules. Next, we looked at the current label configuration.
Label Configuration
Before checking the rules, we must verify that the labels do not have parsing errors and aren’t in a PendingDeletion state. For collecting this info, we can use the following:
$LabelDetails=Get-Label -IncludeDetailedLabelActions $true
Next, we filter the parameters, as shown below:
There are 4 labels. So, there’s no distribution or parsing issue. Let’s see how many actions these labels contain:
There are 2 labels with no action, 1 label with one action, and 1 label with 2 actions. This means that, if we add all 4 to a single label policy, we’d expect 5 rules to be created.
Label Policies
Let’s now take a look at the label policies by checking their DistributionStatus and Mode:
We can see a label policy in PendingDeletion and two in “Pending” status. If the policy shows Pending status, you should wait until its successfully distributed. Labels, label policies and label policy rules can also be in a PendingDeletion state. This should not last more than 24 hours, and if it does, we recommend contacting Microsoft support.
Next, we need to verify if the 2 label policies are really pending or not. Label policies show the correct “DistributionStatus” when you specify the label policy name. If you want to check all policies at once, you can use the following command:
$DistDetails=(Get-LabelPolicy|%{Get-LabelPolicy -Identity $_.Identity})|Select Name,DistributionStatus,Mode;DistDetails|FT
According to Contoso, LabelPolicy3 was deleted several days ago. So, until now we haven’t seen any errors on labels, there’s a label policy in PendingDeletion (LabelPolicy3), and the remaining two policies are correctly distributed. Now let’s check the label policy rules.
Label Policy Rules
Let’s look at LabelPolicy3 as its in PendingDeletion. Since it doesn’t contain any labels, rules shouldn’t exist, right?
But here we see a rule still linked to this policy that is also in a PendingDeletion state.
Next, let’s check LabelPolicy1. This policy contains all labels; therefore, we would expect 5 rules to be listed:
In this case, we have 6 rules. There’s a rule in PendingDeletion that was previously associated with a label called MarketingTest, which no longer exists.
Now let’s check the second policy.
Here we see the expected 5 rules associated with LabelPolicy3.
As stated previously, the label policy rules should reflect the same settings as the associated policy. So, for the first one (LabelPolicy1), we see:
It seems one of the label actions from the internal label didn’t update/replicate correctly. This can be due to several deletion actions occurring before replication completed. The DefaultLabelId values refer to the MarketingTest label, which is no longer available.
Reviewing the second one (LabelPolicy2) and its respective rules, we see:
Although all rule settings match the policy settings, there’s another parameter that’s incorrectly set/placed. The OutlookDefaultLabel is a label policy advanced setting.
This value is expected to have an immutable label ID assigned. If the setting is disabled, it should be removed as there is no “none” value for this option. You can learn more about advanced settings here.
Lastly, just for consistency, let’s check the last policy (LabelPolicy3):
Although there are no inconsistencies, we already know that the label policy and label policy rule are in PendingDeletion, and as such, they will need to be eliminated.
Working towards issue resolution
Based on the above, we conclude that:
- LabelPolicy1 has a rule mentioning a label action for a label that no longer exists and a rule for an existing label that hasn’t correctly updated/replicated. Therefore it contains incorrect settings.
- LabelPolicy2 has an incorrect advanced setting value (OutlookDefaultLabel -> None) which led to the same incorrect value in all associated rules.
- LabelPolicy3 is in pending deletion state and it contains a rule that is also pending deletion.
To resolve this, the Contoso admin removed all labels from this policy using Set-LabelPolicy -Identity LabelPolicy1 -RemoveLabels Public, HR, Internal, Confidential. Next, they created a new label policy (with a new name) and re-added all the labels. After confirming the previous LabelPolicy1 has no labels, they deleted it.
Once the admin performed these actions, Microsoft Support issued a forced removal of the “PendingDeletion” rule associated with this policy and verified LabelPolicy1 was deleted.
For the second, the admin ran:
Set-LabelPolicy -Identity LabelPolicy2 -AdvancedSettings @{outlookdefaultlabel=""}
We later confirmed that all rules from this policy had the setting removed, as well.
For the last issue, Microsoft Support performed a forced deletion of the last label policy and label policy rule, both of which were in a pending deletion state.
After all this, the Contoso admin cleared/reset the labeling client (please see post appendix below) by closing all Office apps and re-opening one of them to check. Here’s what they found:
At this point, the issue was fixed!
Appendix
The Unified labeling plugin has a reset option but if you want to reset the built-in labeling client, you can use the UnifiedLabelingSupportTool (PowerShell Gallery | UnifiedLabelingSupportTool 3.0.1).
After installing and importing the module, you can run “UnifiedLabelingSupportTool -Reset Silent” in PowerShell with all Office apps closed. This tool can also be used to reset the Plugin or as a troubleshooting tool.
The script used for label data collection:
# Create a folder under C:\ called "Temp". Then, connected to S&C, run:
Get-Label|Export-Clixml -path "C:\Temp\Labels.xml"
$AllPolicies=Get-LabelPolicy; $AllPolicies|Export-Clixml -path "C:\Temp\LabelPolicies.xml"
# Collect label parsing issues:
Get-Label -IncludeDetailedLabelActions $true|Export-CliXml -path c:\Temp\LabelDetails.xml
# Collect Label Policy Distribution Details:
$DistDetails=Foreach ($AS in $AllPolicies) {Get-LabelPolicy $AS.name | Select Name,Dist*};$DistDetails |Export-Clixml -path C:\Temp\DistDetails.xml
# Collect LabelPolicy Rules:
$AllRules=Foreach ($AP in $AllPolicies) {Get-LabelPolicyRule -Policy $AP.ExchangeObjectId.guid}; $AllRules|Export-Clixml -path C:\Temp\LabelRules.xml
# For Auto Labeling Policies and Rules:
Get-AutoSensitivityLabelPolicy | Export-Clixml -Path C:\Temp\AutoLabelPolicies.xml
Get-AutoSensitivityLabelRule | Export-Clixml -Path C:\Temp\AutoLabelPolicyRules.xml
This will generate 7 xml files that can be imported to another PowerShell without the need to be connected.
For importing all the files into variables:
$path="Path to folder" # Ex: C:\testfolder
$Items=Get-ChildItem -Path $path |? {$_.Extension -match "xml"}; foreach ($it in $Items) {New-Variable -Name $it.Basename -Value (Import-Clixml -Path $it.Fullname) -Description "LabelsTroubleshoot"}; $SensitivityVars=Get-Variable |? {$_.Description -match "LabelsTroubleshoot"}| % {'$'+"$($_.Name)"};$SensitivityVars
Hopefully you found this useful! Please let me know below if questions!
(Exchange Online Tech Lead / Support Escalation Engineer)
Microsoft
