Connecting SharePoint

Register a Microsoft Entra application and grant it read access to your sites, then add it under Connectors so Knowledge Bases can sync SharePoint sites.

For: Microsoft Entra administrators, and WI administrators (the admin ability) · Last updated

WI reads SharePoint through a Microsoft Entra application registered in your Microsoft 365 tenant. The application's permissions decide which sites WI can read; WI never grants that access itself. Only the Microsoft public cloud is supported. Once the connection exists, Knowledge Base owners and editors point a Knowledge Base at a SharePoint site (see SharePoint sources).

Who does this#

Part 1 happens in Microsoft Entra and needs two roles:

  • Registering the application needs an Entra role that can create app registrations, such as Application Developer.
  • Granting admin consent for Microsoft Graph application permissions needs Privileged Role Administrator (a Global Administrator can too). Application Administrator and Cloud Application Administrator cannot grant consent for Microsoft Graph application permissions (see Microsoft's grant tenant-wide admin consent page).

Part 2 happens in WI and needs the admin ability. An administrator of WI who does not hold the Entra roles can hand this article to the person who does, and use Part 2 once that person gives them the tenant ID, client ID and client secret.

What each way of reading SharePoint needs:

Part Organization application (default) Sign in with a person's Microsoft account
Register the application, copy the tenant ID and client ID Needed Needed (same application)
Client secret Needed Needed (same secret)
Application permission Sites.Read.All (or Sites.Selected) with admin consent Needed Needed only if you also use the organization application
Redirect URI (platform Web) Not used Needed
Delegated permission Sites.Read.All Not used Needed

Part 1: In Microsoft Entra#

Find the redirect URI#

The redirect URI is the address of the WI installation followed by /api/integrations/oauth/callback, for example https://wi.example.com/api/integrations/oauth/callback. WI shows the exact value on its Add SharePoint form, so you can copy it from there or ask a WI administrator for it. The organization application does not use it. Microsoft sends a person back to it only when sign in with a person's Microsoft account is on. Microsoft accepts only https addresses, except for localhost.

Register the application#

  1. Sign in to the Microsoft Entra admin center.
  2. If you belong to more than one tenant, select the Settings icon at the top and switch to the tenant whose SharePoint WI should read.
  3. Select Entra ID, then App registrations, then New registration.
  4. Enter a Name, for example Workforce Intelligence SharePoint.
  5. Under Supported account types, select Single tenant only. Some versions of the portal word it "Accounts in this organizational directory only (Single tenant)".
  6. Under Redirect URI (optional), open the platform list and select Web, then paste the redirect URI. If you do not have it at hand, leave it empty and add it later (see Add the redirect URI later).
  7. Select Register.

Copy the IDs and create a client secret#

  1. On the Overview page, copy the Directory (tenant) ID and the Application (client) ID.
  2. In the left menu, select Certificates & secrets, then the Client secrets tab, then New client secret.
  3. Enter a description, choose when it expires, and select Add. Microsoft limits a secret to 24 months and recommends less than 12.
  4. Copy the secret's Value straight away. Do not copy the Secret ID. Microsoft shows the value only once; after you leave the page it is gone and you must create another.

Give the tenant ID, client ID and secret value to the WI administrator who does Part 2.

Grant read access#

The application can read nothing until you grant it a permission. Choose one of the two options.

Option A: read all sites with Sites.Read.All#

  1. In the left menu, select API permissions, then Add a permission.
  2. Select the Microsoft Graph tile, then Application permissions. Type Sites in the search box, tick Sites.Read.All, and select Add permissions.
  3. On the API permissions page, select Grant admin consent for your tenant's name, then Yes. Select Refresh. The Status column then shows a green Granted for your tenant's name.

Choose the Microsoft Graph tile, not the SharePoint tile. The Add a permission pane shows both a Microsoft Graph tile and an older SharePoint tile, and both list a permission named Sites.Read.All. WI reads SharePoint through Microsoft Graph, so the permission under the SharePoint tile does not apply and every site is refused. In the API permissions list, the correct row sits under Microsoft Graph. A row under SharePoint is the mistake: select the menu at the end of that row and remove it, then add the permission again from the Microsoft Graph tile and grant admin consent.

Option B: read only selected sites with Sites.Selected#

Sites.Selected is tighter: the application reads only the sites you name.

  1. Add the permission and grant admin consent as in Option A, but tick Sites.Selected instead of Sites.Read.All.
  2. For each site, give the application the read role on that site. Microsoft does this with a Graph request or a PowerShell command, not with a button in the portal. Follow Microsoft's pages on selected permissions and granting access to a site.

Until a site has been granted to the application, WI's Check access passes but that site is refused.

Add permissions for person sign-in (only if WI uses it)#

Do this when the WI administrator turns on sign in with a person's Microsoft account (see Part 2).

  1. On API permissions, select Add a permission, then Microsoft Graph, then Delegated permissions.
  2. Tick Sites.Read.All and offline_access, then select Add permissions. offline_access lets WI keep a person's sign-in current without asking again. User.Read is granted by default.
  3. Select Grant admin consent for your tenant's name if your tenant requires it.

Add the redirect URI later#

  1. In the left menu, select Authentication.
  2. Select Add a platform, then Web, and paste the redirect URI.
  3. Select Configure.

Part 2: In WI#

A WI administrator does this part. You need the tenant ID, client ID and client secret from Part 1.

Add the connection#

  1. Open Settings and select Connectors under Your account.
  2. Select Add a connection, search for SharePoint, and select it. It is tagged For Knowledge Bases, because SharePoint feeds Knowledge Bases rather than giving Coworkers tools.
  3. Fill in:
    • Name: how Knowledge Base owners and editors see the connection.
    • Tenant ID: the directory (tenant) ID of the application.
    • Client ID: the application (client) ID.
    • Client secret: at least 8 characters, stored encrypted and never shown again.
  4. Select Add SharePoint.

The form also shows the Redirect URI for Part 1. Connection names are unique within your company. You can add more than one connection, for example when different sites are granted to different applications; owners and editors then choose one when they add a site.

Check access#

Select Check access on the connection. WI tries to sign in with the application and shows the result under the name, with the time of the check:

  • Access confirmed: sign-in worked and the application holds a Microsoft Graph permission to read SharePoint sites (Sites.Read.All, Sites.ReadWrite.All or Sites.FullControl.All).
  • Access confirmed with a note, "Signed in with Sites.Selected. Each site must also be granted to the application before it can be read.": the application has only Sites.Selected, so each site must be granted to it as described in Option B.
  • Access refused, with the reason: sign-in failed (the tenant ID, client ID or client secret is wrong, or the secret has expired), or sign-in worked but the application has no Microsoft Graph permission for SharePoint.
  • Not checked: no check has run.

Check access reads the permissions the application was granted, but it cannot tell whether a particular site has been granted. That is tested when an owner or editor adds the site. A permission change in Entra can take a few minutes to take effect. WI uses the new permission on the next check or sync.

Sign in with a person's Microsoft account#

By default WI reads SharePoint as the application. You can also let people connect their own Microsoft account, so a Knowledge Base can sync a site as its owner's account and read what that account can read. This uses the same application and client secret as the connection.

  1. In Entra, add the delegated permissions and the redirect URI described in Part 1.
  2. On the connection in WI, find Sign in with a person's Microsoft account and select Turn on. The section shows On and a Redirect URI; select Copy to copy it.

Once it is on, the connection appears as one entry named after the connection under Connected accounts in each person's Settings (see Connecting your accounts). It does not appear as a separate system on the Connectors page and is managed here. When an owner or editor adds a site, Sync as offers the owner's Microsoft account for this connection.

Turn off asks you to confirm. Turning it off removes everyone's connected Microsoft accounts for this connection. It is refused, with a message naming the Knowledge Bases, while any site is still set to sync as an owner's account; those sites must be removed first (a site's sign-in cannot be switched, so add it again as the organization's application if you still need it). Deleting the connection removes the sign-in the same way.

Changing the Tenant ID or Client ID points the sign-in at a different application, so people have to connect again; their sites show Needs sign-in until they do.

Edit the connection and replace the secret#

Select Edit to change the Name, Tenant ID or Client ID, then Save changes. Select Hide settings to close the form.

The client secret is write-only, and a new one must be at least 8 characters. The form shows only the masked end of the current secret. When a secret is close to expiring, create a new one in Entra (Certificates & secrets, then New client secret), enter the new value under Replace client secret and select Replace secret. Syncs use the new secret from then on. Sign in with a person's Microsoft account stays connected only if the new secret belongs to the same application.

Delete the connection#

Select Delete, then Delete SharePoint. A connection cannot be deleted while any Knowledge Base still syncs a site through it; the message names those Knowledge Bases. Remove their SharePoint sources first. Documents already indexed stay where they are.

Which Knowledge Bases use a connection#

Each connection lists the Knowledge Bases that use it under Used by, linked to their pages. Supervisors who are not administrators see each connection by name with that list. They do not see its tenant ID, client ID or secret, and cannot add, change or delete it.

Troubleshooting#

A site that cannot be read shows Sync failed in its Knowledge Base's SharePoint sources card, with the reason in plain words.

Sign-in failed#

A sign-in failure, or Access refused from Check access, means the tenant ID, client ID or client secret is wrong or the secret has expired. Correct the values under Edit, or replace the secret, then select Check access.

Check access says the application has no Microsoft Graph permission#

Check access shows "Signed in, but this application has no Microsoft Graph permission for SharePoint. In Microsoft Entra, add the Microsoft Graph application permission Sites.Read.All (not the SharePoint one) and grant admin consent." The usual cause is that Sites.Read.All was added from the SharePoint tile instead of the Microsoft Graph tile. On API permissions in Entra, a row under SharePoint is that mistake. Remove it with the row's menu, add Sites.Read.All from the Microsoft Graph tile as Application permissions, and grant admin consent. Wait a few minutes, then select Check access again. WI picks up the change on that check, and a source that was refused syncs again on its next sync.

A site is refused#

Check access passes but a site is refused when the application has no permission on that site:

  • On API permissions in Entra, the Status column is not a green Granted for your tenant's name. Grant admin consent.
  • With Sites.Selected, the site has not been granted to the application. Give it the read role on that site.

After fixing it, select Sync now on the site.

Some libraries could not be read#

When a site's Library field is blank, WI syncs every document library on the site except system libraries (Site Assets, Style Library, Form Templates, Preservation Hold Library, Teams Wiki Data, Site Pages, and any library whose name starts with an underscore). A library the application cannot read shows Partially synced with how many libraries were left out; their documents stay as they were and the other libraries sync. Name a single library in the site's Library field to sync only that one.

The site or library is not found#

A message that the site or library could not be found means the address or library name is wrong, or the account or application may not have access to it. A site address on a different Microsoft 365 organization shows the same message. Check the address, then check access. Remove the site and add it again with the right address. When a site is added, WI first checks that it can reach it; a wrong address or a refusal is shown on the form and nothing is saved.

A site added with your own account that SharePoint refuses reads "SharePoint refused access to this site for your account." Ask the site owner for access, or use the organization's application. A message that SharePoint could not complete the request means a temporary problem or an address SharePoint did not accept; try again in a moment, and if it keeps happening, check the address and the account's access.

What the audit log records#

Every change to a SharePoint connection is recorded in the audit log: the connection added, changed, checked, having its client secret replaced, personal sign-in turned on or off, or removed. So is each change to a Knowledge Base's SharePoint sources: a source added, its sync schedule changed, a sync started by hand, or the source removed. The record carries names, the tenant and client ids and the site address. It never carries the client secret.

Production setting#

A production install always uses the real Microsoft connection. WI_SHAREPOINT_DRIVER defaults to httpx, the only value a production install accepts. Production startup refuses any other value (see Production boot checks).