Applying 'Least Privilege' permissions to SharePoint integration

Views:

Summary

This article explains how you can apply “Least Privilege principles” to the components that Mercury requires when communicating with SharePoint for document management. The target audience for this article is your IT team who has the appropriate Microsoft tenant level permissions.

Requirements

1 - Access to a user account with Global Administrator role.

2 - Microsoft Graph Explorer: https://developer.microsoft.com/en-us/graph/graph-explorer.

Method

Enterprise Application Permissions

Navigate to the “MercuryIntegration” Enterprise Application within Entra ID in your organisational Tenancy.

1 - Select Security > Permissions on the left-hand menu.

2 - Select Grant admin consent for [customer tenancy name] button.

This will now pull through the updated permissions from the Application Registration in the Mercury Tenancy.

As of v35, Mercury is starting to transition permissions from the Office 365 SharePoint Online API to the Microsoft Graph API to both improve performance and to align with deprecations within the Microsoft technology stack. As such, both “Microsoft Graph” and “Office 365 SharePoint Online” API’s are required to be their permissions configured appropriately.

Looking at both “Microsoft Graph” and “Office 365 SharePoint Online”, the claim value of Sites.Selected should be visible in the Admin consent permissions table:

Setting SharePoint permissions

To allow the Sites.Selected permissions to take effect within SharePoint, access needs to be granted specifically on the site that requires access. This is a twofold exercise - firstly finding the site ID and secondly applying these permissions via the MS Graph API.

Finding SharePoint Site ID

Logon to the Microsoft Graph Explorer with appropriate permissions to enumerate all sites.

Perform the following query:

GET: https://graph.microsoft.com/v1.0/sites?search=*

This will return all sites in the Response Preview. Alternatively, if you know the name of the SharePoint Site where Mercury documents are stored, replace the final * with this name.

In the response preview, find the site that is used by the Mercury application to store documents and locate the ID field.

Take note of the second item in the ID field. This is the Site ID.

Applying Permissions via the MS Graph API

Logon to the Microsoft Graph Explorer with appropriate permissions to administer sites.

Perform a new query, entering in the site ID (from the above section) in the URL.

POST: https://graph.microsoft.com/v1.0/sites/[replace-with-site-id]/permissions

Edit and paste the following into the Request body:

{
  "roles": ["manage"],
"grantedToIdentities": [{
  "application": {
  "id": "[replace-with-id-of-enterprise-application]",
                        "displayName": "MercuryIntegration"
}
}]
}

Note: Within the roles section, this must be "manage" for the Mercury Integration to work for when uploading documents from within the Client and Candidate Portals.

Select “Run Query”.

If successful, you will receive a 201 Created response code and a permission object in the response body.

Repeat these steps for any additional sites that require least privilege permissions.

Revoking existing permissions

Now that the sites within SharePoint are configured for restrictive permissions, we can now revoke the other permissions for the “Microsoft Graph” and “Office 365 SharePoint Online” API’s.

Navigate to the “MercuryIntegration” Enterprise Application within Entra ID in your organisational Tenancy.

1 - Select Security > Permissions on the left-hand menu.

2 - Navigate to Sites.Manage.All and Sites.ReadWrite.All within the Microsoft Graph API and select ... > Revoke Permission.

3 - Repeat with Office 365 SharePoint Online API.

Note: These permissions will be replaced should anyone press the “Grant admin consent for [customer]” on the Enterprise Application, as it will pull through all permissions from the Mercury Application Registration again. If so, the revoke permission process as above must be repeated.

Deleting Permissions via the MS Graph Explorer API

Should the permissions for the SharePoint site(s) be no longer required, they can be removed with the following steps within the Microsoft Graph Explorer:

1 - Get the Permissions ID:

GET: https://graph.microsoft.com/v1.0/sites/[replace-with-site-id]/permissions

The ID is listed in the Response preview window:

2 - Remove the permissions by the following query:

DELETE: https://graph.microsoft.com/v1.0/sites/[replace-with-site-id]/permissions/[the-permissions-id-returned-from-above-step]

If successful, this method returns 204 No Content response code. It doesn't return anything in the response body.