# SharePoint Connector ## Overview The SharePoint connector retrieves pages and files from SharePoint Online and on-premises installations as Knowledge Base Articles. ## Prepare The authentication method for this connector depends on your intended use case. Before following the section for your environment, collect your SharePoint endpoint. ### Endpoint You will need the root URI for your SharePoint tenant. This takes the following format: ``` .sharepoint.com ``` Do not include the protocol (`http` or `https`). ### Generate a certificate If you are using Basic authentication, generate a certificate and private key pair before completing the Basic section below. OAuth authentication does not require a certificate. Generate a self-signed certificate using OpenSSL: ```bash # Generate private key (PKCS#8 format) openssl genpkey -algorithm RSA -out private-key.pem -pkeyopt rsa_keygen_bits:2048 # Generate certificate signing request openssl req -new -key private-key.pem -out csr.pem \ -subj "/CN=SharePoint-App-Auth/O=YourOrg/C=US" # Generate self-signed certificate (valid 2 years) openssl x509 -req -days 730 -in csr.pem \ -signkey private-key.pem -out certificate.pem # Generate CER file for Azure AD upload openssl x509 -in certificate.pem -outform DER -out certificate.cer ``` {% hint style="warning" %} The private key must be in PKCS#8 format — the file must begin with `-----BEGIN PRIVATE KEY-----`. If it begins with `-----BEGIN RSA PRIVATE KEY-----`, convert it before proceeding: ```bash openssl pkcs8 -topk8 -nocrypt -in pkcs1-key.pem -out private-key.pem ``` {% endhint %} {% hint style="warning" %} Keep `private-key.pem` secure. Do not commit it to version control or share it via email or chat. The private key is not password-protected in this configuration. {% endhint %} ### OAuth SharePoint Online supports OAuth 2.0 with the Microsoft Graph API. Use this option if you are connecting to SharePoint Online and do not need to ingest User Profile data. Authentication is managed through an Azure AD application registered in Microsoft Entra ID. #### **Register an Azure AD application** Register a new application in Microsoft Entra ID. See Microsoft's guide to [Registering an application in Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app). When registering your application, set the Redirect URI to: ``` https://.login.aisera./?id=aisera.oauth.oauthCommand ``` After registration, note your **Client ID** and **Tenant ID** from the application's Overview page. #### **Add Microsoft Graph API permissions** In **API permissions**, select **Add a permission > Microsoft Graph** and choose **Delegated permissions**. Add the following permissions and grant admin consent for each: ``` Sites.Read.All Files.Read.All Directory.Read.All Group.Read.All ``` #### **Create a Client Secret** Create a **Client Secret** for your application. See Microsoft's guide to [Add and manage application credentials in Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-credentials?tabs=client-secret#add-a-credential-to-your-application). {% hint style="warning" %} The client secret value appears only once and is not retrievable after you navigate away from the page. Copy it before leaving. {% endhint %} #### **Retrieve your Access Token URL and Authorization URL** Your **Access Token URL** takes the following format: ``` https://login.microsoftonline.com//oauth2/v2.0/token ``` Your **Authorization URL** takes the following format: ``` https://login.microsoftonline.com//oauth2/v2.0/authorize?scope=offline_access%20Sites.Read.All%20Files.Read.All%20Directory.Read.All ``` See Microsoft's [OAuth 2.0 Endpoints documentation](https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols#endpoints) for more information. #### **After completing this section you should have:** * Client ID * Client Secret * Access Token URL * Authorization URL *** ### Basic Basic authentication uses a certificate and private key pair to authenticate with Microsoft Entra ID. Use this option if you are connecting to an on-premises SharePoint installation, or if you need to ingest User Profile data from SharePoint Online. Complete the Generate a certificate section above before continuing. #### **Register an Azure AD application** Register a new application in Microsoft Entra ID. See Microsoft's guide to [Registering an application in Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app). After registration, note your **Client ID** and **Tenant ID** from the application's Overview page. #### **Add API permissions** In **API permissions**, select **Add a permission** and add the following **Application permissions**. Grant admin consent for each. **Microsoft Graph:** ``` Sites.Read.All Files.Read.All Directory.Read.All Group.Read.All ``` If you are ingesting User Profile Data, also add the following **Mircrosoft Graph** permissions: ``` User.Read.All GroupMember.Read.All Member.Read.Hidden ``` **SharePoint:** ``` Sites.Read.All Sites.ReadWrite.All Sites.FullControl.All ``` #### **Upload the certificate to your Azure AD application** 1. In the Azure Portal, navigate to **Microsoft Entra ID > App registrations** and select your application. 2. Go to **Certificates & secrets > Certificates**. 3. Click **Upload certificate** and select the `certificate.cer` file generated above. 4. Note the **thumbprint** displayed after upload. #### **After completing this section you should have:** * Tenant ID * Client ID * The full contents of `certificate.pem` * The full contents of `private-key.pem` ## Integration Setup To create the SharePoint integration: 1. In the Aisera Admin UI, navigate to **Settings > Integrations**. 2. Click **+ New Integration**. 3. Select **SharePoint** and click **Next**. 4. Enter the configuration details, then select **Next**.
FieldDescription
NameThe name used to identify this integration
EndpointThe root URI for your SharePoint tenant. Do not include the protocol (http or https). For example: yourtenant.sharepoint.com
DescriptionA description of the integration and its purpose
5. Select the authentication type that matches your installation.
Use caseAuth type
SharePoint Online, knowledge base content onlyOAuth
SharePoint Online, User Profile ingestionBasic
On-premises installationBasic
6. Enter the credentials collected during Prepare and select **OK** to save the integration. {% hint style="info" %} When you select OAuth and click **OK**, you are redirected to Microsoft to authorize the Aisera platform. Complete the authorization to save the integration. {% endhint %} ## Data source setup To create the SharePoint data source: 1. In the Aisera Admin UI, navigate to **Settings > Data Sources**. 2. Click **+ New Data Source**. 3. Select **SharePoint** and click **Next**. 4. Enter the configuration details, then click **Next**.
FieldDescription
NameThe name used to identify this data source
IntegrationThe integration created in the previous section
FunctionDefines how the data source behaves and what data is ingested
ScheduleHow often the data source requests new data
DescriptionA description of the data source and its purpose
The remaining fields are additional configurations. See additional configurations for details. 5. Click **Next** until the window closes to save the data source. ### Additional Configurations #### List name The name of the SharePoint list from which to retrieve page items. #### Site The name of the specific SharePoint site to crawl. #### Libraries A list of library names to crawl, separated by carriage returns. If left empty, all libraries are crawled. #### Folders A list of relative folder paths to crawl recursively. Only the specified folders in your library are crawled. If left empty, the entire library is crawled. {% hint style="warning" %} Do not include the library name in the relative path. {% endhint %} #### User Render When selected, HTML content is rendered through the Node Renderer before ingestion. #### Managed path In SharePoint, a managed path is the designated location in a web application for site collections. The default managed path is `sites` — for example, `https://company.com/sites/`. Specify a value here only if your managed path differs from the default. ## Environment-specific setup The following processes apply only in specific environments or use cases. Each involves configuration steps outside the Aisera platform in addition to changes within it. Complete the relevant section only if it applies to your deployment. ### On-Prem installations In the **Data Source Configurations** enable **On Prem** if your SharePoint installation is on-premises. Leave unchecked for SharePoint Online instances. ### Limiting access to specific SharePoint sites Complete this process if you need to restrict the connector to specific SharePoint sites rather than your entire environment. This requires configuring the `Sites.Selected` Microsoft Graph permission on your Azure AD application and making changes in both Azure AD and the Aisera Admin UI. You can apply the `Sites.Selected` permission in two ways: * Use a PowerShell script to assign the necessary permissions. This must be performed by an authorized Azure administrator. * Use a second Azure application (the Admin App) to set permissions on the first (the Connector App). **Two application method** In this configuration, the **Connector App** is the application connected to Aisera, and the **Admin App** is used to manage permissions for the Connector App. 1. Register the **Connector App** in Microsoft Entra ID following the process in Prepare. Grant this application the `Sites.Selected` permission and grant admin consent. Note the **Client ID**. 2. Register the **Admin App** in Microsoft Entra ID. Grant this application the `Sites.FullControl.All` permission and grant admin consent. Note the **Tenant ID**, **Client ID**, and **Client Secret**. 3. Generate an access token for the Admin App. ```http POST https://login.microsoftonline.com//oauth2/v2.0/token ``` ```http Content-Type: x-www-form-urlencoded ``` ```http grant_type=client_credentials scope=https://graph.microsoft.com/.default client_id= client_secret= ``` 4. Copy the **Access Token** from the response. 5. Retrieve the **Site ID** for each SharePoint site you want to assign permissions to. {% hint style="info" %} To retrieve a list of available Site IDs, make a `GET` request to `https://graph.microsoft.com/v1.0/sites` with the header `Authorization: Bearer `. The Site ID appears in the `id` field of each result. {% endhint %} 6. Grant the Connector App access to the site.
```http POST https://graph.microsoft.com/v1.0/sites//permissions ``` ```http Content-Type: application/json Authorization: Bearer ``` ```json { "roles": ["read"], "grantedToIdentities": [ { "application": { "id": "", "displayName": "" } } ] } ``` \ Repeat this request for each site you want the connector to access. 7. In the Aisera Admin UI, navigate to **Settings > Data Sources** and open your SharePoint data source. 8. In the **Configuration** tab, enter the site names or IDs of the SharePoint sites to include as data sources.