Utilize the Microsoft Purview APIs to automate your compliance

Automating your compliance process can dramatically improve the speed and overall quality of your process. For example, automatically triggering retention events helps you comply with regulatory requirements by disposing data after the legal retention periods.

Microsoft Graph was a good starting point for utilizing the Microsoft Purview APIs, however when working with retention labels you still needed to revert to the SharePoint CSOM APIs as Microsoft Graph didn’t support this feature yet.

But guess what just hit General Availability? Yes, indeed: Microsoft Purview APIs for managing retention labels! Making Microsoft Purview APIs now feature parity with its predecessors.

Read on to learn more about how to unleash full power!

Managing compliance can be a daunting task, let alone the fact that manual labor can also make this error prone, leaving you at legal risk. Tools like Microsoft Purview are here to make your life easier, especially with this new set of APIs.

In this blog I’m going to talk you through the steps necessary to utilize the new Microsoft Purview APIs, provided by Microsoft Graph. Because I’m a fan of the ability to scan through (lengthy) documents, I’ve added a Table of Contents. Feel free to use it to your convenience.

Prerequisites

While writing this blog I consider the following to be in place

• The use case of automating retention labels is clear to you
• You have already set up retention in Microsoft Purview Compliance (especially labels)
• You are a Global Administrator of the Azure tenant were you’re performing these actions
• All licenses are sorted on the Azure tenant to make use of Microsoft Purview
• You know and understand concepts of API’s, specifically Microsoft Graph and preferably on working with Sites and Drive Items
• You are familiar with the Azure Portal, specifically Azure Active Directory
• Infrastructural configuration allows execution of the steps described

Create App Registration

First we need to create an App Registration. This will be used for requesting a token to be able to authenticate to the Microsoft Purview API.

• In the Azure Portal, go to ‘App Registrations’
• Click ‘New’ in the menu bar to create a new App Registration
• Provide a name for the new App Registration, e.g. “Microsoft Purview API”
• Set the ‘Redirect URI’ to “Web” and add “https://localhost”
• Now click ‘Register’ to create your App Registration

When your app is created you are redirected to it’s blade. Make sure to store the following information on the same secure location as we did previously:

• Application (client) ID
• Directory (tenant) ID

Assign API Permissions

The App Registration will need permissions before it can successfully call the Microsoft Purview API. The steps below describe how to add the permissions.

A quick note
In this example we’re going to update the retention label of an asset in SharePoint using an app. Therefore we’re adding the ‘app permissions’ with ‘.ReadWrite.All’ scope. When you only want to retrieve labels, adding ‘.Read.All’ is enough. Alternatively, you could also choose to work with ‘delegated permissions’ depending on your scenario, but keep in mind the flow will be slightly different from this example.

• Select ‘API permissions’ in the side menu of the App Registration’s blade
• Click ‘+ Add a permission’ and select ‘Microsoft Graph’

• Next, choose ‘Application permissions’ and search for “files”
• Check the box next to ‘Sites.ReadWrite.All’

• Now directly search for “files”
• Check the box next to ‘Files.ReadWrite.All’

• Click ‘Add permissions’ to assign these permissions to your App Registration

Grant Admin Consent

When you’ve added the permissions they don’t automatically become active. You first need to provide consent. This can be done through the user, however in this example we’re providing consent as Global Administrator.

Types of consent
The difference between providing User Consent or Admin Consent is that, with providing User Consent you make the API permissions available for that user only. When granting Admin Consent you allow all users in the tenant to connect through this App Registration. It is a choice whether you want every user to provide consent separately, or once for the entire tenant. Please note that these permissions in itself do not provide access to the Microsoft Purview API, thus providing Admin Consent does not directly enable your entire tenant to send authenticated requests.

• After adding the API permissions , click ‘√ Grant admin consent for {tenantName}‘
• Click ‘Yes’ to grant Admin Consent

When Admin Consent is provided correctly you see the status showing a green checkmark:

Create Secret

Now we’ve got the API permission set we’re at the last step of setting up the App Registration: create a secret. This is used for authenticating the App Registration to the Microsoft Purview API.

• Select ‘Certificates & secrets’ in the side menu of the App Registration’s blade
• Click ‘+ New client secret’ on the ‘Client secrets (0)’ tab
• Provide a description for your key (this is for future reference)
• Select an expiration time (after this time you need to create a new key)
• Now click ‘Add’ to generate a new secret

The newly created client secret will show. Copy it to the same secure location where we stored our information in earlier steps. We can almost put it to use!

Don’t hit refresh!
Make sure to copy the client secret directly after it is created. When you leave the page the key won’t show anymore, and there is no way to retrieve it anymore!

Test API in Postman

Now we’ve got our App Registration set up, and provided the permission, it is time to test the Microsoft Purview API. This is a two-step process:

1. Request Access Token
2. Use Access Token to make an authenticated request to the Microsoft Purview API

The following paragraphs provide details on each of these steps.

Get Access Token

First step is retrieving an Access Token. This will be used in the next step for authenticating the request to the Microsoft Purview API.

• Create a new request in Postman
• Set the method to ‘Post’
• Enter the following request URL (change {tenantId} with the Directory (tenant) ID we securely stored earlier):

https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token

• Set the ‘Body’ to “x-www-form-urlencoded” and fill the details below using the details we stored securely along the way of this guide:

Key	Value
client_id	Application (client) ID
client_secret	Secret of the App Registration
grant_type	client_credentials
scope	https://graph.microsoft.com/.default

• Hit ‘Send’ to fire the request
• If everything went correctly you should see a body like below
• Copy the contents of the “access_token” attribute

Call Microsoft Purview API

Next step is to actually call the Microsoft Purview API. For this we need the “access_token” from the previous step to authenticate the request.

• Create another request in Postman
• Go the the ‘Authorization’ tab
• Set ‘Type’ to ‘Bearer token’ and paste the “access_token” in the ‘Token’ field

• Now go to the ‘Body tab
• Set the method to ‘Post’
• Fill in the following request URL (while replacing {DriveId} and {ItemId} respectively with the ID’s corresponding to the drive and drive item on your SharePoint site):

https://graph.microsoft.com/v1.0/drives/{DriveId}/items/{ItemId}/retentionLabel

• Set the body to ‘raw’ and set the type to ‘JSON’
• Use the following sample body, and set the values as desired
  • Change {labelName} to the retention label set in Microsoft Purview, and published to the site you’re working on

{
  "name": "{labelName}"
}

• Now hit ‘Send’ to execute the request
• You should see a ‘200 OK’ when the retention label is successfully applied

Considerations

While writing this guide, providing the examples, I noted some considerations you might want to take into account:

• You might prefer Delegated Permissions instead of App Permissions in your scenario, like for example when you’re developing an App with user interaction that utilizes the Microsoft Purview API.
• When talking security, you should make sure security is set properly for this API not to be abused (as it can have big consequences)

Next Steps

Now we’ve got the basics of the Microsoft Purview API in place it’s time to build a process around it for the automation to work. It depends on your use case what that process looks like but could for example be triggered when a file is updated to check whether the retention label is still correct and update it accordingly.
Another next step could be that, with the retention labels set, you want to trigger a retention event. Read my previous blog with all the details on how to automate that as well.

Please feel free to discuss with me on this topic through the comments below. Off course, you can also get in touch and leave me a message. Looking forward!