Using PowerShell to Generate a Report About Sensitivity Label Settings

Documenting the Many Settings of Sensitivity Labels

After an organization starts to use sensitivity labels, the task of documenting the settings of each label begins. Microsoft has steadily enhanced the capabilities of sensitivity labels to accommodate the needs of information protection (like adding support for meetings) and container management (like controlling sharing permissions for SharePoint Online sites or their use by Teams meeting templates). Improvements have also happened to basic label operations, like adding color to highlight the function of labels. The point is that sensitivity labels have many settings today, with more to come in the future.

The Microsoft Purview compliance center list sensitivity labels in its Information protection section but it doesn’t include an option to export details of the labels and their settings. However, the Get-Label cmdlet is available and reveals all that’s needed to build a report.

Apart from being a more accessible way to review label settings and detect possible inconsistencies, a report is also a good way to backup label settings should someone make an error when updating a label in the future. If this happens, you can consult the last report to see where the problem lies and adjust back to the last known good value. With all that in mind, let’s discuss how to create a report.

Retrieving Sensitivity Label Settings

The Get-Label cmdlet returns sensitivity label settings in a property called LabelActions. The information is in JSON format that converts to an array for easier manipulation with PowerShell. Here’s what our array looks like:

$LabelActions = (Get-Label -Identity $Label.ImmutableId).LabelActions | Convertfrom-JSON
$LabelActions

Type                SubType Settings
----                ------- --------
applycontentmarking header  {@{Key=disabled; Value=true}}
applycontentmarking footer  {@{Key=disabled; Value=false}, @{Key=fontsize; Value=8}, @{Key=text; Value=Sensitivity: ...
applywatermarking           {@{Key=disabled; Value=true}}
encrypt                     {@{Key=disabled; Value=false}, @{Key=protectiontype; Value=template}, @{Key=aiptemplates...
endpoint                    {@{Key=disabled; Value=true}}
protectgroup                {@{Key=privacy; Value=unspecified}, @{Key=allowemailfromguestusers; Value=false}, @{Key=...
protectsite                 {@{Key=allowfullaccess; Value=false}, @{Key=allowlimitedaccess; Value=true}, @{Key=block...
protectteams                {@{Key=disabled; Value=false}, @{Key=islobbyrestrictionenforced; Value=true}, @{Key=ispr...

As you can see, the array divides into a set of sections (types), each of which contains a hash table holding the relevant settings for that section. For instance, the encrypt section holds information about the rights management protection that’s invoked when someone applies the label to a message or file, while the protectsite section holds the container management settings for SharePoint Online sites. You can better see the settings in a section by selecting the section and expanding the settings. Because the information is in a hash table, it is structured as a set of keys and values:

$LabelActions | Where-Object {$_.Type -eq "encrypt"} | Select-Object -ExpandProperty Settings

Key                               Value
---                               -----
disabled                          false
protectiontype                    template
aiptemplatescopes                 ["All"]
templateid                        2707d5c0-a112-45e3-9925-522a34bee048
templatearchived                  False
linkedtemplateid                  2707d5c0-a112-45e3-9925-522a34bee048
contentexpiredondateindaysornever Never
offlineaccessdays                 -1
rightsdefinitions                 [{"Identity":"office365itpros.onmicrosoft.com","Rights":"VIEW,VIEWRIGHTSDATA,OBJ...

Interpreting Rights

Now that we know how to retrieve sensitivity label settings, we can consider how to report what we find. The easy approach is to create a simple listing of settings, but I decided that I wanted to extract more value from the report. This brought me to considering the rights assigned in sensitivity labels.

Sensitivity labels that encrypt (protect) content can use preassigned rights or user-defined permissions. Preassigned rights means that the label contains a set of identities and the rights assigned to those identities. User-defined permissions mean that users assign rights at the time when they protect a document or message.

The valid types of preassigned identities are:

• Individual users identified by their primary SMTP address.
• Groups. The assignment uses the group’s primary SMTP address. Any member of the group can receive the assigned rights.
• Any user or group in the host organization.
• Any authenticated user. Anyone who can authenticate against Azure AD or has a Microsoft Services Account can open an Office document protected with the label. People who use a federated social provider or can use a one-time password can access emails protected with the label, but they cannot authenticate to access protected documents.
• Anyone in a domain.

Sensitivity labels pair identities with a set of rights which dictate what the assignee can do with the protected content. For convenience, labels bundle sets of rights into roles like Co-Author and Reader. When you assign rights to assignees in a label, you usually assign a role. However, you can also assign a custom set of rights to satisfy specific requirements. Here’s what the set of rights assigned by a sensitivity label looks like. The rights assigned to authenticated users and anyone with a Microsoft.com email address equate to the Viewer role. The rights assigned to anyone in Office365itpros.com equate to the Reviewer role. Although the assignment is to the service domain in this case, you can use either it or the default domain to identify members of the host organization.

Identity                          Rights
--------                          ------
AuthenticatedUsers                VIEW,VIEWRIGHTSDATA,OBJMODEL
microsoft.com                     VIEW,VIEWRIGHTSDATA,OBJMODEL
office365itpros.onmicrosoft.com VIEW,VIEWRIGHTSDATA,OBJMODEL,DOCEDIT,EDIT,REPLY,REPLYALL,FORWARD

The thing that nobody says anything about is that rights stay assigned in labels unless administrators take the time to validate the set of rights to remove unnecessary rights or tweak the set of rights assigned to assignees. For instance, if an individual user receives rights and then leaves the company so that their email address is no longer in use, Purview doesn’t periodically check email addresses to make sure that they are still valid, and it’s possible that labels assign rights to complete domains that are no longer necessary.

It’s understandable why this situation exists. If you remove an identity from a sensitivity label, those who depend on the assigned rights lose access to content protected by the label. Customers would complain bitterly if Microsoft removed identities that it considered invalid and caused people to lose access to important documents. It’s therefore best to leave the responsibility for rights maintenance to the tenant that owns the sensitivity labels.

However, that doesn’t mean that a report can’t examine the rights assigned in sensitivity labels to flag those that administrators should consider checking, which is exactly what happens in my script. Figure 1 shows an example of sensitivity label properties shown in the HTML report generated by the script. The report highlights a right assigned to an individual email address because the address is no longer valid. Similarly, if the script finds a right assigned to a consumer email domain like outlook.com or gmail.com, it flags that for checking because allowing rights to massive email domains is not a good way to protect information.

Validating Rights

The code to validate rights isn’t very complex:

• It’s impossible to check Any authenticated users, so that identity passes without further comment.
• If the email address for an individual user or group assigned a right belongs to a domain owned by the host tenant, the script runs the Get-ExoRecipient cmdlet to see if the address can find an email recipient. If it can’t, the script issues a warning. It also warns for external email addresses to highlight the address for checking by an administrator.
• If a domain receives rights, the script uses the technique explained here to validate if the domain uses Azure AD (it’s a managed domain). If not, or if the domain is a consumer domain, the script flags the domain for follow-up. For some strange reason, the code considers Microsoft.com to not be a managed domain.

At the end of the script, it generates a HTML report and CSV file. If any warnings are noted, it reports them in summary:

You should check these warnings flagged for rights assignments

Label    : Intellectual Property
Applies  : File, Email
Priority : 12
Value    : flayoscperson@outlook.com rights: VIEW,VIEWRIGHTSDATA,DOCEDIT,EDIT,REPLY,REPLYALL,FORWARD,OBJMODEL (Warning:
           Rights assigned to unverified holder)
           IPManagement.Team@office365itpros.com rights: VIEW,VIEWRIGHTSDATA,DOCEDIT,EDIT,REPLY,REPLYALL,FORWARD,OBJMODEL
           outlook.com rights: VIEW,VIEWRIGHTSDATA,OBJMODEL (Warning: consumer domain)
           office365itpros.com rights: VIEW,VIEWRIGHTSDATA,REPLY,REPLYALL,OBJMODEL
           tredmond99@yandex.com rights: VIEW,VIEWRIGHTSDATA,OBJMODEL (Warning: Rights assigned to unverified holder)
           vasil@michev.info rights: VIEW,VIEWRIGHTSDATA,DOCEDIT,EDIT,REPLY,REPLYALL,FORWARD,OBJMODEL (Warning: Rights
           assigned to unverified holder)

You can download the full script from GitHub.

Maintain the Rights Assigned in Sensitivity Labels

When I set out to write the script, I thought that the set of sensitivity labels defined in my tenant were in good shape. But the effects of testing different scenarios over the last five or so years meant that some labels weren’t well configured. At least, I could make improvements. And when it came to rights assignments, I found plenty of gaps that I’ve now fixed. This exercise proves that reviewing Microsoft 365 objects occasionally is good practice and shows just how useful PowerShell is at extracting and presenting information in a useful format.