# SharePoint

Index and search Microsoft SharePoint document libraries and site pages in Risotto

Connect your Microsoft SharePoint sites to Risotto to make document libraries and site pages searchable through the AI assistant.

## What Gets Indexed

Risotto's SharePoint integration indexes:

- **Document Libraries** - Files stored in SharePoint drives (PDFs, Word documents, spreadsheets, etc.)
- **Site Pages** - SharePoint modern pages and wiki pages

> **Note:** SharePoint indexing uses application credentials (Azure AD app registration)
> rather than user OAuth. This allows indexing of all content the app has access
> to, regardless of individual user permissions.

## Prerequisites

Before configuring SharePoint indexing in Risotto, you must create an Azure AD application with the appropriate permissions.

### Step 1: Register an Azure AD Application

1. **Access Azure Portal**

   Sign in to the [Azure Portal](https://portal.azure.com) and navigate to **Microsoft Entra ID** > **App registrations**. (Microsoft renamed Azure Active Directory to Microsoft Entra ID.)

2. **Create New Registration**

   Click **New registration** and configure:

   - **Name**: Enter a descriptive name (e.g., "Risotto SharePoint Integration")
   - **Supported account types**: Select "Accounts in this organizational directory only"
   - **Redirect URI**: Leave blank (not required)

   Click **Register**.

3. **Note Application Credentials**

   After registration, note these values from the Overview page:

   | Value         | Location                |
   | ------------- | ----------------------- |
   | **Client ID** | Application (client) ID |
   | **Tenant ID** | Directory (tenant) ID   |

4. **Create Client Secret**

   Navigate to **Certificates & secrets** > **New client secret**:

   1. Enter a description and select an expiration period
   2. Click **Add**
   3. **Copy the secret value immediately** - it will not be shown again

   > **Warning:** Store your client secret securely. You cannot retrieve it after leaving this page.

### Step 2: Grant API Permissions

1. **Add Permissions**

   Navigate to **API permissions** > **Add a permission** > **Microsoft Graph** > **Application permissions**.

2. **Select Required Permissions**

   Add these permissions:

   | Permission       | Description                            |
   | ---------------- | -------------------------------------- |
   | `Files.Read.All` | Read all files in all site collections |
   | `Sites.Read.All` | Read items in all site collections     |

3. **Grant Admin Consent**

   Click **Grant admin consent for \[Your Organization]**.

   > **Info:** Admin consent is required because these are application-level permissions that allow Risotto to read SharePoint content on behalf of your organization.

## Configure SharePoint in Risotto

### Create a SharePoint Index

1. **Open SharePoint's page**

   Go to [**Settings** > **Integrations** > **SharePoint**](https://dashboard.tryrisotto.com/settings/integrations/sharepoint) and click **Add site**. If you have no index yet, click **Add site** on the **Sites** row. The **Add a site** dialog opens.

2. **Enter Credentials**

   Fill in the required fields:

   | Field             | Description                                                                                                                                                                                    | Example                                    |
   | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
   | **Name**          | Descriptive name for this index. Must be unique.                                                                                                                                               | "Engineering Documentation"                |
   | **Site URL**      | SharePoint site to index                                                                                                                                                                       | `contoso.sharepoint.com/sites/engineering` |
   | **Client ID**     | Azure AD Application ID                                                                                                                                                                        | `00000000-0000-0000-0000-000000000000`     |
   | **Tenant ID**     | Azure AD Directory ID                                                                                                                                                                          | `00000000-0000-0000-0000-000000000000`     |
   | **Client secret** | A [vault credential](https://www.tryrisotto.com/docs/dashboard/settings/credential-vault) that holds the Azure AD client secret. Choose it, or click **Add a vault credential** to create one. | `SharePoint client secret`                 |

   If you already have a SharePoint index, the dialog fills in the client ID, tenant ID, and client secret from it.

   The hint under **Client secret** names the Microsoft Graph permissions the app needs: `Files.Read.All` and `Sites.Read.All` (Application type).

3. **Configure Optional Settings**

   Optionally specify:

   | Field          | Description                                                                   | Default           |
   | -------------- | ----------------------------------------------------------------------------- | ----------------- |
   | **Folder**     | Specific folder to index. Empty reads the whole library and the site's pages. | Entire site       |
   | **Department** | Restrict the index to one department                                          | Organization-wide |
   | **Audience**   | **Everyone** or **Assistant only**: who can receive answers                   | Everyone          |

   *Product example: The Add a site dialog on the SharePoint integration page: a name, the site URL, a folder, the client and tenant IDs, a client secret from the vault, Department and Audience, and Add site.*

4. **Create Index**

   Click **Add site**. The site's card on the **Knowledge** tab shows the progress, and so does the **Indexing Jobs** panel on **Knowledge > Indexes**.

**Create index** on [**Knowledge > Indexes**](https://www.tryrisotto.com/docs/dashboard/knowledge/indexes#create-an-index) still adds a SharePoint index with the same details, plus **Profile filters**, which only that dialog has.

### Site URL Formats

Risotto accepts several formats for the Site URL:

```
# Full URL (recommended)
contoso.sharepoint.com/sites/engineering

# Teams site
contoso.sharepoint.com/teams/marketing

# Site name only (will auto-resolve)
contoso
```

### Folder Path Examples

To index only a specific folder within your SharePoint site:

```
# Root-level folder
/Documents

# Nested folder
/Documents/Reports/2024

# Specific project folder
/Projects/Product Launch
```

> **Tip:** If no folder path is specified, Risotto indexes all files in the document
> library plus all site pages.

## Supported File Types

| Category     | Extensions                                      |
| ------------ | ----------------------------------------------- |
| Documents    | `.pdf`, `.doc`, `.docx`, `.txt`, `.rtf`, `.odt` |
| Spreadsheets | `.xls`, `.xlsx`, `.csv`                         |
| Web/Markup   | `.html`, `.htm`, `.md`, `.markdown`             |

## Real-Time Updates

Risotto automatically keeps your index up-to-date using Microsoft Graph webhooks:

- **New files/pages** are indexed within minutes of creation
- **Updated content** is re-indexed automatically
- **Deleted items** are removed from the index

**Note:** No manual reindexing is required for day-to-day changes.

## Access Control

### Department Restriction

Restrict index access to specific departments:

1. When creating or editing the index, select **Department**
2. Choose a specific department or "Organization-wide (no department restriction)"

### Profile filters

Use **Profile filters** to send answers from this index only to users whose profile matches the rules (for example, job title or location). Profile filters improve relevance. They are not an access control. To limit who can get answers from the index, use **Audience**.

## Troubleshooting

### Authentication Errors

#### Authentication failed or Invalid credentials

**Solutions:** - Verify Client ID, Client Secret, and Tenant ID are correct -
Ensure the Client Secret has not expired - Confirm admin consent was granted
for the API permissions

#### Site not found

**Solutions:** - Check the Site URL format - try using the full URL from your
browser - Verify the Azure AD app has `Sites.Read.All` permission - Ensure the
site exists and is accessible

#### Access denied or Insufficient permissions

**Solutions:** - Verify admin consent was granted for all required permissions

- Check that you granted **Application** permissions, not Delegated - Ensure
  the permissions are `Files.Read.All` and `Sites.Read.All`

### Indexing Issues

#### No files indexed

**Solutions:** - Verify the folder path is correct (paths are
case-insensitive) - Check that the document library contains supported file
types

#### Index shows fewer files than expected

**Solutions:** - Verify the folder path is not too restrictive - Check the
completion notice of the indexing job. Risotto skips a file that stops the
indexer three times and lists it there with "Indexing failed 3 times". Split
large files into smaller files, then reindex. - A file that is too large to
index is skipped, and admins get a **Document Too Large To Index** warning.

#### SharePoint resync notice

Sometimes SharePoint tells Risotto to read the whole library again. Risotto
then starts a full index and sends the notice "SharePoint asked us to resync.
A full index is running." You do not need to do anything.

#### The SharePoint client secret is invalid

The indexing job ends with "The SharePoint client secret is invalid. In Azure,
use the secret Value, not the Secret ID." Microsoft Entra ID refused the
client secret. In Azure, open the app registration, go to **Certificates &
secrets**, and copy the secret **Value**. Do not copy the **Secret ID**. Enter
the Value in the index settings, then run the job again. An expired secret or
a wrong client ID or tenant ID shows the "Risotto couldn't list the files in
SharePoint" error instead.

#### The app has no SharePoint access

The indexing job ends with "The app has no SharePoint access. Add
Sites.Read.All and Files.Read.All as Application permissions and grant admin
consent." Microsoft Entra ID gave the app a token, but Microsoft Graph refused
it. In Azure, add `Sites.Read.All` and `Files.Read.All` as **Application**
permissions, not Delegated, and click **Grant admin consent**. Then run the
job again.

#### Risotto couldn't list the files in SharePoint

The indexing job ends with an error, and admins get an **Indexing Job Error**
alert. Risotto could not read the file list of the document library. Retry the
job. If it fails again, check that the app registration can read the document
library.

## Security Considerations

### Credential Storage

- All Azure AD credentials are encrypted at rest
- Client secrets are never exposed in logs or UI after initial entry
- Credentials are isolated per organization

### Data Access

- Risotto only reads content - no write access to SharePoint
- Indexed content is stored securely within your Risotto instance
- Access respects your configured department and profile rules

### Webhook Security

- Webhook endpoints validate Microsoft Graph notification signatures
- Each subscription uses a unique client state for verification
- Invalid webhooks are rejected and logged

## Limits

| Limit                         | Value                  |
| ----------------------------- | ---------------------- |
| Webhook subscription lifetime | 30 days (auto-renewed) |
| Supported SharePoint versions | SharePoint Online only |

## Next Steps

After setting up your SharePoint index:

1. **Test the integration** using [**Knowledge** > **Playground**](https://dashboard.tryrisotto.com/knowledge/playground)
2. **Ask Risotto questions** about your indexed documentation in Slack
3. **Monitor answer quality** and adjust filters if needed
4. **Expand gradually** by adding more indexes as needed

For additional help, contact support at <support@tryrisotto.com>.

Source: https://www.tryrisotto.com/docs/integrations/knowledge/sharepoint
