Whitepaper

Introduction

As of April 2026, Microsoft will discontinue its authentication service Azure ACS (Access Control Services) and will transition to using Microsoft Entra ID, which affects all Microsoft SharePoint Online Connectors that are currently used by Mindbreeze customers. For more information about the retirement of Azure ACS, please see https://learn.microsoft.com/en-us/sharepoint/dev/sp-add-ins/retirement-announcement-for-azure-acs.

To proactively respond to this change and ensure the continued functionality of the Microsoft SharePoint Online crawler, Principal Resolution Service and the Authorization service, the authentication method is being updated to certificate-based authentication. In the following chapters, the necessary steps are described to prepare the existing Azure application, add the permission “Sites.Selected” and migrate the existing “FullControl” permissions for certificate-based authentication.

Requirements

Please check the following requirements:

• The Microsoft administrator has the appropriate permissions for the Azure application. One of the following two options must be met:
  • Option 1: The Microsoft administrator has the role “Global Administrator”.
  • Option 2: The Microsoft administrator has the roles “SharePoint Administrator” and “Application Administrator”.
• An Application Registration is created or already existent for the SharePoint Online Connector in Azure Portal/Microsoft Entra ID admin center.
  • For more information about the registration of an application, see the Microsoft documentation: How to register an application.

Creation of the certificate

In order to migrate to certificate-based authentication, a certificate is needed that will be uploaded to the Azure application to connect with Mindbreeze InSpire. This certificate can be created and can either be a CA-signed certificate using a trusted certificate authority or a self-signed certificate (.cer, crt or .pem).

For more information about the creation of a self-signed certificate, see the Microsoft documentation: .

After the creation of the certificate, please make sure to save the certificate including the private key and to provide it to the Mindbreeze InSpire administrator.

Adding the certificate and updating the Azure application

Step 1: Adding the certificate to the Azure Application

To upload and add the certificate to an existing Azure application, sign in to the Azure Portal/Microsoft Entra ID admin center.

Then, go to “Microsoft Entra ID”, and in the “Overview”, go to “App registrations”. Choose the existing Azure application that you want to connect with Mindbreeze InSpire.

In the Azure application, go to the side navigation and open the menu item “Manage”. To upload the certificate, go to the sub menu item “Certificates & secrets”. Click on “Upload certificate” and select the public certificate file (.cer, crt or .pem). Then, click on “Add”.

For more information, please see the Microsoft documentation How to add credentials to an application.

Step 2: Migration of SiteCollection-Wide API Permissions

Due to the retirement of Azure ACS for SharePoint Online, SiteCollection-Scoped “FullControl” permissions can no longer be granted by using AppInv.aspx (before the retirement of Azure ACS, it was possible to upload a SiteCollection-level scope with “FullControl” rights through the SharePoint AppInv.aspx page). Now, this capability must be configured through application permissions in Microsoft Entra ID. In the future, access to SharePoint will be managed via Azure application permissions.

To add the API permission “Sites.Selected” to the Azure application, go to the existing Azure application in the Azure Portal/Microsoft Entra ID admin center, open the menu item “Manage” and click on “API permissions”.

Then “Add a permission” and make sure to choose “SharePoint”.

Choose “Application permissions” as permission type. Then expand the permission option “Sites” and choose the permission “Sites.Selected”. Finally, click on “Add permissions”.

For more details see the Microsoft documentation: How to update application permissions

Now, with the API permission added to the Azure application, the sites that are to be indexed by Mindbreeze InSpire can be prepared by migrating the API permission for each site.

Step 3: Migration of the API Permission for each site with Microsoft Graph Explorer

After the API permission “Sites.Selected” has been added to the Azure application, the API permission of each site that is to be indexed by Mindbreeze InSpire must be migrated. In this step, the API permission “FullControl” will be migrated for a site to enable the same level of access as before the migration process. This is done by running queries in Microsoft Graph Explorer.

Hint: Please be aware that this step only migrates the API permission of one site. If the content of several sites is to be indexed, this step must be performed for each site individually.

Go to the Microsoft Graph Explorer and sign in with the needed Microsoft account. To migrate the API permission for a site, the Site ID must be known. If the Site ID is unknown, the following GET query can be used to find the Site ID:

https://graph.microsoft.com/v1.0/sites/<Host>:<Site>

For example, the Site ID for the site “ExampleSite1” can be found with the query:

https://graph.microsoft.com/v1.0/sites/company.sharepoint.com:/sites/ExampleSite1

Now that the Site ID is known, the API permissions can be migrated with the following POST query and Request Body:

For example, to migrate the API permission for the site “ExampleSite1”, the POST query and the request body will look like this:

After the POST query and request body were run, the response should show that the attribute “roles” is now set to “fullControl” for this site (as shown in the screenshot above).

Hint: With the certificate and API permission “Sites.Selected” added to the Azure application, it is now also possible to access the site via SharePoint Rest API or CSOM. For more information, see the Microsoft documentation https://techcommunity.microsoft.com/blog/spblog/develop-applications-that-use-sites-selected-permissions-for-spo-sites-/3790476.

Now, the API permission of one site has been successfully migrated and the contents of the site can be used by the Microsoft SharePoint Online crawler, Principal Resolution Service and Authorization Service. In the case of several sites that are to be indexed, please repeat this whole step for the remaining sites.

Alternative: Tenant-wide application for simplified management and maintenance of sites and permission

The migration of API permissions for every site that is to be indexed by Mindbreeze InSpire can take considerable effort, especially in cases were a big number of sites must be migrated. After the migration, a considerable amount of effort will still be necessary to maintain sites by adapting changes or updates to the sites in coordination with the customer Mindbreeze administrator.

To immensely reduce and streamline the effort that is needed for the migration of the Azure application, the sites and the subsequent maintenance, the transition from a Sites.Selected to a tenant-wide application could be considered. With the transition to a tenant-wide application, the following advantages are available:

• Permissions can be managed from one central point instead of managing the permission for each site individually. Maintaining and updating permissions is also easier and can be done with much less effort.
• Site collections will be detected automatically by the Site discovery feature. Therefore, indices in Mindbreeze InSpire are more often updated and include new sites and documents faster. With this feature it is also ensured, that all new documents will be useable in Mindbreeze InSpire.

To transition to a tenant-wide application, the migration process is simpler than the migration of a Sites.Selected application, as seen in the following table:

For more information about the migration to a tenant-wide application, see Whitepaper - Migration of Tenant-Wide Permissions for the Microsoft SharePoint Online Connector.