8  SharePoint Connector

The SharePoint connector can index a whole Microsoft 365 tenant or a narrow set of sites, libraries, folders, and files. This chapter is for workspace admins and Microsoft 365 admins who must choose the correct sign-in method, configure Microsoft Entra permissions, and verify document access.

8.1 Choose the setup path

Choose the path before you create the connector. The choice controls who owns the Microsoft app and whether Nous can mirror SharePoint permissions.

Setup path Microsoft app owner Document access Best for
Managed by Sophea Sophea Public or Private The fastest setup when the signed-in user’s SharePoint access is enough
Self-managed Client Secret Your organization Public or Private Organization-controlled app-only indexing without permission sync
Self-managed Certificate Authentication Your organization Public, Private, or Sync permissions Organization-wide indexing that must mirror SharePoint users and groups
Important

Sync permissions requires Certificate Authentication. A Client Secret credential cannot use this access mode. Microsoft Entra receives the public certificate. Nous receives the matching password-protected PFX file.

8.2 Before you start

Prepare these roles and values:

  • a Sophea Nous workspace admin who can create credentials and connectors
  • a Microsoft Entra admin who can create app registrations, add application permissions, and grant tenant-wide admin consent
  • the Microsoft 365 tenant ID, also called the Directory ID
  • an account that can confirm which SharePoint sites should be indexed
  • for certificate authentication, a secure location for the PFX file and its password

Use a dedicated Entra app registration for the connector. Do not reuse a user account password or a certificate used by an unrelated application.

8.3 Managed by Sophea

Use this path when you do not need SharePoint permission sync.

  1. In Nous, open Connectors, select Add Connector, and choose SharePoint under Managed by Sophea.
  2. Select Connect with SharePoint.
  3. Sign in to Microsoft and approve the requested delegated permissions.
  4. Choose the sites, libraries, folders, or files to index.
  5. Set Who has access to Specific Teams unless the content is intended for every member of the workspace.
  6. Create the connector and complete the verification.

This path uses the signed-in person’s SharePoint access. It does not ask you for a client ID, client secret, public certificate, or PFX file. It does not offer Sync permissions.

8.4 Portal customer form fields

Portal first asks how this workspace should connect, then shows the form.

Portal dialog with Sign in with SharePoint and Use your organization's own SharePoint credential choices.

Choose a SharePoint connection method in Portal.
Choice Who the connector acts as What Portal asks for
Sign in with SharePoint The person who clicks Connect Nothing. You approve access in Microsoft
Use your organization’s own SharePoint credential The organization Client ID, client secret, and Directory ID

Choose the organization credential for a shared connector. A personal sign-in indexes only what that person can see, and it stops working when they leave.

The form then shows Name, the SharePoint scope fields, and Who has access. Choose Everyone in the workspace or Specific Teams.

Portal Add SharePoint dialog with empty SharePoint Client ID, Client Secret, and Directory ID fields. Certificate Authentication is not offered.

SharePoint client-secret form before any credential is entered.
Field What to enter
Name A unique connector name.
SharePoint content In Browse, choose sites, libraries, folders, or files. Leave empty for all visible sites.
Sites In Paste URLs, enter SharePoint site or folder URLs, one per line.
Index Documents Keep enabled to index documents in the selected scope.
Index ASPX Site Pages Enable only when SharePoint site pages must be indexed.
Treat sharing links as public? Enable only when anonymous or organization-wide sharing links should be visible to every Nous user.
Excluded Sites Optional site URLs or glob patterns to skip.
Excluded Paths Optional file or folder glob patterns to skip.
Authority Host Default https://login.microsoftonline.com.
Graph API Host Default https://graph.microsoft.com.
SharePoint Domain Suffix Default sharepoint.com.
Who has access Everyone in the workspace or Specific Teams.

Client Secret is available in Portal, as the organization credential above, and in Nous. Certificate Authentication stays a Nous-only path, because it exists to enable Sync permissions and Portal does not offer that access mode. Use the certificate path in Nous when the customer must mirror SharePoint users and groups.

8.5 Create a self-managed Entra app

Use this setup for Client Secret or Certificate Authentication.

  1. Open the Microsoft Entra admin center.
  2. Go to Identity > Applications > App registrations.
  3. Select New registration.
  4. Enter a clear name such as Sophea Nous SharePoint Production.
  5. Select Accounts in this organizational directory only.
  6. Register the app. A redirect URI is not required for this app-only flow.
  7. Record the Application (client) ID and Directory (tenant) ID.
  8. Open API permissions > Add a permission and add the permissions for the access mode you will use.
Microsoft resource Application permission Public or Private Sync permissions
Microsoft Graph Sites.Read.All Required Required
Microsoft Graph GroupMember.Read.All Not required Required
Office 365 SharePoint Online Sites.FullControl.All Not required Required

The permission type must be Application, not Delegated. Select Grant admin consent for your tenant after all required permissions are listed. A green Granted for your tenant status must appear for each one.

Warning

Microsoft Graph and Office 365 SharePoint Online are separate resources in the permission picker. Adding Sites.FullControl.All under Microsoft Graph does not replace the Office 365 SharePoint Online permission required by permission sync.

8.6 Use a client secret

Use a client secret only for Public or Private indexing.

  1. In the Entra app, open Certificates & secrets > Client secrets.
  2. Select New client secret, choose an expiry that follows your company policy, and create it.
  3. Copy the secret Value immediately. Do not copy the Secret ID.
  4. In Nous, choose Use your own Microsoft app and create a credential.
  5. Keep Client Secret selected. Enter the Client ID, Client Secret, and Directory ID.
  6. Save the credential. Select Public or Private document access when you create the connector.

If the connector must use Sync permissions, create a separate Certificate Authentication credential. Adding more permissions does not make a Client Secret credential eligible for Sync permissions.

8.7 How certificate authentication works

One certificate creates two files with different jobs:

File Contains Upload destination Safe to share?
.cer, .pem, or .crt Public certificate only Microsoft Entra app registration Yes, it has no private key
.pfx Certificate and private key Sophea Nous credential form No, protect it and its password

Nous signs an application request with the private key inside the PFX file. Microsoft Entra verifies that signature with the public certificate registered on the app, then returns an application token.

Important

Do not upload the PFX file to Microsoft Entra. Do not give the PFX file or its password to users. Nous currently requires the PFX upload and does not read the private key directly from Azure Key Vault.

8.8 Generate a staging certificate

Use a self-signed certificate for staging or a short test.

8.8.1 Windows PowerShell

Run these commands as the account that will export the files:

$cert = New-SelfSignedCertificate `
  -Subject "CN=Sophea Nous SharePoint Staging" `
  -CertStoreLocation "Cert:\CurrentUser\My" `
  -KeyAlgorithm RSA `
  -KeyLength 2048 `
  -HashAlgorithm SHA256 `
  -KeyExportPolicy Exportable `
  -NotAfter (Get-Date).AddYears(1)

$certificatePassword = Read-Host "Enter a password for the PFX file" -AsSecureString

Export-Certificate `
  -Cert $cert `
  -FilePath ".\sophea-sharepoint-staging.cer"

Export-PfxCertificate `
  -Cert $cert `
  -FilePath ".\sophea-sharepoint-staging.pfx" `
  -Password $certificatePassword

$cert | Select-Object Subject, Thumbprint, NotAfter
(Get-Item ".\sophea-sharepoint-staging.pfx").Length / 1KB

The final command shows the PFX size in KB.

8.8.2 macOS or Linux with OpenSSL

Run these commands in a terminal. OpenSSL asks you to protect the private .key file, then asks for the export password for the PFX file:

umask 077

openssl req -x509 -newkey rsa:2048 -sha256 -days 365 \
  -keyout sophea-sharepoint-staging.key \
  -out sophea-sharepoint-staging.crt \
  -subj "/CN=Sophea Nous SharePoint Staging"

openssl pkcs12 -export \
  -out sophea-sharepoint-staging.pfx \
  -inkey sophea-sharepoint-staging.key \
  -in sophea-sharepoint-staging.crt \
  -name "Sophea Nous SharePoint Staging"

openssl x509 -in sophea-sharepoint-staging.crt \
  -noout -subject -fingerprint -sha256 -enddate

wc -c < sophea-sharepoint-staging.pfx

Use the PFX export password when Nous asks for the certificate password. The final command shows the exact PFX size in bytes. It must be 10,240 bytes or less.

Upload only sophea-sharepoint-staging.crt to Microsoft Entra. Upload sophea-sharepoint-staging.pfx to Nous. Never upload the private sophea-sharepoint-staging.key file to either system. Store or remove the private key according to your organization’s secrets policy after you confirm that the PFX works.

For both methods, keep the PFX password out of command history, tickets, chat, and source control. The Nous upload must be a .pfx file of 10 KB or less.

Microsoft documents this process in Create a self-signed public certificate to authenticate your application.

8.9 Prepare a production certificate

For production, request a certificate from your company certificate authority or approved public key infrastructure. Follow these requirements:

  • RSA key with at least 2048 bits and SHA-256 signing
  • an exportable private key, because Nous must receive a PFX file
  • a password-protected PFX file of 10 KB or less
  • a public .cer, .pem, or .crt file from the same certificate
  • an expiry date recorded in your certificate inventory and monitoring process

Store the PFX file and password through your normal secrets process. Keep them in separate controlled locations when company policy requires it. A company certificate authority may include a certificate chain in the PFX. Confirm that the final file still meets the Nous size limit before the change window.

Microsoft recommends a certificate issued by a trusted certificate authority for production. See Certificate credentials.

8.10 Upload the public certificate to Entra

  1. Open the Entra app registration.
  2. Go to Certificates & secrets > Certificates.
  3. Select Upload certificate.
  4. Upload the public .cer, .pem, or .crt file. Do not upload the PFX.
  5. Record the displayed thumbprint and expiry date.
  6. Confirm the thumbprint and expiry match the certificate you generated or received from your certificate team.

An Entra app can hold more than one active certificate. This allows safe rotation with an overlap period.

8.11 Upload the matching PFX to Nous

  1. In Nous, open Connectors, select Add Connector, and choose SharePoint.
  2. Select Use your own Microsoft app.
  3. Create a credential and choose Certificate Authentication.
  4. Enter the SharePoint Client ID and SharePoint Directory ID from the Entra app.
  5. Enter the password used when the PFX was exported.
  6. Upload the matching file under SharePoint PFX File. It must end in .pfx and be 10 KB or less.
  7. Save and select the credential.

The public certificate in Entra and the PFX in Nous must come from the same certificate. The PFX password must match the password used during export.

8.12 Select SharePoint content

The connector provides two ways to select content:

  • Browse: search and expand sites, document libraries, and folders. Select any scope down to an individual file. Unsupported files remain visible but cannot be selected.
  • Paste URLs: enter site or folder URLs when browsing is not convenient. URL parsing currently supports English, Spanish, and German SharePoint site paths.

Leave the selection empty to index every site visible to the connected app or account. Use a narrow selection when the workspace needs only a defined part of the tenant.

Selecting a site, library, or folder includes supported documents below it. An individual file selection includes only that file. Renaming that file or moving it inside the same library keeps it selected. A successful refresh removes it if it is deleted, access is permanently removed, or it moves to another library. A temporary Microsoft service failure does not remove the previously indexed copy.

Older SharePoint files within the selected content are included regardless of the former shared indexing start date. Existing connections that used that setting discover the missing history automatically after the upgrade. Their sites, folders, exclusions, and document permissions do not change. Follow Indexing status and testing to check progress and verify a historical file in search.

8.13 Choose document access

Access mode Search visibility Supported credentials
Public Every workspace member can retrieve indexed content Managed OAuth, Client Secret, or Certificate
Private Only supported Nous users or Portal Teams can retrieve indexed content Managed OAuth, Client Secret, or Certificate
Sync permissions Search mirrors SharePoint users, groups, inherited grants, and supported public grants Self-managed Certificate Authentication only

Choose Sync permissions when you create the connector, before indexing starts. After indexing starts, delete and recreate the connector to change from Public or Private to Sync permissions.

Once a connector uses Sync permissions, its access mode cannot change to Public or Private. Recreate the connector to leave permission sync.

SharePoint group membership refreshes about every five minutes. Document access entries refresh about every thirty minutes. The Uses source permissions badge identifies the access mode. It does not prove that a run finished. Open the connector detail page and check Last completed permission sync. Not completed yet means no successful permission sync has finished. Expand Current access in Nous to inspect a small sample of stored document access.

If SharePoint cannot return permissions for an individual folder, that folder and its subfolders retain their last synchronized folder access for the current pass. Files whose permissions can still be read continue to refresh, including files beneath those folders. A completed pass does not mean every folder’s permissions refreshed. Unreadable folders are checked again on the next pass.

New documents without synchronized permissions remain hidden. Unknown or unsupported permission entries grant no access.

Warning

Treat sharing links as public? is off by default. Enable it only when anonymous and organization-wide SharePoint sharing links should make a document searchable by every Nous workspace member.

8.14 Advanced settings

The SharePoint form provides these advanced settings:

  • Index Documents: on by default
  • Index ASPX Site Pages: off by default
  • Treat sharing links as public?: off by default
  • Excluded Sites and Excluded Paths: optional glob patterns
  • Authority Host: https://login.microsoftonline.com
  • Graph API Host: https://graph.microsoft.com
  • SharePoint Domain Suffix: sharepoint.com

For Microsoft 365 GCC High or DoD, use the hosts approved for that tenant. The current form documents https://login.microsoftonline.us, https://graph.microsoft.us, and the GCC High suffix sharepoint.us. Confirm the correct cloud with your Microsoft 365 administrator before creating the connector.

8.15 Exclude files or sites

Exclusions stop SharePoint content from being indexed when it cannot be removed or moved at the source.

  1. Open the SharePoint connector detail page.
  2. In Connector configuration, select Edit excluded paths and sites.
  3. Enter one pattern per line, such as report.pdf, *.tmp, ~$*, or Archive/*, under Excluded Paths. Matching is case-insensitive.
  4. Enter a safe site pattern such as *://*/sites/archive-* under Excluded Sites.
  5. Select Save for future refreshes, or Save and prune now to remove matching indexed copies.

Do not enter customer filenames, tenant names, private URLs, or secrets in a screenshot or example.

8.16 Verify the connector

Complete all checks before you give the connector to users:

  1. Open the site browser. Confirm the intended sites and libraries appear.
  2. Confirm Sync permissions is enabled only for a Certificate Authentication credential.
  3. Create the connector. A failed permission check must be corrected before the connector is accepted.
  4. Wait for source sync and search indexing to complete.
  5. For permission sync, wait until Last completed permission sync shows a real time.
  6. Search for a known SharePoint document as a user who has source access.
  7. Repeat the search as a user who does not have source access. The document must not appear.
  8. If sharing links are treated as public, verify that decision with a normal workspace member who has no direct SharePoint grant.

Do not treat successful site discovery as a complete access test. Site listing, document indexing, and permission sync use different Microsoft permissions.

8.17 Troubleshooting

What you see Likely cause What to do
The certificate note appears before creating the connector A self-managed Client Secret credential is selected This is a setup note. Use Public or Private, or create a Certificate Authentication credential for Sync permissions.
Sync permissions is not shown The connector uses Managed by Sophea OAuth Use Public or Private, or recreate it with a self-managed certificate credential.
Sync permissions is disabled A Client Secret credential is selected Upload the public certificate to Entra and the matching PFX to a Nous certificate credential.
“The Client ID does not match the app registration this certificate belongs to. Use the Application (client) ID of the exact Entra app registration where the public certificate was uploaded, and check the Directory (tenant) ID.” The certificate is registered on a different Entra app registration, or a wrong Client ID was entered Use the Application (client) ID of the app registration that holds the public certificate (.cer), and check the Directory (tenant) ID.
“Microsoft could not verify the certificate signature. Upload the public certificate (.cer) that matches this PFX to the Entra app registration’s Certificates list, and replace it if it expired.” The PFX private key has no matching public certificate on the app registration, or that certificate expired Upload the public certificate (.cer) that matches the PFX to the Entra app registration’s Certificates list, and replace it if it expired.
“The client secret was rejected. Paste the secret VALUE from Entra, not the secret ID; create a new secret if it expired.” The secret value is wrong or expired Paste the secret VALUE from Entra, not the secret ID; create a new secret if it expired.
No sites appear Sites.Read.All is missing or lacks admin consent Add Microsoft Graph Application Sites.Read.All, grant tenant-wide admin consent, and retry.
Site role assignments cannot be read Sites.FullControl.All is missing or was added under the wrong resource Add Office 365 SharePoint Online Application Sites.FullControl.All, grant admin consent, and retry.
Group membership cannot be read GroupMember.Read.All is missing Add Microsoft Graph Application GroupMember.Read.All, grant admin consent, and retry.
Nous rejects the upload, or reports “Failed to load the SharePoint certificate. Verify the PFX and certificate password are correct.” The file is not a PFX, is larger than 10 KB, is corrupt, does not contain an exportable private key, or the entered PFX password does not match Export a valid password-protected .pfx of 10 KB or less from the same certificate registered in Entra, and re-enter its exact password.
Nous reports that no site is available for validation The app can authenticate but no site can be discovered Select at least one site and confirm the app has access to it.
Last completed permission sync shows Not completed yet No successful permission run has completed Check the connector error state and the three required application permissions.

8.18 Rotate the certificate

Start rotation 30 to 60 days before expiry:

  1. Generate or receive the replacement certificate and matching PFX.
  2. Upload the new public certificate to the existing Entra app. Keep the old certificate active.
  3. Update the Nous certificate credential with the new PFX and password.
  4. Test site discovery, connector creation or refresh, and permission sync.
  5. Confirm Last completed permission sync advances and run the authorized and unauthorized user search checks.
  6. Remove the old certificate from Entra only after the new credential works.
  7. Remove the old PFX and password according to your secrets-retention policy.

Do not delete the old Entra certificate before Nous uses the replacement. The overlap prevents an avoidable indexing outage.

8.19 Microsoft references

For general connector lifecycle, indexing, retry, and deletion behavior, see Connectors.