System Overview

Microsoft 365’s SharePoint Online is your organization’s hub for sites, pages, and document libraries. From an enterprise-search perspective, it’s a primary repository of institutional knowledge and files that can be indexed to make content easily discoverable across the organization with permissions intact.

OneDrive for Business is each user’s personal file store connected to their organization account, where they can store, access, and sync their individual work files across multiple devices. It is private by default, and files are only accessible to others if the user explicitly chooses to share them.

Moveworks supports both — indexing content from SharePoint sites, so users can search the pages and documents they are authorized to view, as well as live search over the SharePoint Online sites a user has access to, serving content beyond ingestion limits.

OneDrive is currently only supported via live search (with user consent); Moveworks does not index OneDrive data.

Authentication

Authentication is accomplished by creating and registering an Azure App Registration for each of the following approaches.

• Indexing (SharePoint Online only)
  • Uses app-only access with certificate-based OAuth (JWT bearer) through an Azure App Registration.
  • You upload the cert’s public half to the app, compute the x5t (SHA-256) thumbprint, and provide the private key (PEM) to Moveworks.
  • Recommended permission model: Sites.Read.All
    • Enables full discovery and the All Sites/All except selected options in Content Selection.
  • Lesser-privilege alternative: Sites.Selected. Choose only if your security policy strictly requires it.
    • Extra admin steps required: you must grant site-specific access to the app for every site to be indexed and ensure the app can resolve site group visibility for all groups within each permissioned site (so ACLs can be read).
    • Content Selection UI impact: All Sites and All except selected are not available; you can only choose Only selected sites.
    • Files.Read.All is still required: webhook registration for near-real-time incremental ingestion depends on it. Without Files.Read.All, webhooks cannot register and ingestions run on a daily schedule (not the typical ~15-minute incremental SLA).
• Live Search (SharePoint Online & OneDrive)
  • Uses delegated OAuth with a separate Azure App Registration and client secret.
  • End users sign in and consent the first time; Moveworks then searches only the files they can access in SharePoint and OneDrive.
  • No enterprise-wide indexing of OneDrive content occurs.

A single unified connector in Moveworks collects both sets of credentials—one block for Indexing (certificate/JWT) and another for Live Search (delegated).

Permissions Enforcement

Moveworks honors native Microsoft 365 ACLs at all times.

• Indexing: Item- and site-level permissions (including group membership) are captured and enforced at query time—users only see results they’re allowed to view.
• Live Search: Results are retrieved on behalf of the signed-in user using their delegated token, so source-system permissions are inherently enforced.

API Usage

• Moveworks uses the standard Graph API v1.0 and SharePoint REST API to fetch data from SharePoint Online and OneDrive. We use application permissions with admin-granted access for indexing content and delegated permissions for live search.

Content Types

Indexing (SharePoint Online)

• Pages (modern site pages, classic wiki pages and classic publishing pages).
• Documents stored in SharePoint document libraries (including common attachments).
• Supported file formats: doc, docx, pdf, ppt, pptx, txt, aspx(pages)

Live Search (SharePoint Online & OneDrive)

• On-demand results from the signed-in user’s accessible SharePoint sites/libraries and their OneDrive files/folders. It includes Pages, Documents, Lists etc.
• Not indexed into the enterprise corpus; fetched at query time after user consent.

Coverage & Freshness

Moveworks delivers comprehensive coverage—content, metadata, identity, and permissions—and uses incremental updates for indexed content.

• Webhooks allow near-real-time incremental updates; registering them requires Files.Read.All.
• Without Files.Read.All, webhooks cannot register and updates are performed on a daily schedule.

Permission Requirements

Moveworks requires the following permissions to index SharePoint content and enforce access controls. All permissions are read-only — Moveworks never modifies content in your SharePoint environment.

SharePoint Indexing

Alternative: Sites.Selected — If your security policy does not permit Sites.Read.All, you can grant Sites.Selected on both API groups instead. This restricts Moveworks to specific sites you authorize. Trade-off: the All Sites and All except selected content scope options are unavailable. Files.Read.All is still required — webhook registration for incremental sync depends on it.

SharePoint and OneDrive Live Search

Live Search uses delegated permissions — content is fetched on behalf of the signed-in user at query time, so users only see files they already have access to.

Access Requirements

Pre-requisites

Before you get started, make sure you have everything you need:

• Admin roles
  • Global Admin permissions to create App registrations, upload certificates, and grant admin consent.
  • SharePoint Admin permissions to identify your tenant domain(s) and (if using Sites.Selected) grant per-site permissions.
• Environment details
  • Your SharePoint tenant domain(s), e.g., contoso (and contoso-eu, contoso-apc if applicable).
  • Cloud environment: Commercial or GOV L4.
• Tools (recommended)
  • PowerShell (Windows) with certificate cmdlets, or OpenSSL (macOS/Linux/Windows).
    • OpenSSL is installed by default on macOS terminals
  • PnP PowerShell if you’ll grant Sites.Selected per-site access via cmdlets.

Understanding Permissions Scopes required for Enterprise Search

SharePoint Indexing

Microsoft Graph API Group

• Sites.Read.All - Application Permission which provides access to read all SharePoint Site Content across all Sites. Moveworks requires this access to ingest Files from all Sites.
  Note : If your organization does not want to provide access to All sites, you can instead provide Sites.Selected
  • Sites.Selected - Application Permission which is an alternate option allows you to narrow down Moveworks search to content from only SPECIFIC sub sites in the tenant.
    This requires additional setup, Please ensure these instructions are followed if Sites.Selected Permission is being provided. Note: Even with Sites.Selected, Files.Read.All is still required — without it, Moveworks cannot register webhooks and incremental ingestion will not work.
• Files.Read.All - Application Permission which provides access to read File content inside a SharePoint Site. Moveworks requires this access to ingest the Files as well as register webhooks to conduct incremental sync of data.
• Group.Read.All - Application Permission which provides access to read Microsoft AD group details for the files in the SharePoint Site. Moveworks requires this access to ingest Microsoft AD groups in order to respect permissions.
• User.Read.All - Application Permission which allows access to read all user information in the tenant. Moveworks requires this access to ingest user details from the Azure tenant which will be used to respect permissions

SharePoint API Group

• Sites.Read.All - Application Permission which provides access to read all SharePoint Site Content across all Sites. Moveworks requires this access to ingest Files from all Sites. As with the Microsoft Graph API group above, you can instead provide Sites.Selected to narrow ingestion to specific sites — see the note there for the additional setup required.

In this approach we will maintain a single Azure Application which will provide access to both SharePoint and Microsoft Graph APIs listed above.

SharePoint and OneDrive Live Search

Microsoft Graph API Group

• Files.Read.All: lets Moveworks read files the user already has access to in OneDrive and SharePoint document libraries, so it can surface relevant results.
• Sites.Read.All: lets Moveworks read site pages and list items the user can access in SharePoint Online.
• User.Read: identifies the signed-in user.
• offline_access: allows Moveworks to store a refresh token so the user doesn’t have to re-consent every time they search.

In this approach we will again maintain a single Azure Application which will provide access to Microsoft Graph APIs listed above but will be a different application than the Indexed one.

Instructions for SharePoint Indexing — App-only with certificate/JWT

1. Register a new App

1. Sign in to the Azure portal.
2. Select Microsoft Entra ID > Manage > App registrations > New registration.
3. On the Register an application page, register an app with the following details

   Field	Value
   Name	Moveworks
   Supported account types	Accounts in this organizational directory only (Single tenant)
   Redirect URI	Leave this field empty

4. From the overview page, note down the following values:
   1. Directory (tenant) ID
   2. Application (client) ID

2. Add Application API permissions & grant Admin consent

1. Open the App Registration you created above and click on Manage > API Permissions.
2. Click Add a permission.
3. This will open a panel on the right side:
   
4. Select Microsoft Graph.
5. Choose Application permissions :
   
6. A search bar will appear:
   
7. Search for the permissions you need to grant(noted above) and check the box for each:
   
8. Once they’ve all been checked, click Add permissions
9. Repeat the steps again by clicking on Add a permission button and selecting SharePoint.
   
10. Similar to the previous steps, select Application permissions.
    
11. Select either Sites.Read.All or Sites.Selected based on your requirements (noted above) and click on Add permissions after selecting all scopes.
12. You’ll now see all the newly added permissions will have a status of “Not granted for” your organization.
13. To complete the process, click Grant admin consent for your organization
14. If this panel appears, click Yes, add other granted permissions to configured permissions then Save and continue, then Grant admin consent, and then Yes.
15. You will see green checkmarks on the newly added permissions if this was successful.
16. Note for all Sites you are trying to configure within Moveworks:
    For each SharePoint Group, it must have the following setting in order for members of those SharePoint groups to access the files (unless they have access via another SharePoint Group, or Azure AD Group):
    1. Within “Group Settings”, the setting “who can view the membership of this group” must be set to “Everyone”, in order for Moveworks to read the group members
    2. If it’s not set, please change the setting, or rely on Azure AD Groups or other SharePoint Groups to manage permissions for those files

3. Generate a self-signed certificate and private key

You need:

• Public certificate (.cer) — upload to the app.
• Private key (privateKey.pem) — uploaded later in Moveworks.

Windows (PowerShell)

1. Create a 2048-bit RSA, SHA-256 self-signed cert (exportable) with 2-year validity (replace the CertStoreLocation with your desired location)

   1
   $cert = New-SelfSignedCertificate `
   2
     -Subject "CN=Moveworks" `
   3
     -CertStoreLocation "C:\path\to\your\folder" `
   4
     -KeyAlgorithm RSA -KeyLength 2048 -HashAlgorithm SHA256 `
   5
     -KeyExportPolicy Exportable -KeySpec Signature `
   6
     -NotAfter (Get-Date).AddYears(2)
   
   
2. Export the .pfx (choose a password) and .cer

   1
   $pwd = Read-Host -AsSecureString "Enter PFX password"
   2
   Export-PfxCertificate -Cert "C:\path\to\your\file\$($cert.Thumbprint)" `
   3
     -FilePath ".\Moveworks.pfx" -Password $pwd
   4
   Export-Certificate -Cert "C:\path\to\your\file\$($cert.Thumbprint)" `
   5
     -FilePath ".\certificate.cer"
   
   
3. Export the private key (PEM) from Moveworks.pfx

   openssl pkcs12 -in "C:\path\to\your\file\Moveworks.pfx" -nocerts -nodes -out "C:\path\to\output\file\privateKey.pem"
   
   

macOS/Linux (OpenSSL)

1. Generate Private key + self-signed cert with 2 years validity

   $
   openssl req -x509 -newkey rsa:2048 -nodes \
   >
     -keyout privateKey.pem -out certificate.cer \
   >
     -days 730 -subj "/CN=Moveworks"

Verify that both certificate.cer and privateKey.pem are generated successfully in the desired location. Open each file, and ensure the files conform to the following formats:

• The certificate file must start with BEGIN CERTIFICATE and end with END CERTIFICATE
• The private key should begin with BEGIN PRIVATE KEY and end with END PRIVATE KEY.
  • It must not include RSA in the headers, nor be encrypted.

Store the private key in a safe storage since this will be used later to create the connector in Moveworks

4. Bind the cert to the app

• Navigate to the App you created above -> Certificates & secrets -> Certificates -> Upload certificate -> upload the certificate.cer file.

5. Compute x5t (SHA-256)

Windows (PowerShell)

1
$certPath = "path\to\your\certificate.cer"
2
$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($certPath)
3
4
$sha256 = [System.Security.Cryptography.HashAlgorithm]::Create("SHA256")
5
$hash = $sha256.ComputeHash($cert.RawData)
6
7
$x5t = [Convert]::ToBase64String($hash) -replace '\+','-' -replace '/','_' -replace '='
8
9
Write-Output $x5t

macOS/Linux (OpenSSL)

$
openssl x509 -in certificate.cer -outform der \
>
  | openssl dgst -sha256 -binary \
>
  | openssl base64 -A \
>
  | tr '+/' '-_' | tr -d '='

1. Note down the x5t token value from the terminal output

Instructions for SharePoint and OneDrive Live Search — Delegated with client secret

1. Register a new App

1. Sign in to the Azure portal.
2. Select Microsoft Entra ID > Manage > App registrations > New registration.
3. On the Register an application page, register an app with the following details

   Field	Value
   Name	Moveworks - Live Search
   Supported account types	Accounts in this organizational directory only (Single tenant)
   Redirect URI	Web -> https://{org}.moveworks.com/auth/oauthCallback

Note:

Ensure the Redirect URI is a Web application, and when specifying the Redirect URI, include your specific sub-domain for MyMoveworks.

https://{org}.moveworks.com/auth/oauthCallback — for US orgs

Make sure to replace the {org} with your specific sub-domain.

If you have a sandbox MyMoveworks environment, please configure an additional URL for that too:

1. On the Home page of the Application you just created, click on the Redirect URIs link
   
2. On the page that opens, click on the Add Redirect URI button to add an additional URI
   
3. Select Web
   
4. Enter the URL for your sandbox MyMoveworks environment and click on Configure.

   https://{org}-sandbox.moveworks.com/auth/oauthCallback — for US orgs

   
   
5. You should now see both of your MyMoveworks URIs configured on this page.
   

2. Setup API Permissions

1. Go to API Permissions to add the required MS Graph Permissions:
2. Click on Add a permission button. This will open a panel on the right side
3. Select Microsoft Graph.
4. Choose Delegated Permissions.
   
5. Ensure the following Delegated Permissions are added to the application.
   1. Files.Read.All: lets Moveworks read files the user already has access to in OneDrive and SharePoint document libraries, so it can surface relevant results.
   2. Sites.Read.All: lets Moveworks read site pages and list items the user can access in SharePoint Online.
   3. User.Read: identifies the signed-in user.
   4. offline_access: allows Moveworks to store a refresh token so the user doesn’t have to re-consent every time they search.
6. Click on Add permissions after selecting all of the above permission scopes.
7. Verify that all 4 permission scopes are present under Configured permissions.
8. Click on the Grant admin consent for your-org button to make sure all permissions are available for all users to grant access.
   
9. If this panel appears, click Yes, add other granted permissions to configured permissions then Save and continue, then Grant admin consent, and then Yes.
10. You will see green checkmarks on the newly added permissions if this was successful.
    

3. Generate Client Secret

Next, we will need to create a Client Secret for the Registration to connect it to Moveworks.

1. Navigate to the App you created above -> Certificates & secrets
   
2. Click on New client secret button. This will open a panel on the right side.
   
3. Set the description and expiry of this credential based on your org’s policy and click on Add.
4. This will create a new entry on the Client secrets table
5. Make sure to copy the secret present in the Value column and store it in a secure location. Note: Once you create the Secret, make sure to save it right now as it cannot be recovered later.
   
6. Go back to the Overview page, to capture the following details:
   1. Directory (tenant) ID
   2. Application (client) ID
   
   

Setup in Moveworks

Connector Creation

1. Log in to your org’s MyMoveworks portal
2. Navigate to Moveworks Setup > Connectors > Built-in Connectors
3. Click Create New
4. Search and Select SharePoint & OneDrive (Next Gen)
5. Click on Next: Add Creds
6. Input the following details
   1. Connector Name : Name this connector for your future reference. Once set, this name cannot be changed.
   2. Tenant (directory) ID: Enter your Microsoft Entra (Azure AD) tenant ID that uniquely identifies your organization.
   3. Tenant Domains: Enter all the SharePoint tenant domains to ingest data from across the organization, if you have multiple geo-locations configured. Eg: Enter org1 for domain_url org1.sharepoint.com and org2 for domain_url org2.sharepoint.com
   4. Region (optional): Select an option that will be used to establish the base URL. If no selection is made, the default option will be Commercial. If GOV L4 is selected, a .us token URL will be created.
   5. Application (client) ID: Enter the Application (client) ID from your Indexing Microsoft Entra app registration’s Overview page, used for certificate-based authentication.
   6. X.509 Certificate SHA-1/SHA-256 Thumbprint (x5t): Enter the SHA-256 thumbprint of your uploaded certificate from Microsoft Entra, used to verify certificate authenticity (format: hexadecimal string without colons or spaces).
   7. Private Key: Upload the private key as a PEM file that corresponds to the certificate uploaded to your Microsoft Entra app registration.
   8. Application (client) ID: Enter the Application (client) ID from your Live Search Microsoft Entra app registration for delegated/user-consent authentication.
   9. Application Client Secret: Enter the client secret value from your Live Search Microsoft Entra app registration for delegated/user-consent authentication.
   10. Click Save. This connector will now be used to configure content ingestion from SharePoint Online and enable live search from OneDrive. Refer to the steps mentioned below.

Configuring SharePoint Online and OneDrive for Enterprise Search

Initialising setup

1. Log in to your org’s MyMoveworks portal
2. Navigate to Moveworks Setup > Search > Configure Search > Max Capacity
3. Click on Create New or Get Started
4. Select SharePoint Online & OneDrive from the dropdown list and click on Get Started
5. You will be redirected to the SharePoint Online & OneDrive ingestion overview page. On the overview page, you will find a few info blocks and a few configuration blocks.
   1. System Overview: This presents an overview of SharePoint Online & OneDrive support from Moveworks
   2. Ingestion Summary: This provides information on the count of records that have been ingested and are being served. The values will appear after the first successful ingestion run.
   3. Connector Selection: In this configuration block, you select the connector and choose one or more retrieval methods: SharePoint Online: Enable Live Search (Instant), SharePoint Online: Add Sites, and/or OneDrive: Enable Live Search (Instant).
   4. Content Selection: In this configuration block, you are required to define the content that should be ingested within Moveworks
   
   

Connector selection and validation

SharePoint Online and OneDrive are configured through a single connector, but on the connector-selection screen you choose one or more retrieval methods. Select the methods that match how you want employees to search, validate each one, and then save.

The retrieval methods

Which methods to choose

SharePoint Online — do you need to control exactly what Moveworks makes searchable?

• Yes, control what is ingested: select Add Sites and choose the specific sites to ingest. Do not also enable SharePoint Live Search — Live Search queries across all SharePoint content the signed-in user can access, so it would return results beyond the sites you scoped.
• No, employees should be able to search broadly right away: select Enable Live Search so employees can search SharePoint immediately, with nothing stored in Moveworks. You can optionally also Add Sites for a selected set of sites to get higher-quality search over that content. Live Search and Add Sites can be used together.

OneDrive — do you want personal OneDrive files to be searchable?

• Yes: select Enable Live Search. This is the only method for OneDrive; Moveworks does not index OneDrive content.

Steps

1. Click Select Connector, then choose the connector you created in the Connector Creation step.

   Please note: Only the SharePoint & OneDrive (Next Gen) connectors will appear in this list.

2. Under Select and combine one or more required method(s), choose any combination of SharePoint Online: Enable Live Search (Instant), SharePoint Online: Add Sites, and OneDrive: Enable Live Search (Instant). Each selected method must be validated before you can save.

   
   

3. For Add Sites (indexing): click Start Validation — Add Sites has no Authorize step. In the Connector validation dialog, enter a Site URL (for example, https://{tenant}.sharepoint.com/sites/{sitename}) and click Validate.

   
   
   Connector Validation is mandatory before you can save. For Add Sites, Moveworks validates:

   • Auth — the connector can authenticate
   • Content — the connector has the scopes to fetch content
   • Permissions — the connector has the scopes to fetch user permissions
   • Users — the connector has the scopes to fetch user data
   • Groups — the connector has the scopes to fetch Microsoft 365 groups data
   • Site Groups — the connector has the scopes to fetch site-group data from the specified site

   All checks must pass. If any fail, click View Details and see Troubleshooting Connector Validation Failures.

   On success, the method shows Connector validated successfully, with View Details and Re-Validate available.

   
   

4. For Enable Live Search (SharePoint and/or OneDrive): click Authorize, sign in with your Microsoft user, and approve the app. You are redirected back to Moveworks Setup, where you click Start Validation. Live Search validation checks a single Content scope (the delegated read) rather than the six checks used by Add Sites.

   
   

   

   
   

5. Every selected method must validate successfully before Save is enabled.

6. Enter a unique configuration name (optionally add a change summary) and click Save.

   
   
   At this stage, only the configuration entry is created. Ingestion does not start until you configure the Content Selection step, and ingested content is not served in search until you configure the Audience step. Live Search does not use Content Selection — enable Live Search on the configuration’s home page and configure the Audience step so results are served.

7. After saving, the configuration’s home page shows the saved method(s) — for example, SharePoint Online (With Live Search). For Live Search, click Enable Live Search to deploy it for your organization, and use Select Audience to choose who can search. You can rename the configuration with the pencil 🖊️ icon, or click Modify on a block to change it.

   
   

8. You will also see your configuration in the Connected Systems list on the Max Capacity page (Search → Configure Search → Max Capacity). Click it to edit or complete the configuration.

   
   

Content Selection

Once the connector selection step is complete and the configuration is saved, you will now be required to define the scope of content that will be ingested in Moveworks.

1. Once you click on Select Content, a content selection screen will appear as follows.
   
2. In this screen, you are required to define the Site URLs from which Moveworks will ingest content and apply filters (optionally) to filter down the content further.
3. SharePoint Site Selection: This is a mandatory configuration. This configuration defines which Sites Moveworks will crawl and ingest content from. As an admin, you get three options
   

   1. Only selected Sites(s) (Recommended): Moveworks will only ingest content from specified Site URLs.

      When to choose this option? Choose this option if you want content to be served only from a subset of Site URLs. For example - Let’s assume, the Azure App has access to 15 Sites or All Sites, but you want content to be served only from 5 Sites, then you choose this method.

      How to configure? Enter comma separated Site URL(s).

   2. All except selected: Moveworks will ingest content from all Sites except the specified ones.

      When to choose this option?

      Choose this option if you want content to be served from all except a few Sites. For example - Let’s assume, the Azure App has access to All 100 Sites, but you want content to be served from 96 Sites, then you choose this method and specify the 4 Site URLs from which Moveworks should not ingest.

      Important Note: The Azure App must be configured with Sites.Read.All permission scope to enable selecting this option.

      How to configure? Select this option and enter comma separated Site URL(s).

   3. All Sites: Moveworks will ingest content from all applicable Sites

      When to choose this option?

      Choose this option if you want content to be served from All Sites within your SharePoint tenant. For example - Let’s assume, your SharePoint tenant contains 100 Sites, and you want content to be served from all 100 Sites, then you choose this method.

      Important Note: The Azure App must be configured with Sites.Read.All permission scope to enable selecting this option.

      How to configure? Select this option. You are not required to specify the Site URLs in this scenario.

4. Additional Filters: Use these filters to narrow the content ingestion scope further. Only records matching ALL of the specified criteria will be included.
   This is an optional configuration. Moveworks recommends using these filters only if your dataset is very large (i.e. >1million records) so that only relevant content is ingested and served to your employees.

   Currently following filters are supported:
   1. Modified date: Use this filter to include only those content records whose Modified date is after a specified date.
   2. Created date: Use this filter to include only those content records whose Created date is after a specified date.

Save and Start Ingestion

Once content selection is configured, you have two options:

• Save: Clicking this will just save the configuration and not initiate the first ingestion crawl. Use this option, if you would want to complete your configuration in multiple sessions/ sittings.

  • Once you click on Save, you will be redirected to the SharePoint Online & OneDrive overview screen
  • You will notice a banner that prompts you to Start Ingestion
    
  • Once you are satisfied with your configuration, you can click on Start Ingestion
  • A confirmation popup will come that provides a summary of the configuration
    
  • Click on Confirm
  • After you click on Confirm, ingestion will start shortly.
  • For the first crawl to complete, this generally takes anywhere from few hours to 48 hours depending upon the size of the data.

• Save and Start Ingestion: Click this option if you have completed and validated your content selection configuration and you are ready to initiate the first ingestion crawl.

  • A confirmation popup will come that provides a summary of the configuration
    
  • Click on Confirm
  • After you click on Confirm, ingestion will start shortly.
  Important Note for Admins:

  • It generally takes anywhere from few hours to 48 hours for the first crawl to complete depending upon the size of the data.
  • You can review the status of ingestion via Data Ingestion Viewer and view ingested record in the Indexed Content > Files and Indexed Content > Internal Knowledge screens.

Audience configuration

A configuration does not serve content in search until you set its audience. From the configuration’s home page, open the Target audience tab, choose who can search this content, and save — source permissions are always enforced on top of your selection.

Audience configuration is the same for every Max Capacity connector. For the full steps and options, see Step 4: Define Target Audience in the Max Capacity Setup overview.

Known Limitations

The items below are known constraints we are actively working on. Each includes the current way forward.

• SharePoint Multi-Geo tenants. Microsoft Graph does not support change-notification webhooks for sites on non-root geo domains (for example, contoso-eu.sharepoint.com). If your tenant uses SharePoint Multi-Geo, reach out to Moveworks for additional configuration so content on those domains stays in sync.

Troubleshooting Connector Validation Failures

Validation errors can occur when setting up a SharePoint Online or OneDrive connector. This guide helps you diagnose and resolve common issues.

Primary Validation Errors:

1. “Validation failed: Invalid credentials or missing required permissions”
2. “Invalid URL schema” - Base URL must use HTTPS protocol
3. “Host name is not safe or valid” - The SharePoint domain cannot be resolved or is blocked
4. “Failed to find connector action data” - Required configuration fields are missing or empty

Root Causes

The guide outlines potential causes by authentication method:

Server-to-Server Authentication Issues:

1. Application not registered - The Azure AD application hasn’t been created or registered in Microsoft Entra
2. Missing API permissions - Application lacks required SharePoint permissions (Sites.Read.All or Sites.Selected or Files.Read.All etc)
3. Certificate issues - Invalid certificate thumbprint, expired certificate, or private key format errors
4. Tenant ID mismatch - The provided Tenant ID doesn’t match the SharePoint tenant
5. Admin consent not granted - API permissions haven’t been approved by a Global Administrator

User-Consent Authentication Issues:

1. Invalid Client Secret - The client secret has expired or is incorrect
2. Missing delegated permissions - OAuth application lacks either Sites.Read.All or Files.Read.All or both the delegated permissions
3. Refresh token expired - User needs to re-authenticate

Configuration Issues:

1. Invalid tenant domain - Domain doesn’t match the SharePoint site (e.g., “contoso” for contoso.sharepoint.com)
2. Wrong region selected - Must choose “Commercial” for standard tenants or “GOV L4” for government clouds
3. Private key format - Private key file must be in PEM format
4. Empty required fields - Tenant domains list is empty or Client ID is missing

Resolution Approach

Follow these steps in sequence to diagnose and resolve validation failures:

Step 1: Verify Base Configuration

Check the fundamental connector settings:

• Confirm Tenant ID matches your Microsoft Entra tenant (found in Azure Portal → Azure Active Directory → Overview)
• Verify Tenant Domain is correct (e.g., “contoso” if your SharePoint URL is https://contoso.sharepoint.com)
• Confirm Region selection:
  • “Commercial” for standard Microsoft 365 tenants
  • “GOV L4” for US Government GCC High tenants
• Validate at least one tenant domain is provided

Step 2: Verify Azure AD Application Registration (Server-to-Server Auth)

For certificate-based authentication:

1. Confirm application exists:
   • Navigate to Azure Portal → Azure Active Directory → App registrations
   • Search for your application by Client ID
   • Verify the Application ID matches the Client ID in your connector configuration
2. Check API permissions: Required Microsoft Graph permissions mentioned above - Understanding Permissions Scopes required for Enterprise Search
3. Verify admin consent:
   • In the application’s API permissions page, check the “Status” column
   • Should show “Granted for [Your Organization]”
   • If not granted, click “Grant admin consent” (requires Global Administrator role)
4. Validate certificate configuration:
   • Navigate to Certificates & secrets → Certificates
   • Verify a certificate is uploaded and not expired
   • Confirm the SHA-256 Thumbprint matches the certificate_sha256_x5t_fingerprint in your connector config
   • Thumbprint format should be: uppercase hex string without colons (e.g., “A1B2C3D4E5…”)

Step 3: Verify Private Key Format

The private key must be in PEM format:

-----BEGIN PRIVATE KEY-----
[Base64 encoded key data]
-----END PRIVATE KEY-----

Common issues:

• Wrong format: Key must be PEM, not PFX, CER, or DER
• Missing headers: File must start with -----BEGIN PRIVATE KEY-----
• Line breaks: Ensure proper line breaks in the base64 content
• Encryption: Use unencrypted PEM files (not password-protected)

To convert from PFX to PEM:

$
# Extract private key from PFX file
$
openssl pkcs12 -in certificate.pfx -nocerts -nodes -out private-key.pem

Step 4: Test OAuth Credentials (User-Consent Auth)

For the Live Search (user-consent) OAuth application:

1. Verify Client ID and Secret:
   • Navigate to Azure Portal → App registrations → Your App
   • Confirm the Application (client) ID matches your configuration
   • Check Certificates & secrets → Client secrets
   • If secret is expired, generate a new one
2. Test token acquisition: Use Microsoft Graph Explorer or curl to test authentication:

   $
   curl -X POST https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token \
   >
     -d "client_id={client-id}" \
   >
     -d "client_secret={client-secret}" \
   >
     -d "scope=https://graph.microsoft.com/.default" \
   >
     -d "grant_type=client_credentials"
   Should return an access token if credentials are valid.

Step 5: Verify SharePoint Access Permissions

1. Test application can access SharePoint sites:
   • Use Microsoft Graph Explorer (https://developer.microsoft.com/graph/graph-explorer)
   • Authenticate with your service principal or test user
   • Try query: GET https://graph.microsoft.com/v1.0/sites/{site-id}
2. Check site permissions:
   • Navigate to SharePoint Admin Center → Active sites
   • Select a site and check site permissions
   • For app-only access, verify the application has access to required sites

Step 6: Validate URL Accessibility

The connector validates that the SharePoint instance is accessible:

1. HTTPS requirement:
   • All URLs must use https:// (HTTP is rejected for security)
   • SharePoint Online always uses HTTPS
2. Network accessibility:
   • Ensure the SharePoint domain resolves to public IPs (not internal/private addresses)
   • The connector blocks connections to private IP ranges for security
3. Firewall rules:
   • If using on-premise proxy, verify firewall allows outbound connections to SharePoint Online
   • Check corporate proxy/firewall rules

Step 7: Advanced Troubleshooting

If issues persist after completing steps 1-6:

1. Check Azure AD audit logs:
   • Azure Portal → Azure Active Directory → Audit logs
   • Filter by application ID to see authentication attempts
   • Look for failed sign-in events or permission errors
2. Review SharePoint audit logs:
   • SharePoint Admin Center → Audit log search
   • Search for activities by the service principal
   • Check for access denied events
3. Validate certificate-key pair:
   • Ensure the private key matches the certificate uploaded to Azure AD
   • Test by using the same certificate/key pair with Azure CLI:

   $
   az login --service-principal \
   >
     -u {client-id} \
   >
     -p {path-to-pem-file} \
   >
     --tenant {tenant-id}
4. Test API directly: Use the Microsoft Graph API to test access with your credentials:
   • Get access token using certificate-based auth
   • Test endpoints:
     • GET https://graph.microsoft.com/v1.0/sites?search=* (list all sites)
     • GET https://graph.microsoft.com/v1.0/sites/{site-id}/drive/root/children (list documents)