Often people came and asked this same question. Although all my eventual on-hands experience would increase, it can be tricky to answer to this question, or even just to give a straightforward method. To understand any kind of steps in a troubleshooting process, you have to know the product, know its features or purpose, and what's required to deploy it and/or in what order. Please join in as we share a few steps on how to troubleshoot sensitivity labels through this series. Hope you enjoy.
Even when trying to just scope it to an article can be quite limiting, but simply put, sensitivity labels can be seen in two perspectives. Item Categorization & Item access policies. These are enforced via metadata placed into a file or container, adding classification and/or access policies properties to each.
The Basics:
Let’s first make sure that all approached services in this article are configured and enabled for sensitivity labels.
Using the table below to know which PowerShell Modules you need to install (by running Install-Module XXX) and import (Import-Module XXX) to configure / troubleshoot Labels:
Want to install them “all at once”?
Install-Module AipService; Install-Module ExchangeOnlineManagement; Install-Module Microsoft.Online.Sharepoint.Shell; Install-Module AzureAd Preview
The first step is always to make sure the service and features are enabled. If you have issues on:
- AipService → After connection, make sure the service is enabled by running Enable-AipService
This is essential for any features related with encryption.
- Exchange Online (emails / OWA / Transport Rules) → Make sure IRM endpoint is correct and service is enabled*
Connected to AipService, run: $EndPoint=(Get-AipServiceConfiguration).LicensingIntranetDistributionPointUrl
Connected to Exchange Online set the endpoint: Set-IrmConfiguration -LicensingLocation $EndPoint
Then make sure the service is enabled for EXO, run: Set-IrmConfiguration -InternalLicensingEnabled $True - AzureRmsLicensingEnabled $True
*Note: If license containing MIP gets deprovisioned and you acquire new Licenses, do note that the endpoint changes
and needs to be updated.
- SharePoint Online, OneDrive or Office online apps (& online files) → Connected to SharePoint Online run: Set-SPOTenant -EnableAIPIntegration $true
- AzureAD or Groups → Connected to AzureAD, run: $grpUnifiedSetting = (Get-AzureADDirectorySetting | where -Property DisplayName -Value "Group.Unified" -EQ)
Make sure to enable the value: $Setting["EnableMIPLabels"] = "True"
Save the changes and apply settings: Set-AzureADDirectorySetting -Id $grpUnifiedSetting.Id -DirectorySetting $Setting
- Teams → Having met all the above requirements, wait for sync (I’d say a good couple of hours or day). Then, connected to S&C, run: Execute-AzureAdLabelSync
- PowerBI → Enable sensitivity labels in Power BI
Labels, Label actions, Label Policies and Label Rules
Although classification is useful when sorting an organization's access policy, item restrictions might not always be present. E.g., you can deem a label to your company without any encryption/access policy and just use it for item categorization (E.g., markings). This helps your users to sort content. Now, add the ability for an admin to place access restrictions to this content across most of the available apps and platforms on the Azure AD / Office 365 service and you can get quite some content to study. Not to mention having to "touch" the product, and often cross check documentation reminds us of the idea that testing, pre-deployment & research is essential for an administrator.
Having this said, now that we explained that a label can have classification "Markings" (Watermark, Header & Footer) & can enforce restrictions (Encryption and file/container access control), we need to know that what you configure on labels are "actions", and these actions can have its own customizations or options.
Like shown below, something like applying a header can have values to set color or margin (among others) but, the action type is simply to apply a header:
Command: (Get-Label “LabelName”).LabelActions | ConvertFrom-Json | ? {$_.SubType -match “Header”}|FL
PowerShell Module used: S&C
On the other hand, the action to encrypt for example, can be achieved in different ways:
Command(s): (Get-Label “LabelName”).LabelActions | ConvertFrom-Json | ? {$_.Type -match “encrypt”}|FL
PowerShell Module used: S&C
As you can see the LabelActions parameter is what stores all information regarding these customizations within a label. Therefore, it’s important to know how to check them. There are more parameters that can be explored and analyzed, especially when you consider the detail available with one extra parameter "-IncludeDetailedLabelActions" (left), although I do prefer to convert the LabelActions to a PowerShell object via “ConvertFrom-Json” cmd-let (right):
Command(s): Get-Label “LabelName” -IncludeDetailedLabelActions $True |FL *apply*,*Encryption*,*SiteAndGroupProtection* # on the Left
(Get-Label “LabelName”).LabelActions | ConvertFrom-Json |FL # on the Right
PowerShell Module used: S&C
We're getting a bit of head of ourselves here but, another thing you need to know is that each of the label actions create a rule when added to a policy. If you configure X actions, X rules are created. In turn, the label rules take the settings (including advanced settings) of the policies to which they are added, as below:
Command (s): (Get-Label "LabelName").LabelActions|ConvertFrom-Json|FL # 1st command
Get-LabelPolicyRule -Policy "PolicyName"|Select Name,LabelName,LabelActionName,Settings|FL # 2nd Command
Get-LabelPolicy "PolicyName" | Select Name,Labels,Settings|FL # 3rd Command
PowerShell Module used: S&C
Like mentioned on Using Label Policy Rules to Troubleshoot Label Issues, each of these can be impactful for the troubleshooting process. Ok, so now we have 3 components, labels, label policies & label rules and we now know how and why they're intertwined.
Licensing and Limitations
Before diving in on concepts like CAs or encryption, I'd like to also make an important but often foreseen issue, licensing. Although I won't delve on it much for now, I do want to remind that, for special features, including (but not only restricted to) client auto labeling and service side auto labeling (which we’ll approach in another part), as well as some advanced setting features, having the correct licensing is crucial. You can see more details about licensing on Subscription and licensing requirements for sensitivity labels, Plan comparison PDF or even here for some auto labeling features.
Equally important is documentation. Often we need to confirm if the setting / feature we are using is supported by the client being used, via documentation research as testing isn’t always enough to reach definite conclusions for our scenarios & behavior. To know what is expected and supported is equally important.
Another few limitations might originate on client or workload side. As sensitivity labels evolve and are integrated each time more on the Microsoft MIP & Purview platform and services, we do still need to approach some of the client issues as current limitations we’re trying to address to. Examples of this can be the custom permissions & user defined permissions (which do use custom permissions) not yet supported (but in development) in SPO (and in turn ODB & Office Online). Or, some of the client advanced settings only being available for some of the desktop clients.
Label Data Collection
Whatever is the case/issue, always make sure to note & collect label output via the mentioned cmd-lets:
What is intended? Who is affected? Is it one or all?
What is the label being used? Is it Published?
Does it affect other labels? Does it affect other labels in the same policy?
What is the client being used?
Remember that you can export the data to an xml format so that can be imported in another Powershell session (e.g. for microsoft support). To do this, create a folder called “temp” under c:\ and run:
Get-Label|Export-Clixml -Path C:\Temp\Labels.xml;Get-LabelPolicy |%{Get-LabelPolicy -Identity $_.Identity} | Export-Clixml -Path C:\Temp\LabelPolicies.xml;Get-LabelPolicy |%{Get-LabelPolicyRule -Policy $_.Identity}|Export-Clixml -Path C:\Temp\LabelRules.xml
To later import the data to another powershell session:
$path="" # 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
Transcript collection (Txt): $FormatEnumerationLimit=-1;Start-Transcript; Get-Label|FL; Get-LabelPolicy |%{Get-LabelPolicy -Identity $_.Identity}|FL; Get-LabelPolicy |%{Get-LabelPolicyRule -Policy $_.Identity}|FL
Encryption:
Having the above scope in mind, next we need to tackle the question: Does it have encryption?
For encryption we need to know that we’re using Rights Management Services (RMS) and Information Rights Management (IRM) app. For the first, Azure information protection needs to be enabled and its what provides the Protection Templates, Kinda like GPOs, these contain settings in regard to permission levels for each user. IE, who can access and what they can do with the content. The second, although more aimed at recipient permissions (since it originates in EXO) depends on RMS to work. IE, if RMS isn’t enabled for a tenant, IRM won’t work properly. That’s why we enabled both in the beginning. They can be the core for server side configuration.
RMS Templates
The RMS templates (or protection templates) are accessible and manageable via the AipService PowerShell module. Templates have a set of permissions for each account (or group) and are set by the administrator via label management GUI (e.g. S&C Portal). Upon label creation an admin can either select from 4 pre-defined groups (Co-Owner, Co-Author, Reviewer & Viewer), each containing a group of permissions or, stipulate their own individual permissions for a specific user or mail enabled group:
Command: ((Get-Label “LabelName”).LabelActions |ConvertFrom-Json | ? {$_.Type -match "Encrypt"}).Settings[-1].value # on the Left
(Get-AipServiceTemplate -TemplateId “TemplateID”).RightsDefinitions # on the Right
PowerShell Modules used: S&C & AipService
IMPORTANT: When a label with such template is published, the template’s status should pass to published* in AipService side. In our image above, our label is published (on a policy) as the templatearchived parameter in our label is showing as false. We can also see this in the template itself, as well as the label its linked to:
Command: Get-AipServiceTemplate -TemplateId “TemplateID”|FL *
PowerShell Modules used: AipService
*Note: This is not the case with IRM Templates, which are “managed” differently
Please do note that although is possible, managing a template directly (instead from within the sensitivity label GUI) can lead to errors or incorrect behavior, like is often the case with some of the client errors, although in some cases it can become necessary. As example of this, I’ve seen cases in which adding a label to a policy wouldn’t “trigger” this action (I.E. enable the template). As a result of this, the label would appear on the client, but we’d have the mentioned error “couldn’t apply template” as the clients would “see” the label but were unable to apply its backend template:
Labels already provisioned had no issues, only the new ones being created and published. To bypass this issue, one would have to publish (enable) the template directly by running (not applicable to Do not forward, Encrypt & user defined labels):
Set-AipServiceTemplateProperty -TemplateId "TemplateID" -Status Published
Its worth mentioning that seeing this error is not exclusive to the templates being disabled as other issues can cause the same error as we’ll see in future parts.
IRM Templates
For the IRM Templates, these depend on that the RMS endpoint is correctly configured, IRM to be enabled and do originate from EXO. Although you can “see” them via PowerShell (using the Get-RmsTemplate cmd-let from EXO), they are not directly manageable. You can still use them or allow users to use them in two ways. One is by having IRM configured and allow your users to use the built-in Exo Templates (Encrypt and Do Not Forward):
Example showing “Encrypt” and “Do not Forward” in OWA
The second is by creating user defined Labels (which will be applied to emails only). In this case, no Protection Template is created in AipService. In other words, the difference from the ones above picture (on EXO and recipient based) is that you can use them in labels you create that can also have markings & other actions:
For emails, the permissions will be placed by the users and its recipient based (IE, address on to, cc or bcc). If using the “Do Not Forward”, the recipients can’t forward, print or copy. If choosing the “Encrypt Only”, the recipients have all usage rights except Save As, Export and Full Control. For more information in regards to these and its differences, please check here
Therefore when creating a “user defined” permissions label, you see the below options (PowerShell comparison to the right):
Command: ((Get-Label “LabelName”).LabelActions | Convertfrom-json|? {$_.Type -match "Encrypt"}).Settings
PowerShell Modules used: S&C
For files, the user is prompted to set which permissions should be given to the intended account:
NOTE: Its worth mentioning that if you select the “encrypt-only” template in “let users assign permissions”, the label will only be shown in desktop apps if you use the Office built-In Client:
"(…) applying the Encrypt-Only option with a sensitivity label is a more recent release that's supported only by built-in labeling and not the Azure Information Protection unified labeling client."
SUPER IMPORTANT: Like mentioned, the status of the template is only applicable to “assign permissions now” labels.
Let’s assume that you first created a label with “assign permissions now” but then you later changed it to “user defined permissions”. Although not active, the initial template info is still listed on the label:
Command: ((Get-Label “LabelName”).LabelActions |ConvertFrom-Json | ? {$_.Type -match "Encrypt"}).Settings # 1st command
(Get-AipServiceTemplate -TemplateId “TemplateID”)|FT Names,Status # 2nd Command
(Get-LabelPolicy “LabelPolicyname)|FT Name,Labels # 3rd Command
PowerShell Modules used: S&C & AipService
Even if published, if the label is kept as a user defined permissions label after changing from “assign permissions now” then the template in these cases should show as archived, as you’re using the “Encrypt” or “Do Not Forward”, not the RMS template. This is expected.
Remove Protection
Its worth mentioning that there is a 3rd protection type, which is to remove protection, although its only applicable to the AIP Unified client. There are also other requirements in place for this action to be allowed to users. For more information on creating a label with an action for removing encryption, please read “What happens to existing encryption when a label is applied”.
Conditional access and / or Other Access Policies
Finally, as we talk a bit about Conditional Access (CA), we can again address it as access control as it does have an impact in content access by the internal or external user. Here, while still approaching emails, this is especially important if you’re talking about sharing external access with guests, like gmail.com. Let’s assume an organization has created a CA to enforce MFA on its user like the image below:
Note: Conditional access policies can also be consulted via Powershell by using Get-AzureADMSConditionalAccessPolicy from the AzureAD module
As you can see, the policy is applied to all users. As such, we send an encrypted email with an encryption labeled attachment to a gmail recipient. Gmail is listed as having permissions on the label. Gmail user also has a legitimate Microsoft Office 2019 Home & Business Subscription and a Microsoft account liked to it. Using either the OTP or the sign in option, the gmail recipient opens the email and can see the same. He then clicks on “Download” to see and edit the document in his local Office:
Upon trying to open the document in his local office, the user will be prompted for his account & password but afterwards this prompt appears:
This happens as the user is not added to the sender tenant as a guest. We then invite the user as guest and user accepts, but then after placing the account password, we this time see in the word app:
The external user receives the prompt due to the enforcement of the MFA CA policy which is applied to all users, including guests. As such, not only a guest object needs to be created on the sending tenant but, due to the policy, the external user will still be prompted to configure MFA on his guest account on that organization’s 365 tenant.
Although we’ll approach EXO’s OME Portal in more detail on a future part, these are examples of policies that can and will enforce admin restrictions upon an external guest, although you might need to consider if wanting to maintain all guest accounts or if you want these to be prompted for MFA in every scenario. You might also consider scoping the policies to specific users (like internal users only) or groups of users.
Another example (using CAs) can be allowing unmanaged devices on sites in a label, which requires you to configure dependent conditional access policy for SharePoint as documented here and here
Do be advised that, depending on your configuration and other device management policies (like MDM or Intune) can also affect content access, especially when referring to 3rd party apps. Examples of this include EXO having the ability to allow encrypted content on a mobile 3rd party app (via cmd-let Set-ActiveSyncOrganizationSettings -AllowRMSSupportForUnenlightenedApps $true) but, if you have MDM or Intune, these will take precedence and will prevent content access by the 3rd party app.
Again, remember that actions and all the data we’ve seen is again stored on file / container via metadata. Although these are received by the clients, there are other policies external to the label settings that can be taking precedence.
All these configurations and settings are what allows an admin to customize the service for an organization.
Geez... That was something, and we still are far from finished. We can still talk about clients, auto-labeling (service and client side), email transport, network traces, hybrid environments, authentication contexts, locale and language, a bit of DLP, among others like the Scanner or vault keys. Due to time and complexity, we might not be able to take a deep look into all but as you can see, we still have a lot to go. Join us for the second part of this series in a couple of weeks.
Stay tuned!
Manuel Pereira
Exchange Online Support Escalation Engineer / Tech Lead
Microsoft
