How Default Sensitivity Labels Work with SharePoint Online Document Libraries

Preview Feature Expected to be Generally Available Later in 2022

According to a LinkedIn post by Microsoft Principal Program Manager Sanjoyan Mustafi, administrators will soon be able to assign default sensitivity labels to document libraries in SharePoint Online and OneDrive for Business. The capability is in private preview at present, but Microsoft 365 tenants can sign up to join the preview here.

Today, you can require that users add a sensitivity label to documents and define a default label to use. This is done through settings of the sensitivity label publishing policy which makes labels available to users. Requiring documents to be labelled works, but you don’t know what labels users will choose. Sometimes, it might be necessary to ensure that every document in a library receives the same sensitivity label to reflect the level of confidentiality of the library, and that’s where the new capability comes in.

The Backend to Apply Sensitivity Labels

The preview includes the back-end code to define a default label and apply it to new Office documents uploaded or copied to or saved in a library. An asynchronous thread examines new items to check if they already have a sensitivity label. The stamping of the default sensitivity label on new items by the thread can take a few minutes.

If a new item already has a user-applied sensitivity label, the thread ignores the document based on the principle that explicit assignment by users always takes precedence over automatic assignment. If the item has a label of a lower priority (sensitivity labels have a priority order from 0 to n, with 0 being the lowest) received through automatic assignment (usually because a label publishing policy mandates the application of a default label), the thread replaces the label and applies the default label defined for the library.

For now, labeling only happens for new Office documents (support for PDFs will come later). Existing documents remain untouched, and you must apply labels manually if you want all documents to have the same label. However, in the future, Microsoft plans to update the code so that SharePoint will apply labels whenever a user opens an unlabeled document in a library with a default label.

Note that a user can remove the default label assigned for the library or replace it with a label of higher or lower sensitivity. In these cases, the user-assigned label remains, again following the principle of user precedence.

The preview doesn’t come with any UI to configure a document library with a default sensitivity label (SharePoint Online already can add default retention labels to new items). Microsoft will update the SharePoint Online and OneDrive for Business GUI before the feature is generally available.

Configuring for Default Sensitivity Labels

To set things up for default label assignment, you must update the configuration of the target document library using the SharePoint API. You can do this with Postman (the tool favored by Sanjoyan), but I prefer PowerShell, which is what I used. Sanjoyan explains the procedure in his post, but briefly is:

  • Get a bearer token to authenticate with SharePoint Online. You can copy the token if you’re logged into SharePoint Online by using the developer tools (F12).
  • Create a header structure to hold details of the transaction, including the bearer token.
  • Create a body structure to define the GUID of the sensitivity label you want to add as the default for the library. Use Connect-IPPSSession to connect to the Compliance center endpoint and run Get-Label to find the list of labels. The GUID for each label is in the ImmutableId property.
Get-Label | Format-List DisplayName, ImmutableId
  • POST to the URL for the document library using the header and body defined earlier.

The commands I used to update a document library were:

$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("Accept", "application/json;odata=verbose")
$headers.Add("Content-Type", "application/json;odata=verbose")
$headers.Add("X-HTTP-Method", "MERGE")
$headers.Add("If-Match", "*")
$headers.Add("Authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IkRya21Mczl1akhnMkp1SE5CRm5vOERicXBJSSJ9.eyJhdWQiOiIwMDAwMDAwMy0wMDAwLTBmZjEtY2UwMC0wMDAwMDAwMDAwMDBAYjY2MjMxM2YtMTRmYy00M2EyLTlhN2EtZDJlMjdmNGYzNDc4IiwiaXNzIjoiMDAwMDAwMDMtMDAwMC0wZmYxLWNlMDAtMDAwMDAwMDAwMDAwIiwibmJmIjoiMTY0MzMxNTU5MiIsImV4cCI6IjE2NDMzMTkxOTIiLCJ1cG4iOiJ0b255LnJlZG1vbmRAcmVkbW9uZGFzc29jaWF0ZXMub3JnIiwicHVpZCI6IjEwMDNCRkZEODA1Qzg3QjAiLCJjYWNoZWtleSI6IjBoLmZ8bWVtYmVyc2hpcHwxMDAzYmZmZDgwNWM4N2IwQGxpdmUuY29tIiwidmVyIjoiYnJvd3NlciIsInRpZCI6ImI2NjIzMTNmLTE0ZmMtNDNhMi05YTdhLWQyZTI3ZjRmMzQ3OCIsImFwcGlkIjoiYzU4NjM3YmItZTJlMS00MzEyLThhMDAtMDRiNWZmY2QzNDAzIiwiYXBwX2Rpc3BsYXluYW1lIjoiU2hhcmVQb2ludCBPbmxpbmUgQ2xpZW50IEV4dGVuc2liaWxpdHkiLCJzY3AiOiJGaWxlcy5SZWFkV3JpdGUuQWxsIFNpdGVzLk1hbmFnZS5BbGwgU2l0ZXMuRnVsbENvbnRyb2wuQWxsIFRlcm1TdG9yZS5SZWFkV3JpdGUuQWxsIiwiaXBhZGRyIjoiNTEuMTcxLjIxMi4xMjkiLCJzZXNzaW9uaWQiOiIzYzdiMjUzYy0zNmJjLTQ1ZTctYmQ4OS1mNGRhZjdkZjZhNmEiLCJzaWduaW5fc3RhdGUiOiJbXCJrbXNpXCJdIn0.m0VNYiAPfu7GKuTcnAi0hc4ay7TAQ-KzlH1g3hRzRzJZccoLeRepey8k7ydNHsvdhO8N0E4mMEEz3dD8Tk-1qreBzNrqPkB6p2s8hGF1J04RaR6vkyTqJypFXLRXgmSsVrPsX1huNnkwZ0d_ShmPowUToZk_HN0MrDRIEleCks32pg1nQs2Umk63BkWAaUHJy_pLhYJOea0uzSc7iPeVpPaAQ8PbK8K4eRJX__DEByQueUSOd21V9O6KJ9ey-JasryPiqtncFUDGrofQ6EZztjwaCAjQubRv7RjOkMYeucgsgiI7cvfuvuCzcXjc6oqdosZwc-18Uurq_8r8ks9c4A")

$body = "{
`n `"__metadata`": {
`n `"type`": `"SP.List`"
`n },
`n `"DefaultSensitivityLabelForLibrary`": `"27451a5b-5823-4853-bcd4-2204d03ab477`"
`n}
`n"
$Uri = 'https://office365itpros.sharepoint.com/sites/Office365Adoption/_api/web/lists/GetByTitle(''Documents'')'
$Update = Invoke-RestMethod -Method 'Post' -Headers $Headers -Body $Body -Uri $Uri

Formatting of these commands must be precise, and the bearer token must be valid or the update will fail (I know, because I made many mistakes before doing it just right). The easiest way to make sure is to open the site you want to update in a private browser window to force a recent authentication and then copy the token (use F12 in Edge and access Local storage, then copy the value of the key for the identity for SharePoint Online as shown in Figure 1).

Copying a bearer token for SharePoint Online
Figure 1: Copying a bearer token for SharePoint Online

After configuring a default sensitivity label, it’s a good idea to change the default view for the library to include the sensitivity label to remind users that documents now have labels.

Steady Progress

Sensitivity Labels and SharePoint Online had a rocky start. There was a time when the content of protected Office documents was inaccessible to search and eDiscovery. That’s in the past (if you enable support) and Microsoft is busy filling out all the details that make software more useful. Adding a default sensitivity label to document libraries is a nice step forward but remember that using this capability will require Office 365 E5 or above, just like all the other auto-label application features in Microsoft 365.


So much change, all the time. It’s a challenge to stay abreast of all the updates Microsoft makes across Office 365. Subscribe to the Office 365 for IT Pros eBook to receive monthly insights into what happens, why it happens, and what new features and capabilities mean for your tenant.

One Reply to “How Default Sensitivity Labels Work with SharePoint Online Document Libraries”

  1. I can’t for the life of me get the bearer token in Edge. The key never shows. Tried on multiple computers in Edge. Ironically I saw it once and it said it was expired. Then I tried a private browser, cleared cookies etc and never saw it again, and I’m browsing around the SharePoint Online site. The “self” key just isn’t there.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.