1. Architecture Overview

Before we start integrating Sharepoint Online with Moveworks, We need to understand the approach Admins can follow to provide the access. Customer will need their Azure Admin to carry out the steps here.

The below sections outline what Azure API Access needs to be provided respectively for either scenario and details of how Moveworks consumes them.

File Ingestion from Sharepoint Sites

In order for Moveworks to ingest Files and their Permissions the admin needs to provide the following permissions, To Learn more about File Search please visit the guide File Search - Respecting File Permissions.

Microsoft Graph API Group

• Files.Read.All - Application Permission which is provides access to read File content inside a Sharepoint Site. Moveworks requires this access to ingest the Files.
• Group.Read.All - Application Permission which provides access to read Microsoft AD Group details to the Files in the Sharepoint Site. Moveworks requires this access to ingest Microsoft AD Groups for respecting Permissions
• 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 organisation 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: With Sites.Selected, Files.Read.All is no longer required
• User.Read - Delegated Permission which allows signed in users to Read User Profile information.
• 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.
  Note : If your organisation 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.

📘

The Sites.Read.All or Sites.Selected Permission needs to be provided to Both API Groups.

In this approach we will maintain a single Azure Application which will provide access to both SharePoint and Microsoft Graph APIs list above.
Note : You can also set up multiple Azure Applications to provide the permissions, this would mean creating extra connectors in Moveworks Setup to interface with each App

Knowledge Ingestion from Sharepoint Sites

In order for Moveworks to ingest Knowledge Articles and their Permissions the admin needs to provide the following permissions :

Microsoft Graph API Group

• Group.Read.All - Application Permission which provides access to read Microsoft AD Group details to the Files in the Sharepoint Site. Moveworks requires this access to ingest Microsoft AD Groups for respecting Permissions
• Sites.Read.All - Application Permission which provides access to read all Sharepoint Site Content across all Sites. Moveworks requires this access to ingest Knowledge Articles from all Sites.
  Note : If your organisation 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.
• User.Read - Delegated Permission which allows signed in users to Read User Profile information.
• 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 Knowledge Articles from all Sites.
  Note : If your organisation 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.

❗️

Please read the following Approach for setting up the Access Requirements

2. Azure App Registration Approach

In this approach we will maintain a single Azure Application which will provide access to both SharePoint and Microsoft Graph APIs listed above so Moveworks can leverage them via the API calls.

📘

It is Recommended to create a new Azure Application to provide the API permissions. App can be created by following the steps from the Setting Up an Azure AD App for App-Only Access section from the Microsoft Azure AD App-Only Authentication guide.

1. Ensure you have generated the App ID and App Client Credentials which will be used later to configure the connector.
2. Next we need to use the New-SelfSignedCertificate cmdlet to generate the certificates which will be used to create the Connector. In this step, you will:
   1. First generate the .pfx and .cer files using the Powershell script outlined above.
   2. Save the .pfx and .cer files for the following step.
   3. Register an Azure Application for Moveworks in your Azure AD App Directory.
   4. Connect your certificate (the .cer file) to the Application.
3. Run Powershell Commands to Generate X5t and Private Key values

   1. There are two options for generating an X5t value. Either using SHA256 (modern, more secure) or SHA1. Either option below is sufficient.

      1. For SHA256, run the following Powershell command to generate the X5t value using SHA256 needed for Moveworks’ Sharepoint Connector.

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

      2. For SHA1, run the following Powershell command, to generate the X5t value using SHA1 needed for Moveworks’ Sharepoint Connector.

         $certPath = "path\to\your\certificate.cer"
         $cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($certPath)
         
         $sha1 = [System.Security.Cryptography.HashAlgorithm]::Create("SHA1")
         $hash = $sha1.ComputeHash($cert.RawData)
         
         $x5t = [Convert]::ToBase64String($hash) -replace '\+','-' -replace '/','_' -replace '='
         
         Write-Output $x5t

   2. Save the X5t value generated to create the connector.

   3. Run the following Powershell command, to generate the Private Key needed for the Moveworks’ Sharepoint Connector.

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

   4. Save the Private Key (the privateKey.pem file) value generated for Step 3 (Create Connectors in Moveworks Setup).

4. Now we will grant the API permissions via the Azure admin portal by modifying your existing app.

   1. Go to your Microsoft Azure portal, and select Enterprise applications.

      

   2. Search for the application to which you’ll be granting the new permissions. Note down its Application ID (aka App Id).

      

   3. Navigate to this URL, replacing the end of the URL with your App Id: https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationMenuBlade/~/CallAnAPI/appId/{Application ID}

   4. This will bring you to the API Permissions page for that application. You may already see some permissions configured for this application, some of which may already be ones we need. In the image below, however, you’ll see this app only has User.Read, and that is not one of the required permissions we need, so we need to add the others.

      

   5. Click Add Permission.

      

   6. This will open a panel on the right side:

      

   7. Click on Microsoft Graph.

      

   8. Click on Application permissions.

      

   9. A search bar will appear.

      

   10. Search for the permissions you need to grant (noted above) and check the box for each.

       

   11. Once they’ve all been checked, click Add permissions.

       

   12. You’ll now see all the newly added permissions alongside any you previously had granted the app, however, the new ones will have a status of “Not granted for” your organization.

       

   13. [Important] Grant specifically the Sites.Read.All access, as Sites.FullControl.All is not necessary. Note, this must be done for the Sharepoint API during this step.

       

       1. Alternate Option: Sites.Selected (more information here)
          This permission allow you to narrow down Moveworks search to content from only SPECIFIC sub sites in the tenant. This requires additional setup, where instructions can be found here.

       2. Disclaimer: If using a GCCH Microsoft tenant, the Sharepoint permission is not available. You will want to use the Office 365 Sharepoint Online permission instead.

       3. Note: 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 settle "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

   14. To complete the process, click Grant admin consent for your organization.

       

   15. If this panel appears, click Yes, add other granted permissions to configured permissions then Save and continue, then Grant admin consent, and then Yes.

       

   16. You will see green checkmarks on the newly added permissions if this was successful.

This completes the creation of the Azure App which now has all the required API Permissions.

3. Configuring Sharepoint Integration

The below Guides will walk you through the steps of creating the Connectors in your Moveworks Setup portal, using the credentials that you have configured above and setting up Sharepoint Integration for File Search or Answers Plugin.

Note: If you have not been granted access to Moveworks Setup, please reach out to your Customer Success Team to enable this.

• How To Configure Sharepoint File Search
• How To Configure Sharepoint Answers Plugin