Decrypting SharePoint Online Documents with PowerShell

Great to Protect Content Until Access is Needed

The growing popularity of sensitivity labels is goodness if you simply look at the desirability of protecting confidential information. However, the presence of a larger percentage of encrypted data within Office 365 creates some addition management challenges. As I have noted during several conference talks, the only downside of encryption is encryption.

For example, if you run a content search to find information needed for an investigation, the search can return protected documents because SharePoint Online can decrypt and index their content. But when the time comes to export the documents found by the search, SharePoint delivers encrypted content which can only be opened by people who have the necessary rights. This creates a problem for investigations. A recent update to Exchange Online means that protected attachments are decrypted for content search exports. The same functionality is needed for protected files found in SharePoint Online and OneDrive for Business document libraries.

More fundamentally, if an organization decides on a “cloud exit” and needs to move all its information out of Office 365 to bring them to another platform, the presence of encrypted content creates some processing headaches, especially if large numbers of documents are protected using auto-label policies. The same issue exists when moving content during tenant-to-tenant migrations.

Unlocking Protected Files in SharePoint Online

To ease the situation, Microsoft has introduced the Unlock-SPOSensitivityLabelEncryptedFile cmdlet in version 16.0.20616.12000 and above of the SharePoint Online PowerShell module. Global and SharePoint admins can run this cmdlet to remove sensitivity labels with encryption from documents stored in SharePoint Online document libraries. The cmdlet only works against documents protected by labels owned by the tenant. In effect, this is the same functionality available to rights management super-users when they use the Set-AipFileLabel cmdlet to remove labels from files stored in folders in local drives and file shares. For example:

Set-AipFileLabel "C:\Temp\Important Stuff.docx" -RemoveLabel -JustificationMessage "Label no longer necessary"

The input parameters to the Unlock-SPOSensitivityLabelEncryptedFile cmdlet are the full URL for the file and a justification for the removal of the label. For instance:

Unlock-SPOSensitivityLabelEncryptedFile -Justification "Needed to remove label"
-FileUrl https://office365itpros.sharepoint.com/sites/billing/Shared Documents/Invoice Tracking 2020.xlsx

Decrypting All the Files in a Folder

While being able to decrypt one file is good, being able to decrypt a set of files is even better. In this example, we use cmdlets from the SharePoint PnP module to connect to a target site and retrieve a list of items in a folder. The SharePoint Online module deals with administrative operations against sites and other SharePoint objects. To unlock documents, we need to know what files exist in a folder in a document library, and that’s why we use the PnP module, which can be downloaded from the PowerShell gallery.

In this example, the code defines some variables to identify the site and folder where the files are stored. After connecting to the site, we create a list of files in the target folder and a loop processes each item to remove a sensitivity label with encryption (if one exists).

$SiteURL = "https://office365itpros.sharepoint.com/sites/corporatebilling"
$FolderURL= "/Shared Documents/2020"
Connect-PnPOnline -Url $SiteURL -Credentials $O365Cred 

$FolderItems = Get-PnPFolderItem -FolderSiteRelativeUrl $FolderURL -ItemType File
ForEach ($Item in $FolderItems) {
     $ItemPath = $SiteUrl+$FolderUrl+"/"+$Item.Name
     Write-Host "Unlocking" $Item.Name
     Unlock-SPOSensitivityLabelEncryptedFile -FileUrl $ItemPath -JustificationText "Administrator removed label"
}

Currently there’s no way available in PowerShell to select the documents protected by sensitivity labels with encryption (this is possible with the Graph API). No harm is done by running Unlock-SPOSensitivityLabelEncryptedFile against a file which doesn’t have a label or has a label which doesn’t use encryption. When this happens, the cmdlet ignores the file. We can therefore go ahead and process all the files in the folder in the knowledge that only files assigned labels with encryption will be updated.

Auditing Label Removal

When a label is removed by the Unlock-SPOSensitivityLabelEncryptedFile cmdlet, SharePoint updates the name of the last modified user to System Account. If you want to discover the account which ran the cmdlet to remove a sensitivity label, you should query the Office 365 audit log to examine the FileSensitivityLabelRemoved events captured when labels are removed. The justification provided is captured in the audit event.

Some Known Limitations

Some limitations exist. Most sensitivity labels in use today can be removed by the cmdlet, but those that cannot are labels which:

  • Include encryption using permissions assigned by an administrator (in other words, the rights are assigned when the label is created or edited).
  • Do not have user-defined permissions.
  • Do not use Double-key encryption (DKE).

These shouldn’t be significant restrictions for most tenants. Microsoft hasn’t said if they will lift the restrictions in the future.

Good Cmdlet for the Administrator Toolkit

Having a method to remove encryption from SharePoint Online files is a nice step forward and fits nicely into the Office 365 administrator toolkit. Although tenant administrators might not think they will ever need to process documents in this manner, a dollar gets a penny that they will. And perhaps often.