MS SharePoint Knowledge Ingestion

This document describes how to set up MS Sharepoint Knowledge Ingestion. It includes:

a) How to Set Up Aisera Integration (OAuth)

b) How to set up Integration for the SharePoint connector

c) How to set up the SharePoint Data Source

Please note that this information applies only to Aisera version 1.0 or newer.

The connector uses MSGraph API calls.

Create an Aisera Service Account

Use the Aisera Admin UI to create an Aisera Service Account User that can log into your SharePoint system. This user only needs Read permissions (with Export ability) to transfer data to the Aisera platform DB. If you plan to use Ticket Concierge, Knowledge Generation, or other features that write back to your SharePoint system, this user will need Read/Write permission (with Import/Export ability). This user does not need Execute or Delete permissions because all Aisera operations will be performed, tracked, and logged in the Aisera cloud.

How to set up Aisera Integration (OAuth)

1. Click on Setting > Integration > New Integration

2. Enter the configuration details

Name - Enter the name of your Aisera Service Account user.

EndPoint - Enter the Endpoint of the SharePoint you want to connect to. It is a tenant/customer's SharePoint URI. For example, for Aisera it would be aiseraoffice365.sharepoint.com - enter this without the protocol such as HTTP or HTTPS.

Public - Determines whether the integration can be used outside the firewall.

Description - Enter the description you want to mention (optional)

1. Enter the authentication details:

Tenant ID - Enter the Tenant ID. Get this from the customer.

Client ID - Enter the Client ID of the SharePoint tenant you want to connect to.

Client Secret - Enter the Client Secret of the SharePoint tenant you want to connect to.

Username - Enter the Username of the SharePoint tenant you want to connect to.

Password - Enter the Password of the SharePoint tenant you want to connect to.

Note - If you select the Authentication type as “Auth”, you will need to get the Access Token URL too.

The parameters above are retrieved depending on whether you use:

(A) Azure AD

OR

(B) SharePoint App token for authentication/authorization by the tenant/customer.

See the appropriate Section A OR Section B below to configure the Aisera Integration for SharePoint.

Section A: Get auth credentials from Azure Portal

The Azure Portal uses the MSGraph API.

Copy the values for the parameters from the Azure Portal as described below:

1. Login to the Azure Portal

2. Go to Azure Active Directory → App Registrations and select an app (Aisera app) You can see values for clientId and azureTenantId.

Create the Client secret by going to Certificates & Secrets:

1. Click New Client Secret, add the description and duration.

2. Copy the generated secret and save it to a file, because it will not be visible after leaving the page.

   
3. Permissions

   • Select your app and on the sidebar click API Permissions.

• Click Add a permission and select Microsoft Graph in the Request API Permissions screen:

  

1. On the next screen, select Application Permissions

2. Scroll down the list and select the following MSGraph Application permissions to have access to SP sites resources, (or set the scopes according to the example after this section).

   • Sites.Read.All

   • Files.Read.All

   • Directory.Read.All

   • User.Read.All (to get User Profile information)

   • Group.Read.All

   • GroupMember.Read.All (to get User Profile information)

     
3. Click Add Permissions.

4. Finally, click the Grant Admin Consent button.

You can also authorize the Integration from the command line as:

scope=offline_access AccessReview.Read.All AccessReview.ReadWrite.All Application.ReadWrite.All Directory.Read.All User.Read.All Group.Read.All GroupMember.Read.All.

Section B: Get auth credentials from SharePoint (by registering auth information for Aisera)

The SharePoint app uses the SharePoint REST API.

Remember to save client_id and client_secret in a file because you can not retrieve them after leaving this page.

1. Navigate to https://[tenant].sharepoint.com/_layouts/15/appregnew.aspx. (it will look like image above)

2. Click Generate next to Client ID.

3. Click Generate next to Client Secret.

4. Add Title (It can be any title, for example, Aisera REST API Access).

5. Update App Domain (It can be any domain, but preferably www.aisera.com).

6. Update Redirect URL (It can be any URL, but preferably https://[tenant].login.aisera.cloud/).

7. Click Create.

Grant permissions to an app

1. Navigate to https://[tenant].sharepoint.com/_layouts/15/appinv.aspx

2. Paste the value of the Client ID in the App Id field (generated during APP registration) and appended with an @, followed by the Tenant ID

3. Click Lookup

4. Update the Permission Request XML: the values below will give you read access to site collections (don't include the outer quotes from the XML example below): <AppPermissionRequests AllowAppOnlyPolicy="true">

<AppPermissionRequest Scope="http://sharepoint/content/sitecollection/web" Right="Read"/>

</AppPermissionRequests>

1. Click Create.

Note: If you want to give tenant-wide permissions you have to go to https://[tenant-admin].sharepoint.com/_layouts/15/appinv.aspx and update the Permission Request XML as follows:

<AppPermissionRequests AllowAppOnlyPolicy="true">
<AppPermissionRequest Scope="http://sharepoint/content/sitecollection" Right="FullControl"/>
</AppPermissionRequests>

You can find some useful information on permissions here.

How to configure Aisera SharePoint Data Source

The SharePoint data source supports the Knowledge Base Learning function.

SharePoint DataSource Configuration Options:

1. Click on Settings > Data Source > New DataSource.

2. Select SharePoint and click Next.

3. Enter the configuration details

Name - Enter the Name of the DS. Type - Select the Type Integration - Select the Integration created Function - Select the Function (Objects you want to ingest) Schedule - Select the schedule you want to DS to run Public Domain - Enter the Public Domain If any (optional) Description - Enter the Description you want to mention for this DS.

4. Enter the additional configuration details

How to apply granular permissions for the Azure app

When there is a need to configure the Sharepoint connector to only use a limited set of sites instead of everything on the Sharepoint server, you need to configure the Sites. Select MSGraph permission. In order to apply the Sites. Select MSGraph permission to the Azure application configured for the integration, this can be done in two ways:

1. Use a PowerShell script to set this permission to the Aisera Azure application which can be done by an Azure administrator, or

2. Create a second Azure application which will be used to set the permissions to the first Aisera Azure application (this is the main Azure app that the Aisera SaaS will connect to). This two-app method is described below.

App Registration

1. Register Azure AD Application (APP 1) in Azure AD Portal with the following permissions:

Sites.Selected (Admin Consented)

2. Another AD Application (APP 2) with the following permission only for the admins to assign selected roles to the above App (APP1):

Sites.FullControl.All (Admin Consented)

Grant Permission to Site

This step is about granting permission for the Azure AD application with Sites. Selected application permission to a given site collection.

Perform the following steps to grant the role (Read/Write or Read and Write) to the AD app (APP 1):

1. Collect the Client ID, Tenant ID, and Client secret of the admin app

2. In Postman, make an HTTP request to generate the access token for the admin app: Request Method: POST

Request URL: https://login.microsoftonline.com/yourtenantID/oauth2/v2.0/token

Request Header:

Key: Content-Type

Value: application/x-www-form-urlencoded

Request Body: (x-www-form-urlencoded)

grant_type: client_credentials

scope: https://graph.microsoft.com/.default

client_id: adminappclientid

client_secret: adminappclientsecret

1. Copy the access_token

2. Get the Client ID of the Azure AD Application – APP 1 with Sites.Selected permission

3. Decide on the Role (Read or Write) for granting the Site specific role for the APP 1 with Sites.Selected permission.

4. Get the SiteId of the SharePoint site to be assigned permissions for the application (App 1). An easy way to get the siteId is by viewing the page source from the browser with the site open.

5. In PostMan, make a HTTP request to grant the site role to the APP 1. Replace the siteId with the actual siteId which will be a guide:

Request Method: POST

Request URL: https://graph.microsoft.com/v1.0/sites/siteId/permissions

Request Header:

Key: Content-Type

Value: application/json

Request Body: (raw JSON)

Replace the id with APP 1 client id and the display name of the APP 1

{

    "roles": ["read"],

    "grantedToIdentities": [{

  "application": {

    "id": "xxxxxx-APP1GUID-4ad9-xxxx-4d36e68b0454",

    "displayName": "AppNamewithSelectedPermissions-App1"

       }

    }]

}

8. In the Authorization tab, select Bearer Type and paste the token you got from step 3.

9. Send the request for granting the role for APP 1. After you make the request, APP 1 is connected with the Sites. Selected permissions have access to the site with the read role you have granted. In the same way, you can assign app access to multiple SharePoint sites.