Common Setup for Sites.Selected

Using Azure Communication Services (ACS) for authentication is being deprecated. If you are using this, you must migrate away from it by 2nd April 2026.

The preferred way of authenticating is using an Azure Portal App Registration. It creates an application in Entra ID (previously Azure AD). Entra ID manages authentication and allows invocation of supported apps. This includes SharePoint via API permission scopes.

This guide explains how to configure two applications in Azure Portal and how to grant your crawl identity access per site using Sites.Selected. Use it when you want least-privilege SharePoint access at the API level (only selected sites) instead of tenant-wide Sites.FullControl.All or Sites.Read.All on the application that performs the crawl.

Application-only permissions: Every API permission in this guide is an Application permission (app-only). Do not use Delegated permissions for these scenarios.

---

Crawling Application and Grant Site Permissions Application

You must keep the following two applications distinct.

Crawling Application stays limited to Sites.Selected on the SharePoint API so it can only operate on sites you explicitly grant.

Grant Site Permissions Application has a much higher permission level (Sites.FullControl.All on Microsoft Graph) because Microsoft requires an identity with sufficient privilege to manage site permission grants.

Application	Purpose	SharePoint API	Microsoft Graph API
Crawling Application	The app registration Workplace AI uses to crawl SharePoint (CSOM / connector).	Sites.Selected	Depends on site grant role — see below.
Grant Site Permissions Application	The app registration used only to grant the Crawling Application access to each site (adds it to the site's granted identities). It does not perform crawling.	Not used for crawling; not required on this app for the connector.	Sites.FullControl.All (required so the app can assign permissions on sites for the Crawling Application).

Disable the Sites.FullControl.All permission from the Grant Site Permissions Application when it is not actively in use. This reduces risk by limiting standing permissions of this app.

---

Choose your path

The steps you follow depend on which role you grant the Crawling Application at each site. Decide before you begin. To help you decide which path, please see the API Permissions Quick Reference. Complete the common setup on this page first, then follow the matching runbook.

Prerequisites

1. You must grant access to the IPs listed under the SharePoint section of Microsofts URLs and IP Address Ranges document.

2. PowerShell 7 and PnP PowerShell module must be installed. PowerShell 7, PnP PowerShell

Grant role	What it means	Runbook
FullControl	The Crawling Application can retrieve file permissions via CSOM directly. No Graph API or SharePoint Security plugin required.	FullControl Grant Path →
Read	The Crawling Application can only read file content. Graph API and the SharePoint Security plugin are required for permissions.	Read Grant Path →

---

Azure Portal – Application Registration (Crawling Application)

To register the SharePoint connector application within Azure Portal, follow these steps:

1. Navigate to https://portal.azure.com

2. Ensure you are in the correct Azure Directory.

3. In the search bar, type "App Registrations" or click the shortcut under Azure Services.

4. Select New registration.

5. Name - Give the application a user friendly name.

6. Supported account types - Consider if the application will only be used in this directory or others within your organisation.

7. Redirect URI (optional) – This is not required.

8. Select Register.

This will take you to the registered application page with an overview of your application. You'll need the Application (client) ID and Directory (tenant) ID from this page later in the process.

---

Azure Portal – Application Registration (Grant Site Permissions Application)

Repeat the same New registration steps above to create a second application. This registration is only for granting site access; note its Application (client) ID separately from the Crawling Application.

---

Azure Portal – Certificates & Secrets (Crawling Application)

You can now create and apply a self-signed X.509 certificate. This will authenticate and invoke SharePoint Online via the registered application.

Alternatively, you can use an X.509 certificate issued by your preferred Certificate Authority (CA), although the certificate is not client facing.

This guide explains creating the self-signed certificate and manifest settings using a Cmdlet. They're needed to use SharePoint CSOM via app-only API permissions. You create them using the PnP.PowerShell Cmdlet, New-PnPAzureCertificate. See Microsoft's app only security documentation for more information on this.

Cmdlet requirements

• Running PowerShell 7 in Administrator mode.

• The PnP.PowerShell module to be installed.

1

Running the Cmdlet

1. Open a new administrator PowerShell terminal and run the following command.

New-PnPAzureCertificate -OutPfx crawling-app.pfx -OutCert crawling-app.cer -CertificatePassword (ConvertTo-SecureString -String "<Your Password>" -AsPlainText -Force) 

1. Save the certificate files in your preferred location and give them a strong password.

   • Make sure both the .cer and .pfx files are saved. The .cer (public key) will be uploaded to the registered application in Azure Portal. The .pfx (private key) will be uploaded to the Credential Store in Workplace AI Control Hub.

2

Apply the certificate to the registered application

1. In Azure Portal, select Certificates & Secrets.

2. Ensure you are on the Certificates tab.

3. Select Upload certificate.

4. Select the generated .cer file you created using New-PnPAzureCertificate.

5. Description – Add a description of how the certificate will be used.

6. Select Add.

This certificate is now associated with the registered application in Azure.

---

Azure Portal – Certificates & Secrets (Grant Site Permissions Application)

Create a certificate for this application separately from the Crawling Application certificate.

1

Running the Cmdlet

1. Open a new administrator PowerShell terminal and run the following command.

New-PnPAzureCertificate -OutPfx grant-app.pfx -OutCert grant-app.cer -CertificatePassword (ConvertTo-SecureString -String "<Your Password>" -AsPlainText -Force)

1. Save the certificate files in your preferred location and give them a strong password.

   • Make sure both the .cer and .pfx files are saved. The .cer (public key) will be uploaded to the registered application in Azure Portal. The .pfx (private key) must be retained securely for use with the PowerShell grant commands later in this guide.

2

Apply the certificate to the registered application

1. In Azure Portal, navigate to your Grant Site Permissions Application.

2. Select Certificates & Secrets.

3. Ensure you are on the Certificates tab.

4. Select Upload certificate.

5. Select the grant-app.cer file you created using New-PnPAzureCertificate.

6. Description – Add a description of how the certificate will be used.

7. Select Add.

This certificate is now associated with the Grant Site Permissions Application in Azure.

---

Azure Portal – API permissions (Grant Site Permissions Application)

1. In Azure Portal, navigate to your Grant Site Permissions Application.

2. Under Manage, select API Permissions.

3. Select Add a permission.

4. Select Microsoft Graph.

5. Select Application permissions.

6. From the available permissions, select Sites.FullControl.All.

7. Select Add permission.

8. Select Grant admin consent for <organisation>.

9. Select Yes to confirm this selection.

---

Control Hub – Credentials (Crawling Application certificate)

Create a Certificate credential

1. Within Control Hub select Credentials.

2. On the Credentials page, select New Credential.

3. Credential Type – Select Certificate.

   • This will reveal the relevant input fields for uploading a certificate.

4. Credential ID – Enter an ID for this credential.

   • It must be lowercase, with no spaces or special characters.

5. Credential Name – Enter a user friendly name for this credential.

6. Password – Enter the password associated with the certificate you generated earlier.

7. Expiry Date (DD-MM-YYYY) – This will automatically populate according to the certificate's expiry.

   • You can add a date to the certificate expiry if needed. It must not be in the past or after the certificate's expiry date.

8. Import Certificate – Either, drag and drop the .pfx file or find it using the "browse files" link.

   • If using "browse files" in Windows Explorer you must enable "All Files (*.*)" when searching.

   • Only valid certificates can be uploaded.

9. Select Create.

Your new certificate credential is now in the Workplace AI Credential Store.

---

Troubleshooting

Certificates are validated at the point of creation. Validation checks things like passwords, expiry dates and user profile capabilities.

Applying the certificate to the Credential Store

If you get an error about the expiry date or network password, check they are correct in the credential.

An error stating "The file cannot be found"

1. Open Internet Information Services (IIS) on the web server running Control Hub.

2. Confirm which AppPool is used for the admin API.

   1. Navigate to Sites -> Default Web Site -> admin -> api.

      • Open Basic Settings for the api and observe the AppPool used.

   2. Navigate to the AppPool - Application Pools -> <YouAdminAppPool>

   3. Open Advanced Settings for the Admin AppPool.

   4. Under Process Model, ensure "Load User Profile" is set to True.

   5. Restart IIS, this will also recycle your Application Pools too.

You should now be able to add your certificate to the Credential Store in Control Hub.

---

Next steps

Continue with the runbook for your chosen path:

• Read Grant path →

• FullControl grant path →