Read Grant Path for Sites.Selected
Complete the common setup before continuing here. This runbook covers the remaining steps for the Read site grant path only.
Note: If you are only granting the Crawling Application Read access to the site, the SharePoint connector cannot retrieve file permissions via CSOM alone. This path uses Use Graph API for permissions and the SharePoint Security plugin to manage permissions, and Use Graph API for site discovery for discovering sites.
Azure Portal – Certificates & Secrets (Crawling Application)
A client secret is required on the Crawling Application in addition to the certificate. The certificate covers SharePoint CSOM; the client secret is required for Microsoft Graph.
In Azure Portal, select Certificates & Secrets for the Crawling Application.
Ensure you are on the Client Secrets tab.
Select New Client Secret.
Description – Add a description to the secret of what it will be used for.
Expires – Give the secret an appropriate expiry date.
Select Add.
Be sure to save your secret to a secure vault such as LastPass as you will not be able to view it again.
This secret is now associated with the registered application in Azure.
Azure Portal – API permissions (Crawling Application)
SharePoint API – Sites.Selected
In Azure Portal, navigate to your Crawling Application.
Under Manage, select API Permissions.
There will always be Microsoft Graph, User.Read permissions. This is required and should remain in place.
Select Add a permission.
Under Microsoft APIs, select SharePoint.
Select Application permissions.
This ensures user credentials aren't required for authentication and the context is not scoped to one user.
From the available permissions, select Sites.Selected.
Select Add permission.
You must grant admin consent for any permission applied.
This allows silent authentication for APIs. Without this the application needs a user invoked authentication flow.
Select Grant admin consent for <organisation>.
Select Yes to confirm this selection.
Microsoft Graph API – Sites.Selected
Select Add permission again.
Select Microsoft Graph.
Select Application permissions.
From the available permissions, select Sites.Selected.
Select Add permission.
Grant admin consent for <organisation>.
Granting the Crawling Application on each site (Grant Site Permissions Application)
When using Sites.Selected you must grant access to the Crawling Application for each selected site.
You must do this on a per site basis.
Using PowerShell
Connect using PowerShell with the Grant Site Permissions Application (replace placeholders).
Grant access to the Crawling Application (replace placeholders).
Control Hub – Credentials (Crawling Application secret)
Create a Client ID Secret Credential
Within Control Hub select Credentials.
On the Credentials page, select New Credential.
Credential Type – Select Client ID and Secret.
Credential ID – Enter an ID for this credential.
It must be lowercase, with no spaces and no special characters.
Credential Name – Enter a user friendly name for this credential.
Secret – Enter the secret associated with the Crawling Application in Azure.
Expiry Date (DD-MM-YYYY) – Enter the expiry date.
It must not be in the past or after the secret's expiry date.
Select Create.
Your new secret credential is now in the Workplace AI Credential Store.
Control Hub – Security Configuration
For permission trimming in Workplace AI, we must know the SharePoint groups a user belongs to.
Members of a SharePoint group are exploded onto an item during crawl time when using Sites.FullControl.All. With the Read grant path and Graph API for permissions, only the SharePoint group names are accessible—not who is in them. The SharePoint Security plugin provides a secondary security sync that maps SharePoint group membership to users in Workplace AI.
If you're running a permissionless crawl, a SharePoint Security plugin isn't needed. You can skip this section.
Creating a SharePoint Security configuration
Within Control Hub select New Configuration.
Select Security.
Configuration ID – Enter an ID for this configuration.
It must be lowercase, with no spaces or special characters.
Configuration Description – Add a description of what the configuration will be used for.
Source System - Select SharePointSecurity from the dropdown.
Primary Connection
Client ID – Enter the Application (client) ID of the Crawling Application.
You can find this in the Overview on the Azure Portal.
Directory (Tenant) ID – Enter the Directory (tenant) ID for the Crawling Application.
You can find this in the Overview on the Azure Portal.
Select Credential – Select the certificate credential associated with the Crawling Application .pfx file.
Secondary Connection
Select Credential – Select the secret associated with the Crawling Application in Azure.
The SharePoint security configuration is designed to run with Read-Only API permissions where applicable.
Control Hub – Source Configuration
This configuration corresponds to the Selected Sites - Read Access scenario in the API Permissions Quick Reference.
Within Control Hub select New Configuration.
If you're applying this to an existing source, find the configuration and select edit.
On the Source tab, select SharePoint from the Source System dropdown.
Primary Connection (Crawling Application)
Client ID – Enter the Application (client) ID of the Crawling Application.
You can find this in the Overview on the Azure Portal.
Directory (Tenant) ID – Enter the Directory (tenant) ID for the Crawling Application.
You can find this in the Overview on the Azure Portal.
Select Credential – Select the certificate credential associated with the Crawling Application's .pfx file.
Secondary Connection
Check "Use Graph API for site discovery".
Check "Use Graph API for permissions".
Only enable this if permissions on files are needed. Otherwise run the crawl as permissionless under the Advanced tab.
Directory (Tenant) ID – Enter the Directory (tenant) ID for the Crawling Application.
You can find this in the Overview on the Azure Portal.
Select Credential – Select the Client ID and Secret credential for the Crawling Application.
Permissions tab
Security Configuration – Enter the configuration ID of the SharePoint Security configuration you made earlier. This is very important for permission trimming in Workplace AI. It is validated when saving the source configuration.
This is not required if you are running a permissionless crawl.
Advanced tab
Disable Build Site Caches when using Read site grants with this pattern.
Save
Select Save.
You are now ready to run a crawl using Sites.Selected with Read site grants.
Implementation note (validator behaviour)
When Use Graph API for permissions or Use Graph API for site discovery is enabled, the SharePoint source expects Graph connection settings to be complete (including a Client Secret credential reference on the Graph authentication configuration). When Use Graph API for permissions is enabled, a valid SharePoint Security secondary security configuration ID is also required.
Last updated