Microsoft Purview Sensitivity Labels
Introduction
Gimmal Discover supports sensitivity labels that can be created in Microsoft’s Purview Information Protection area. Sensitivity labels allow organizations to classify and protect their information. Labels may be applied to file content and are visible to end users from within Microsoft Office applications. See sensitivity labels, a Microsoft link that provides more details.
Discover extends the reach of Purview sensitivity labels by allowing file-based content outside of the Microsoft 365 environment to be labeled. The Discover File Agent can label content on network file shares and Microsoft Windows endpoints. In addition, Discover’s data governance workflows can interrogate a label and, based on that value, implement an action such as moving the file to SharePoint or deleting the file. This document details how to configure Discover to support Purview sensitivity labels.
Configuration
File Agent Credentials
To continue configuration, log into the server where the File Agent service is installed and open the Connector Status application. From there, click the credentials hyperlink and open the tab for File Agent:
![image-20240624-194947.png](../__attachments/357105666/image-20240624-194947.png?inst-v=2a7f6216-cd78-4207-9e5e-2ee0ab03c660)
Supply the Microsoft 365 credentials for Client ID, Tenant ID, location to a certificate file, and the certificate password. Then click the Save button to update the credentials.
Note 1: The Application Name and Application version will be pre-filled and do not need to be changed.
Note 2: Currently, the “Test Login” button is not functional on the File Agent credentials screen. This is a known issue.
File Agent Settings
The sensitivity label feature requires installing version 20240701 (or above) of the Gimmal Discover File Agent.
Note: if your Agent has not automatically updated to the specified version, go to Administration/Configuration/Connectors, select the Connector where the File Agent is installed and under the orange More button select the option to “Update Connector and Agents”
To activate the feature, open the Connector Settings, check the Advanced box at the top of the page, then open the File Agent tab. Scroll to the bottom of the File Agent settings and there will be a new section for Microsoft Purview Settings.
![image-20240624-193613.png](../__attachments/357105666/image-20240624-193613.png?inst-v=2a7f6216-cd78-4207-9e5e-2ee0ab03c660)
Check the box to enable the feature and specify a frequency to download the settings (this determines how often the File Agent will query Purview for any new labels). Then click Update to save those settings.
After completing these steps, either restart the File Agent service or reboot the server where the agent is installed. To verify that the labels were successfully obtained, open the File Agent log and look for this entry:
[00:38:50.3 Jun-24] Get Sensitivity Labels for Tenant sbalajidomain.onmicrosoft.com
At this point, the list of current MIP labels has been obtained from the Microsoft 365 tenant and stored in the Discover database.
Using MIP Labels in Workflows
The Discover workflow editor has been updated to allow the use of MIP labels. Before inserting any MIP label workflow step, you must update the list of labels in the Workflow Editor. After starting the application, select the Session option from the top menu bar then choose the option to “Update Purview Sensitivity Labels”
![Screenshot (289).png](../__attachments/357105666/Screenshot%20(289).png?inst-v=2a7f6216-cd78-4207-9e5e-2ee0ab03c660)
This will cache the list of sensitivity labels from the Discover database and then provide the confirmation message:
![image-20240628-174109.png](../__attachments/357105666/image-20240628-174109.png?inst-v=2a7f6216-cd78-4207-9e5e-2ee0ab03c660)
This step must be performed every time you plan to use sensitivity labels in a workflow.
MIP Label Workflow Steps
The workflow editor supports the following MIP label features
Type | Step | Description |
---|---|---|
Decision | Test Purview sensitivity label | This decision will test the Purview sensitivity label value |
Action | Set Purview sensitivity label | This action will set a Purview sensitivity label |
Action | Remove Purview sensitivity label | This action will remove a Purview sensitivity label |
Token | %msip-sensitivity-label% | Returns the text value of a sensitivity label |
Token | %msip-sensitivity-label-id% | Returns the GUID value of a sensitivity label |
When specifying one of the Action steps, there is an option for Justification Message. When setting a label this message is optional, however it is required when using the action to remove a label.
Appendix
Microsoft Purview permissions
This section details the Entra (Active Directory) permissions that need to be applied in order to support access by Gimmal Discover. To locate these permissions, log into the Microsoft Entra Admin Center and select the option for Applications/App Registrations:
![image-20240624-184219.png](../__attachments/357105666/image-20240624-184219.png?inst-v=2a7f6216-cd78-4207-9e5e-2ee0ab03c660)
Select an existing Gimmal Discover application (or create one if necessary) Then select the option for API permissions.
![image-20240624-184632.png](../__attachments/357105666/image-20240624-184632.png?inst-v=2a7f6216-cd78-4207-9e5e-2ee0ab03c660)
Add the permission detailed in the table below. Remember to use the option to ‘grant admin consent’ to each of the permissions that are added.
Azure Rights Management Services
API/Permissions Name | Type | Description |
Content.DelegatedWriter | Application | Create protected content on behalf of a user |
Content.Writer | Application | Create protected content |
user_impersonation | Delegated | Create and access protected content for users |
Microsoft Graph
API/Permissions Name | Type | Description |
APIConnectors.Read.All | Delegated | Read API connectors for authentication flows |
APIConnectors.Read.All | Application | Read API connectors for authentication flows |
APIConnectors.ReadWrite.All | Delegated | Read and write API connectors for authentication flows |
APIConnectors.ReadWrite.All | Application | Read and write API connectors for authentication flows |
Directory.AccessAsUser.All | Delegated | Access directory as the signed in user |
Directory.Read.All | Delegated | Read directory data |
Directory.ReadWrite.All | Delegated | Read and write directory data |
Delegated | View users' email address | |
Files.Read | Delegated | Read user files |
Files.Read.All | Delegated | Read all files that user can access |
Files.Read.All | Application | Read files in all site collections |
Files.Read.Selected | Delegated | Read files that the user selects (preview) |
Files.ReadWrite | Delegated | Have full access to user files |
Files.ReadWrite.All | Delegated | Have full access to all files user can access |
Files.ReadWrite.All | Application | Read and write files in all site collections |
Files.ReadWrite.AppFolder | Delegated | Have full access to the application's folder (preview) |
Files.ReadWrite.Selected | Delegated | Read and write files that the user selects (preview) |
InformationProtectionPolicy.Read | Delegated | Read user sensitivity labels and label policies. |
InformationProtectionPolicy.Read.All | Application | Read all published labels and label policies for an organization. |
openid | Delegated | Sign users in |
profile | Delegated | View users' basic profile |
RecordsManagement.Read.All | Delegated | Read Records Management configuration, labels, and policies |
RecordsManagement.Read.All | Application | Read Records Management configuration, labels and policies |
RecordsManagement.ReadWrite.All | Delegated | Read and write Records Management configuration, labels, and policies |
RecordsManagement.ReadWrite.All | Application | Read and write Records Management configuration, labels and policies |
User.EnableDisableAccount.All | Delegated | Enable and disable user accounts |
User.EnableDisableAccount.All | Application | Enable and disable user accounts |
User.Export.All | Delegated | Export user's data |
User.Export.All | Application | Export user's data |
User.Invite.All | Delegated | Invite guest users to the organization |
User.Invite.All | Application | Invite guest users to the organization |
User.ManageIdentities.All | Delegated | Manage user identities |
User.ManageIdentities.All | Application | Manage all users' identities |
User.Read | Delegated | Sign in and read user profile |
User.Read.All | Delegated | Read all users' full profiles |
User.Read.All | Application | Read all users' full profiles |
User.ReadBasic.All | Delegated | Read all users' basic profiles |
User.ReadBasic.All | Application | Read all users' basic profiles |
User.ReadWrite | Delegated | Read and write access to user profile |
User.ReadWrite.All | Delegated | Read and write all users' full profiles |
User.ReadWrite.All | Application | Read and write all users' full profiles |
Microsoft Information Protection Sync Service (found in the category API's My Organization Uses)
API/Permissions Name | Type | Description |
UnifiedPolicy.Tenant.Read | Application | Read all unified policies of the tenant |
UnifiedPolicy.User.Read | Delegated | Read all unified policies a user has access to. |