Architecture Overview

Your Microsoft Entra administrator must configure the app registration, credentials, and API permissions that Moveworks uses to access SharePoint Online.

The required permissions depend on whether the existing Classic configuration ingests files, knowledge pages, or both.

File ingestion from SharePoint sites

To ingest files and their permissions, grant the following permissions. For more information about access controls in File Search, see File Search: Respecting File Permissions.

Microsoft Graph API group

• Sites.Read.All: An application permission that allows Moveworks to read content across all SharePoint sites.
  • Use Sites.Selected instead to limit access to specific sites. This option requires an explicit grant for each site. Follow the Microsoft Sites.Selected setup instructions.
• Files.Read.All: An application permission that allows Moveworks to read files in SharePoint sites. It is also required to create the Microsoft Graph change-notification subscriptions used for webhooks, including when you use Sites.Selected.
• Group.Read.All: An application permission that allows Moveworks to read Microsoft Entra group details used in file permissions.
• User.Read: A delegated permission that allows signed-in users to read their profiles.
• User.Read.All: An application permission that allows Moveworks to ingest user details used to enforce permissions.

SharePoint API group

• Sites.Read.All: An application permission that allows Moveworks to read content across all SharePoint sites.
  • Use Sites.Selected instead to limit access to specific sites. This option requires an explicit grant for each site. Follow the Microsoft Sites.Selected setup instructions.

The credential workflow below uses one Microsoft Entra app registration for both the SharePoint and Microsoft Graph API permissions. If your existing configuration uses separate app registrations, complete the credential steps for each app and update the corresponding Moveworks connector.

Knowledge ingestion from SharePoint sites

To ingest knowledge pages and their permissions, grant the following permissions.

Microsoft Graph API group

• Group.Read.All: An application permission that allows Moveworks to read Microsoft Entra group details used in page permissions.
• Sites.Read.All: An application permission that allows Moveworks to read knowledge pages across all SharePoint sites.
  • Use Sites.Selected instead to limit access to specific sites. This option requires an explicit grant for each site. Follow the Microsoft Sites.Selected setup instructions.
• User.Read: A delegated permission that allows signed-in users to read their profiles.
• User.Read.All: An application permission that allows Moveworks to ingest user details used to enforce permissions.

SharePoint API group

• Sites.Read.All: An application permission that allows Moveworks to read knowledge pages across all SharePoint sites.
  • Use Sites.Selected instead to limit access to specific sites. This option requires an explicit grant for each site. Follow the Microsoft Sites.Selected setup instructions.

1. Configure the Microsoft Entra app registration

Use the app registration associated with the existing Classic connectors. The same app can provide access to both the SharePoint and Microsoft Graph APIs listed above.

Before you begin, confirm that you have:

• Access to the app registration and permission to manage its credentials and grant the required API permissions.
• Access to the existing Microsoft Graph and SharePoint Online connectors in Moveworks Setup.
• Windows PowerShell and OpenSSL, or a macOS or Linux terminal with OpenSSL.
• An approved secure location for temporary credential files.

Open or replace the app registration

1. Sign in to the Microsoft Entra admin center.
2. Go to Identity > Applications > App registrations.
3. Open the app registration used by the existing Classic connectors. If you are replacing it, select New registration, enter a name such as Moveworks SharePoint Online, and select Register.
4. On the app’s Overview page, record the Application (client) ID and Directory (tenant) ID.

Create or rotate the Microsoft Graph client secret

The separate Classic Microsoft Graph connector uses a client secret. If its current secret remains valid and you are rotating only the SharePoint certificate, continue to Generate a self-signed certificate and private key.

1. Go to Certificates & secrets > Client secrets and select New client secret.
2. Select an expiration period that follows your organization’s credential policy, and then select Add.
3. Copy the client secret Value immediately. Microsoft Entra displays it only once. You will use this value for the Classic Microsoft Graph connector.

Generate a self-signed certificate and private key

Generate these files in a location approved for temporary credential material:

• certificate.cer: The public certificate that you upload to the Microsoft Entra app registration.
• privateKey.pem: The unencrypted PKCS #8 private key that you upload to the Classic SharePoint Online connector.
• Moveworks.pfx: A password-protected export used to produce the PEM private key on Windows.

Windows

Use Windows PowerShell with the PKI module and OpenSSL installed.

1. Create an exportable 2048-bit RSA certificate that uses SHA-256. This example uses a two-year validity period. Change AddYears(2) to follow your organization’s certificate lifetime policy. CertStoreLocation must be a Windows certificate-provider path.

   1
   $cert = New-SelfSignedCertificate `
   2
     -Subject "CN=Moveworks SharePoint Online" `
   3
     -CertStoreLocation "Cert:\CurrentUser\My" `
   4
     -KeyAlgorithm RSA `
   5
     -KeyLength 2048 `
   6
     -HashAlgorithm SHA256 `
   7
     -KeyExportPolicy Exportable `
   8
     -KeySpec Signature `
   9
     -NotAfter (Get-Date).AddYears(2)

2. Export the password-protected PFX file and the public certificate. Use the certificate object returned by New-SelfSignedCertificate.

   1
   $pfxPassword = Read-Host -AsSecureString "Enter a password for Moveworks.pfx"
   2
   3
   Export-PfxCertificate `
   4
     -Cert $cert `
   5
     -FilePath ".\Moveworks.pfx" `
   6
     -Password $pfxPassword
   7
   8
   Export-Certificate `
   9
     -Cert $cert `
   10
     -FilePath ".\certificate.cer"

3. Convert the private key from the PFX file to an unencrypted PKCS #8 PEM file.

   1
   openssl pkcs12 -in ".\Moveworks.pfx" -nocerts -nodes | openssl pkcs8 -topk8 -nocrypt -out ".\privateKey.pem"

macOS or Linux

Use OpenSSL to generate a 2048-bit RSA private key and a SHA-256 self-signed certificate. This example uses a two-year validity period. Change -days 730 to follow your organization’s certificate lifetime policy.

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

Verify the certificate and private key

1. Confirm the certificate validity dates.

   Windows

   1
   $cert.NotBefore
   2
   $cert.NotAfter

   macOS or Linux

   $
   openssl x509 -in certificate.cer -noout -dates

2. Confirm that the certificate and private key belong to the same key pair. The following two commands must return the same SHA-256 digest.

   Windows

   1
   openssl pkey -in ".\privateKey.pem" -pubout -outform PEM | openssl sha256
   2
   openssl x509 -inform DER -in ".\certificate.cer" -pubkey -noout | openssl sha256

   macOS or Linux

   $
   openssl pkey -in privateKey.pem -pubout -outform PEM | openssl sha256
   $
   openssl x509 -in certificate.cer -pubkey -noout | openssl sha256

3. Confirm that privateKey.pem starts with -----BEGIN PRIVATE KEY----- and ends with -----END PRIVATE KEY-----. The header must not contain RSA or ENCRYPTED.

4. On macOS or Linux, confirm that certificate.cer starts with -----BEGIN CERTIFICATE----- and ends with -----END CERTIFICATE-----. The Windows Export-Certificate command creates a DER-encoded .cer file, so the Windows certificate does not contain PEM headers.

Upload the public certificate

1. Open the app registration in Microsoft Entra.
2. Go to Certificates & secrets > Certificates and select Upload certificate.
3. Upload the same certificate.cer file that you use to calculate the x5t value.

Generate the SHA-256 x5t value

The x5t value is the unpadded Base64URL-encoded SHA-256 digest of the certificate’s DER bytes. It is not the hexadecimal certificate thumbprint displayed in Microsoft Entra. For more information, see the Microsoft identity platform certificate credential format.

Windows

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

macOS or Linux

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

A SHA-256 x5t value contains 43 letters, numbers, hyphens, or underscores. It has no spaces, colons, or = padding. Recalculate it whenever you rotate the certificate.

1
$certPath = ".\certificate.cer"
2
$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($certPath)
3
4
$sha1 = [System.Security.Cryptography.SHA1]::Create()
5
$hash = $sha1.ComputeHash($cert.RawData)
6
$sha1.Dispose()
7
8
$x5t = [Convert]::ToBase64String($hash).TrimEnd('=').Replace('+', '-').Replace('/', '_')
9
Write-Output $x5t

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

Save the credential outputs

Grant API permissions

Grant the permissions for your use case to the app registration that you opened or created above. If the existing configuration uses separate app registrations, grant each permission to the app used by the corresponding connector.

1. In the Microsoft Entra admin center, go to Identity > Applications > App registrations and open the selected app registration.
2. Go to API permissions and select Add a permission.
3. Add the Microsoft Graph permissions:
   1. Select Microsoft Graph > Application permissions.
   2. Add the application permissions listed in the File ingestion or Knowledge ingestion section above. If the configuration supports both use cases, add the union of both sets.
   3. Select Add permissions.
   4. Select Add a permission > Microsoft Graph > Delegated permissions, add User.Read, and select Add permissions.
4. Add the SharePoint permissions:
   1. Select Add a permission > SharePoint > Application permissions.
   2. Add Sites.Read.All or Sites.Selected, matching the choice made for Microsoft Graph. Sites.FullControl.All is not required.
   3. Select Add permissions.
5. If you use Sites.Selected, follow the Microsoft Sites.Selected setup instructions to grant the app access to each selected site.
6. Select Grant admin consent for {organization}, confirm the prompt, and verify that each permission shows a granted status.

For each SharePoint group used in file or page permissions, set Who can view the membership of the group? to Everyone so Moveworks can read the group members. If you cannot change this setting, use a Microsoft Entra group or another SharePoint group whose membership is visible to the app.

This completes the app registration setup. The app now has the required API permissions and credential artifacts.

2. Update the existing Moveworks Classic connectors

In Moveworks Setup, go to Connectors > Built-in Connectors.

Microsoft Graph connector

Open the existing Microsoft Graph connector and update these fields when their corresponding credential changed.

SharePoint Online connector

Open the existing SharePoint Online connector and enter the following values.

Save both connectors. A successful credential update is confirmed when the next run of the existing ingestion completes without an authentication error.

• For File Search, open the existing configuration under Search > Configure Search > Classic Ingestion > Files.
• For knowledge ingestion, continue with How to Configure SharePoint Knowledge Ingestion.

If you do not have access to Moveworks Setup or the ingestion reports an authentication error, contact your Customer Success team.