Primer: Finding Sensitivity Labels with PowerShell

Bridging the Knowledge Gap

I’ve written several articles about how to use Graph-based APIs to interact with sensitivity labels, such as how to apply sensitivity labels to SharePoint Online files (using the Graph API or Microsoft Graph PowerShell SDK) or how to read details of sensitivity labels assigned to files.

However, I’ve never discussed the basics how to go about retrieving details of the sensitivity labels defined in a Microsoft 365 tenant, or how to find the identifier of a sensitivity label that’s needed to interact with sensitivity labels. Let’s address that deficiency here, especially in the light of the recent change to introduce a new method of sensitivity label grouping.

Three Different Methods for PowerShell to Fetch Sensitivity Labels

Three methods are available to find what sensitivity labels are available together with their properties such as identifier, name, and priority order. The priority order is a number to indicate the relative sensitivity of a sensitivity label where zero is the lowest level of sensitivity. Priority order is also the default sort order to display labels in the Purview compliance center (Figure 1).

The Get-Label cmdlet from the compliance section of the Exchange Online management module is the oldest method. The Get-Label cmdlet is used to fetch details about labels and their properties (such as this example of generating a report about sensitivity label settings). Here’s how to use the cmdlet to create an array of label identifiers and names:

Connect-ExchangeOnline
Connect-IPPSSession -EnableSearchOnlySession

[array]$Labels = Get-Label | Select-Object ImmutableId, DisplayName

The other two cmdlets are from the Microsoft Graph PowerShell SDK and have different purposes. The cmdlets also read from different sources. The Get-MgBetaUserSecurityInformationProtectionSensitivityLabel cmdlet fetches details of labels published (made available) to the signed-in account.

Connect-MgGraph -NoWelcome

[array]$UserLabels = Get-MgBetaUserSecurityInformationProtectionSensitivityLabel -All -UserId (Get-MgContext).Account | Select-Object Id, Name

Depending on the sensitivity label publishing policies used in a tenant, user accounts can have access to different sets of labels. Running this cmdlet only requires a signed-in account and is equivalent to a user fetching sensitivity labels within an Office application before applying a sensitivity label to a file.

The Get-MgSecurityDataSecurityAndGovernanceSensitivityLabel cmdlet is an administrative cmdlet which requires the SensitivityLabel.Read permission. The cmdlet fetches label information from the Purview label definition store, a central catalog for label data. The signed in account doesn’t need to hold any administrative role to use this cmdlet:

Connect-MgGraph -NoWelcome -Scopes SensitivityLabel.Read

[array]$TenantLabels = Get-MgSecurityDataSecurityAndGovernanceSensitivityLabel -All | Select-Object Id, Name

Expanding Label Groups

In many cases, scripts need to create an array or hash table holding details of sensitivity labels. Neither Graph-based cmdlet expands child labels of sensitivity label groups when it returns a set of labels, so some post-processing is required to find the full set of available labels. The Get-Label cmdlet always returns the full set.

This code creates an array holding the set of labels published to the signed-in user and checks each label to discover if the label has a parent label identifier (indicating that the label is a child of another label). If a parent label identifier exists in the Parent.Id property, the code updates the label array with details of the parent label. At the end, the code sorts the array to eliminate any duplicates:

[array]$UserLabels = Get-MgBetaUserSecurityInformationProtectionSensitivityLabel -All -UserId (Get-MgContext).Account

ForEach ($Label in $UserLabels) {
    If ($Label.Parent.Id) {
        $UserLabels += $Label.Parent
    }  
}
$UserLabels = $UserLabels | Sort-Object Name -Unique

Much the same approach is taken to build the complete set of labels from the tenant label catalog. The difference is that the Sublabels property of a label holds details of child labels, so that’s the property checked and used to build out the complete set of labels:

[array]$TenantLabels = Get-MgSecurityDataSecurityAndGovernanceSensitivityLabel -All

ForEach ($Label in $TenantLabels) {
    If ($Label.Sublabels) {
        $TenantLabels += $Label.Sublabels
    }  
} 
$TenantLabels = $TenantLabels | Sort-Object Id -Unique

Because applications seldom function within the context of a single user, applications should use the Get-MgSecurityDataSecurityAndGovernanceSensitivityLabel cmdlet to fetch label details.

Another point to note is that the Get-MgSecurityDataSecurityAndGovernanceSensitivityLabel outputs the priority order in the Priority property. The Get-MgBetaUserSecurityInformationProtectionSensitivityLabel outputs the information in the Sensitivity property.

More to Do

Populating a list of sensitivity labels to use in a script is only the start. For instance, you might want to reduce the set by selecting only container management labels to use when assigning labels to teams, sites, and groups. Or you might want to do the reverse and find the sensitivity labels created to protect files and emails. All possible with a little filtering, which is a topic for another article.

---

Need help to write and manage PowerShell scripts for Microsoft 365, including Azure Automation runbooks? Get a copy of the Automating Microsoft 365 with PowerShell eBook, available standalone or as part of the Office 365 for IT Pros eBook bundle.