Microsoft SharePoint Online Setup

Before the connector can traverse content from SharePoint Online, a few things need to be set up in the source system.

Microsoft Azure App Registration

The SharePoint Online connector uses the Microsoft Graph and SharePoint Rest API. In order to authenticate against both APIs a single Microsoft Azure application can be registered. The following steps describe how to create such an Azure application.

Visit the Azure Portal and login as a tenant administrator
Go to App registrations
Register an application and follow the instructions. Supported account types should be Accounts in this organizational directory only. A redirect URL is neither needed nor supported.
Configure the following Application API permissions:
- Microsoft Graph
  - Group.Read.All
  - User.Read.All
  - Sites.Read.All (Optional)
- SharePoint
  - Sites.FullControl.All or Sites.Selected
Grant admin consent for your tenant.
Go to Certificates & secrets and upload a certificate.
Use the Application (client) ID and Directory (tenant) ID from the overview tab to configure the connector.

See Certificate File Generation for a guide on how to generate a certificate.

The permission Sites.Read.All is required to perform an auto site discovery. If all sites should be defined manually, this permission can be left out.

When using Sites.Selected see Permission: Sites.Selected for a guide on how to set the required permissions per site.

API Permissions

The following Application API permissions are required by the connector:

Microsoft Graph API

Permission Name Description

Permission Name	Description
`Group.Read.All`	Permission to read Azure AD groups. Used in the principal synchronization to list all Azure AD groups and their members.
`User.Read.All`	Permission to read Azure AD users. Used in the principal synchronization to list all Azure AD users.
`Sites.Read.All`	Permission which grants read access on all site collections in a tenant via the Microsoft Graph API. The connector uses this permission in case auto site discovery is enabled, to determine the starting points for the traversals.

Group.Read.All

Permission to read Azure AD groups. Used in the principal synchronization to list all Azure AD groups and their members.

User.Read.All

Permission to read Azure AD users. Used in the principal synchronization to list all Azure AD users.

Sites.Read.All

Permission which grants read access on all site collections in a tenant via the Microsoft Graph API. The connector uses this permission in case auto site discovery is enabled, to determine the starting points for the traversals.

SharePoint API

Permission Name Description

Permission Name	Description
`Sites.FullControl.All` or `Sites.Selected`	Permission to read the content, metadata and security information for all types of content contained in selected site collections. In case auto site discovery is enabled and the Microsoft Graph API permission `Sites.Read.All` is set, only the selected sites are traversed. Every site the application does not have access to via the SharePoint API, is ignored. `Sites.FullControl.All` Provides full control on all site collections. This enables to read content, metadata and security information for all types of content contained in all site collections of the tenant. `Sites.Selected` Indicates, that the Azure application has only permissions on dedicated site collections via the SharePoint API. A tenant administrator has to provide `FullControl` permissions for sites which should be traversed. See Permission: Sites.Selected on how to configure these site collection specific permissions.

Sites.FullControl.All
or
Sites.Selected

Permission to read the content, metadata and security information for all types of content contained in selected site collections. In case auto site discovery is enabled and the Microsoft Graph API permission Sites.Read.All is set, only the selected sites are traversed. Every site the application does not have access to via the SharePoint API, is ignored.

Sites.FullControl.All
Provides full control on all site collections. This enables to read content, metadata and security information for all types of content contained in all site collections of the tenant.

Sites.Selected
Indicates, that the Azure application has only permissions on dedicated site collections via the SharePoint API. A tenant administrator has to provide FullControl permissions for sites which should be traversed. See Permission: Sites.Selected on how to configure these site collection specific permissions.

To enable secure search, the connector fetches and resolves Microsoft SharePoint Online specific security information (role assignments). The Microsoft endpoints, which provide these information, require Sites.FullControl.All / FullControl Azure application permission. Read, Write or Manage permissions do not suffice.

Permission: Sites.Selected

The 'Sites.Selected' permission allows to set specific Azure Application permissions per site collection. For each site collection to be traversed by the connector, the permission must be set via a PowerShell script.

Install PnP PowerShell module to be able to connect to SharePoint Online via the PowerShell:
```
Install-Module PnP.PowerShell.ps1
```
Establish a connection to SharePoint Online
```
Connect-PnPOnline
```
1. Enter the URL to the tenant to connect to:
  Url: https://<domain>.sharepoint.com
Full control permission need to be specified for every site collection, which the connector will traverse. First provide Write permission to the cmdlet. See Grant-PnPAzureADAppSitePermission for further information.
<appId>: The application id of the registered Azure app for the connector.
<name>: The display name of the registered Azure app.
```
Grant-PnPAzureADAppSitePermission -AppId '<appId>' -DisplayName '<name>' -Permissions Write
```
Note the permission id found in the response of the command above. This id is required for the next step.
Set FullControl for the selected site. See Set-PnPAzureADAppSitePermission for further information.
<permissionId>: The id which is part of the response of the previous command.
<siteUrl>: The URL to the selected site. Example: https://<domain>.sharepoint.com/sites/test
```
Set-PnPAzureADAppSitePermission -PermissionId <permissionId> -Permissions FullControl -Site <siteUrl>
```
Repeat the previous step for each site which shall be traversed by the connector.

In order to revoke an Azure application site permission, the Revoke-PnPAzureADAppSitePermission command can be used:

Revoke-PnPAzureADAppSitePermission -PermissionId <permissionId> -Site <siteUrl>

Set Permissions for Multiple Site Collections

To grant or revoke FullControl permissions for multiple site collections in one go, the connector includes a PowerShell script located within the scripts folder. This script is designed to streamline the process by accepting a text file containing the URLs of the target site collections, with each URL listed on a separate line.

Prior to utilizing this script, it is required to ensure that the PnP PowerShell Module is installed. Detailed instructions for installing this module can be found in the preceding section.

To grant or revoke FullControl permission to multiple site collections, follow these steps:

Open a PowerShell console and change directory to the script’s folder location.
Run the PowerShell script:
```
.\Set-SitePermissions.ps1
```
If the Execution Policy denies the execution, it can be bypassed by:
```
powershell -ExecutionPolicy Bypass -File .\Set-SitePermissions.ps1
```
Supply the values required for the script parameters:
- ApplicationId - Application ID of the Azure Application used to authenticate the connector.
- ApplicationDisplayName - Display name of the Azure Application used to authenticate the connector.
- Username - Username for the connection to the Azure tenant.
- Password - Password for the connection to the Azure tenant.
- FilePath - Path to the text file containing the site collection URLs to change.
- Permissions - Select grant or revoke action for FullControl permission to the selected sites.

All parameters can be set using the command line. Use the PowerShell Get-Help cmdlet to display more information about the script:

Get-Help .\Set-SitePermissions.ps1 -Full

Certificate File Generation

The connector provides a PowerShell script to create a self-signed certificate used for application authentication to the server. It can be found in the scripts folder of the connector.

Open a PowerShell console as administrator and change directory to the script’s folder location.
Run the PowerShell script:
```
.\CreateSelfSignedCertificate.ps1
```

If the Execution Policy denies the execution, it can be bypassed by:

powershell -ExecutionPolicy Bypass -File .\CreateSelfSignedCertificate.ps1

Enter a name for the certificate.
Define a date range in which the certificate should be valid. The required format is: yyyy-mm-dd.
Enter a password for the certificate. The password is required later to configure the connector.
Two files will be generated. The private key PFX file will be used to configure the connector and the public key CER file to configure the Azure application.