How to apply Office 365 labels

Jul 23, 2019 | Blog | 0 comments

One way of classifying documents in SharePoint is by associating them with labels. Labels help us retain, delete or not delete/edit documents in Office 365. We can have Office 365 labels for say:

  • Documents that need to be retained for a certain amount of time e.g. lessons learnt document for a project
  • Documents that cannot be edited or deleted e.g. evidence documents in a law firm
  • Documents that need to be permanently deleted from the system after a certain amount of time
  • Documents that have sensitive information and need to be marked appropriately e.g. research material

When a label is created, we associate that with a retention policy or a sensitivity policy. Retention policies help us to retain, delete and mark a document as a record. Sensitivity policies help us encrypt, mark content or help us with data loss prevention/data leaks.

More information on creating labels and policies can be found in these articles:

In this blog post we concentrate on how to apply labels to documents in SharePoint using REST API and CSOM. We covert 2 scenarios:

Applying label to a single document using REST API using Postman

Using CSOM, enabling the document setting that will apply a label to all the documents within it.

Using REST API and Postman to apply label

We first start by creating an app registration and then use the credentials of that app registration to get the access token. Once we get the access token, we use that in the HTTP request to get the required data.

SharePoint App Registration

To register an app in SharePoint, navigate to the “New App Registration” page. The URL of that page will be similar to:

https://yourtenantname.sharepoint.com/_layouts/15/appregnew.aspx

Fill the details in that page as per the following table and click “Create”.

FieldValue
Client IdClick on generate
Client SecretClick on generate
TitleAny value
App Domainlocalhost
Redirect URIhttps://localhost

 

Copy the generated Client Id and Client Secret into notepad (or any of your favorite editor) as we will need these later.

Now that the app is registered, we need to provide the app with some permissions so that it can access data. In order to do that, navigate to the “appinv.aspx” page (with which you can grant permissions to an app). The URL of that page will be similar to the one below

https://yourtenantname.sharepoint.com/sites/ModernTeamSite/_layouts/15/appinv.aspx

In that page, paste the Client Id in the “App Id” text box and click on “Lookup”. This will load the details of the app we registered previously:

SharePoint App Registration

In the “Permission Request XML” paste the following XML. This XML says that the app can have full control over the current web (which is all I need for this case). If you need to give different permissions then please take a look at this article by Microsoft.

< apppermissionrequests allowapponlypolicy="true">  
< apppermissionrequest scope="http://sharepoint/content/sitecollection/web" right="FullControl">

Once that is added click on “Create”. In the next screen click on “Trust It” and this will mean that the app will have the required permissions.

SharePoint App Registration Permissions

That completes the SharePoint related bits. Now to Postman.

Postman

Please follow the instructions this post to create a Postman environment.

In that environment lets add the following variables:

VariableInitial value
appReg_clientIdClient Id of the app created earlier
appReg_clientSecretClient secret of the app created earlier
targetHostYourtenantname.sharepoint.com
principal00000003-0000-0ff1-ce00-000000000000
realmSame as the Azure Active directory Id

For more information on “Principal” please follow this article.

Create a Postman Environment

Access Token Request

After the variables are set up, it’s time to send a POST request to get the token. Create a new request in Postman, name it as “Get Access Token” and change it’s request type to “POST”.

The URL will be:

https://accounts.accesscontrol.windows.net/{{realm}}/tokens/OAuth/2

{{realm}} is an environment variable. So, when we send the request, {{realm}} will be replaced with the value we specified earlier.

Click on the “Body” tab of the request and add the following Key Value pairs.

Access Token Request

Now click on “Tests” tab in the request and add the following javascript.

var json = JSON.parse(responseBody);
postman.setEnvironmentVariable("appReg_bearerToken", json.access_token);

This code runs after the request is made. It extracts the “access token” from the response, creates an environment variable called “appReg_bearerToken” and assigns its value to the retrieved access token.

Access Token Request

The request is now composed, save it and click on “Send”. This will provide the json response which has access token in it.

JSON Response with Access Token

This should have created a variable called “appReg_bearerToken” in the environment and assigned the value of it to the retrieved token. You can verify that by looking at the environment variables.

Applying the Office 365 label

We are now ready to apply a label to a document. To do that create a new POST request in Postman with the name “Apply Label”. The URL of that request will be similar to:

https://yourtenantname.sharepoint.com/_api/web/lists/getbytitle('ListTitle')/items(‘item-id’)
/ SetComplianceTag

Where “item-id” is the id of the document.

To specify the access token for the request, click on the “Headers” tab and add the following:

KeyValue
AuthorizationBearer {{appReg_bearerToken}}
Acceptapplication/json;odata=verbose
Content-Typeapplication/json;odata=verbose

 

Access Token Request

Click on the “Body” tab and add the following JSON

{"complianceTag":"Label Name"}

Where “Label Name” is the name of the label you want to associate the document with.

The request is now composed. Save it and click send. This will apply the required label to the document and the associated policy will be applied.

Note: Although we are using Postman here for sending requests, the same can be done using HttpClient in C#, which can then be used in say an Azure function for applying labels. Here is a console application on similar lines.

Using CSOM to update the document library setting

Once a label is added in Office 365, the libraries in SharePoint will have a setting named “Apply label to items in the list or library”. Clicking on that allows the site owner to apply required label to all the items in that list/library.

However, if we want this to happen automatically while provisioning or say want to change this setting for a multiple number of lists/libraries we can use CSOM.

The method that we use is “SetListComplianceTagWithMetaInfo

static void UpdateListSettings()
     {
            string siteUrl = "https://yourtenant.sharepoint.com/sites/yoursite ";
            string userName = "yourname@yourtenant.onmicrosoft.com";
            string password = "password";

            using (ClientContext ctx = new ClientContext(siteUrl))
            {
                SecureString securePassword = new SecureString();
                foreach (char c in password.ToCharArray()) securePassword.AppendChar(c);

                ctx.Credentials = new SharePointOnlineCredentials(userName, securePassword);

                Microsoft.SharePoint.Client.CompliancePolicy.SPPolicyStoreProxy
.SetListComplianceTagWithMetaInfo(ctx, "/sites/yoursite/ doclibname", 
"Label name", false, false, DateTime.Now, userName, false);

                ctx.ExecuteQueryRetry();
            }
        }

The above method will apply the label to all the documents that will be created within it.

Are Office 365 labels actually useful?

Office 365 labels are very helpful in classifying the documents based on retention and sensitivity. We have seen how to apply labels to documents via REST API and CSOM. These methods can be used while provisioning or post provisioning.

RELATED POSTS:

Cloud Migration Checklist

Are you prepared to migrate? Cloud migration can offer a faster, more reliable and scalable environment than traditional on-premises infrastructure. In fact, by 2025, Gartner predicts that 80% of enterprises will migrate entirely away from on-premises data centres....

read more

Pen Testing: Everything Your Business Needs To Know

Businesses of all sizes, in any industry, can benefit from taking a proactive approach to cyber security - and strengthening their defences against hackers and threats - with a Pen Test. But what is a Pen Test? Pen Testing, also known as Penetration Testing or ethical...

read more

Microsoft Ignite – Day 5: Latest and Greatest

My debut Ignite experience has been awesome! The scale of and breadth of what Microsoft is delivering is very exciting. The announcements in the security and compliance aspects of SharePoint and OneDrive are of high importance to Content and Code and our clients....

read more