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.

On Demand Migration

Migrate all your workloads and Active Directory with one comprehensive Office 365 tenant-to-tenant migration solution.

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

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":"","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 email address equate to the Viewer role. The rights assigned to anyone in 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
--------                          ------

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 or, it flags that for checking because allowing rights to massive email domains is not a good way to protect information.

HTML report showing sensitivity label settings
Figure 1: HTML report showing sensitivity label settings

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 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
           Rights assigned to unverified holder)
  rights: VIEW,VIEWRIGHTSDATA,OBJMODEL (Warning: consumer domain)
  rights: VIEW,VIEWRIGHTSDATA,OBJMODEL (Warning: Rights assigned to unverified holder)
           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.

Cybersecurity Risk Management for Active Directory

Discover how to prevent and recover from AD attacks through these Cybersecurity Risk Management Solutions.

About the Author

Tony Redmond

Tony Redmond has written thousands of articles about Microsoft technology since 1996. He is the lead author for the Office 365 for IT Pros eBook, the only book covering Office 365 that is updated monthly to keep pace with change in the cloud. Apart from contributing to, Tony also writes at to support the development of the eBook. He has been a Microsoft MVP since 2004.


  1. Nicola

    Thanks a lot Tony.

    We are still in rolling-out phase, this was caused by a change of policy.
    So there are not that many docs, but we need to preserve them.

    Will follow up with the suggested approach.

    Thanks a lot


  2. Nicola

    Hi Tony, thanks for sharing!

    I am confronted with a challenge and I feel I am hitting a wall.
    I have my set of labels published and applied to our files in SPO/OneDrive.
    Let’s say labels A, B, C,D
    For some reasons, I don’t need anymore label B.
    I can unpublish label B.
    How can I make sure that all documents currently labelled with label B are re-labelled to D (ex.)

    Sensitivity label is not a valid condition for Auto Labelling in PurView, and I could not leverage Defender portal either.

    Would you have any hint on this case?

    Thanks in advance


    1. Avatar photo
      Tony Redmond

      There is an API to apply labels to documents, but it’s a paid-for metered API.

      The question is do you need to do anything about the documents with the B label? Can they be left alone until they expire?

      If it is absolutely necessary to track down and change each label from B to D (say), you could use the Report script to find documents labeled with B (see and manually change them to whatever label is necessary. A content search is a great tool to find labeled files and generate a file (export report) showing the locations and individual files.

      How many documents have B? That would be one of the factors driving the decision…

Leave a Reply