Migrating ACS to Azure AD with Sites.Read.All
Using Azure Communication Services for authentication with Sites.FullControl.All permissions 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 gives an application an Entra ID (previously Azure AD). The Entra ID manages the authentication and allows invocation of supported apps. This includes SharePoint via API permission scopes.
The SharePoint connector may need to run against API permissions granting Read-Only access. This means, at an API level, the app can only read SharePoint objects. It cannot create, update or delete SharePoint objects.
This guide explains how to configure an application in Azure Portal and any Control Hub changes. It can assist anyone migrating from ACS to Azure AD while using Read-Only API permissions.
Azure Portal - Application Registration
To register the SharePoint connector application within Azure Portal, follow these steps:
Navigate to https://portal.azure.com
Ensure you are in the correct Azure Directory.
In the search bar, type “App Registrations” or click the shortcut under Azure Services.
Select New registration.
Name - Give the application a user friendly name.
Supported account types - Consider if the application will only be used in this directory or others within your organisation.
Redirect URI (optional) – This is not required.
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 - Certificates & Secrets
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.
Running the Cmdlet
Open a new administrator PowerShell terminal and run the following command.
New-PnPAzureCertificate -OutPfx pnp.pfx -OutCert pnp.cer -CertificatePassword (ConvertTo-SecureString -String "<Your Password>" -AsPlainText -Force) 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 Aiimi Insight Engine Control Hub.
Apply the certificate to the registered application
In Azure Portal, select Certificates & Secrets.
Ensure you are on the Certificates tab.
Select Upload certificate.
Select the generated .cer file you created using New-PnPAzureCertificate.
Description – Add a description of how the certificate will be used.
Select Add.
This certificate is now associated with the registered application in Azure.
Create a secret for the registered application
In Azure Portal, select Certificates & Secrets.
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.
It's important to have both authentication methods set up. We use both to leverage Graph APIs Read-Only capabilities where necessary. The certificate is required for the CSOM (Client-Side Object Model) library for SharePoint. While the secret is required for the Graph API.
Azure Portal - API Permissions
Now you have a registered application with a certificate and secret, you can add API Permissions.
In Azure Portal, navigate to your registered 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.Read.All.
Select Add permission.
Select Add permission again.
Select Graph API
Select Application permissions.
From the available permissions, select Sites.Read.All.
Select add permission.
The permissions have been applied but not yet granted to the registered application.
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.
The Sites.Read.All API permission has been applied to the registered application for SharePoint and the Graph API.
AIE Control Hub – Credentials
Now everything is configured in Azure Portal, you need to create credentials in Aiimi Insight Engine's Control Hub.
Create a Certificate credential
Within the Control Hub select Credentials.
On the Credentials page, select New Credential.
Credential Type – Select Certificate.
This will reveal the relevant input fields for uploading a certificate.
Credential ID – Enter an ID for this credential.
It must be lowercase, with no spaces or special characters.
Credential Name – Enter a user friendly name for this credential.
Password – Enter the password associated with the certificate you generated earlier.
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.
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.
Select Create.
Your new certificate credential is now in the Aiimi Insight Engine 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”
Open Internet Information Services (IIS) on the web server running AIE Control Hub.
Open Internet Information Services (IIS) on the web server running AIE Control Hub.
Confirm which AppPool used for the admin API.
Navigate to Sites -> Default Web Site -> admin -> api.
Open Basic Settings for the api and observe the AppPool used.
Navigate to the AppPool - Application Pools -> <YouAdminAppPool>
Open Advanced Settings for the Admin AppPool.
Under Process Model, ensure “Load User Profile” is set to True.
Restart IIS, this will also recycle your Application Pools too.
You should now be able to your certificate to the Credential Store in the Control Hub.
Create a Client ID Secret Credential
Within the 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 registered 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 Aiimi Insight Engine Credential Store.
AIE Control Hub – Security Configuration
If you enabled “Use Graph API for permissions” you will likely want to discover members of SharePoint groups in the following scenario:
A file or folder, which is shared with a SharePoint group, is discovered via the SharePoint source connector. The connector will tag files with the name of the SharePoint group in the permission object.
Members of a SharePoint group are exploded onto an item during crawl time when using Sites.FullControl.All. If using the Graph API for permissions, we can only access the SharePoint group names not who is in them.
The SharePoint Security plugin allows for a secondary security sync. It maps users from SharePoint to users in Aiimi Insight Engine. The SharePoint group membership is applied to each principles Groups property. This is done in a secondary security index.
Creating a SharePoint Security configuration
Within the 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 registered application.
You can find this in the Overview on the Azure Portal.
Directory (Tenant) ID – Enter the Directory (tenant) ID for the registered application.
You can find this in the Overview on the Azure Portal.
Select Credential – Select the certificate credential associated with the .pfx file.
Secondary Connection
Select Credential – Select the secret associated with your registered application in Azure.
The SharePoint security configuration is designed to run with Read-Only API permissions.
The only limitation to this is when discovering members of limited access or sharing links groups. These groups require the API permission to be Sites.FullControl.All in Azure.
If you don't need to synchronise these groups, you can run the configuration with Sites.Read.All API permissions in Azure.
AIE Control Hub – Source Configuration
Now the registered application, credentials and security are set up, you can configure a SharePoint source.
Within the 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
Client ID – Enter the Application (client) ID of the registered application.
You can find this in the Overview on the Azure Portal.
Directory (Tenant) ID – Enter the Directory (tenant) ID for the registered application.
You can find this in the Overview on the Azure Portal.
Select Credential – Select the certificate credential associated with the .pfx file.
Secondary Connection
Check “Use Graph API for site discovery”.
Directory (Tenant) ID – Enter the Directory (tenant) ID for the registered application.
You can find this in the Overview on the Azure Portal.
Select Credential – Select the secret associated with your registered application in Azure.
If Using Graph API for Permissions
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.
If you're indexing permissions
On the Permissions tab.
Security Configuration – Enter the configuration ID of the SharePoint Security configuration you made earlier.
This is not required if you are running permissionless crawls.
This is very important for permission trimming in Aiimi Insight Engine. It is validated when saving the source configuration.
Select Save.
You are now ready to run a crawl using Read-Only API permissions instead of ACS.
Last updated