Curiosity - Microsoft SharePoint

Microsoft SharePoint

Ingests SharePoint sites, document libraries, files, folders, and site pages via Microsoft Graph. Supports a per-tenant site allowlist so the connector only touches the spaces you care about.

variant=info text="Cloud storage" variant=success text="OAuth" variant=success text="Maps ACLs"

What gets ingested

Element	Mapped to
SharePoint site	`_Site`
Document library	`_Folder` (one per library)
Site page	`_SitePage`
Files in libraries	`_FileEntry` + `_Blob`
Folder hierarchy	`_Folder` linked by `_HasChild`

Authentication

The connector always reads Microsoft Graph as the user who connected it (delegated OAuth), never as a tenant-wide service account. Where the Entra ID app registration behind that OAuth flow comes from depends on the deployment:

Mode	App registration	Typical deployment
Curiosity-hosted app	Curiosity's multi-tenant `Curiosity for SharePoint` app, brokered through `oauth.curiosity.ai`	Curiosity Cloud and the desktop app
Your app, per connector	Tenant ID + Client ID + Client Secret set on the connector	Self-hosted workspace, or a second tenant
Your app, shared with SSO	The Microsoft SSO registration, used automatically when the connector carries no credentials of its own	Self-hosted workspace (the common case)

A workspace running in your own cloud therefore needs an app registration in your Microsoft tenant — see Microsoft Entra ID for the registration walkthrough, redirect URIs, and admin consent.

Required scopes: openid, profile, email, offline_access, User.Read, User.ReadBasic.All, Sites.Read.All.
Optional scopes: administrators can additionally grant Contacts.Read and Contacts.Read.Shared from Manage → Access → Single Sign-On → Microsoft
With your own registration, the consent request itself asks only for openid profile email offline_access; the Graph permissions the token carries are the delegated permissions granted on the app registration, so Sites.Read.All must be consented there.

Setting it up in a self-hosted workspace

Register the app in your tenant

Add the redirect URI {public-workspace-url}/api/oauth/microsoft/authorize, grant the delegated permissions above, and grant admin consent. Full steps: Microsoft Entra ID.

Create the connector

In Manage → Configure → Integrations, add a Microsoft SharePoint connector and set its options:

Setting	Purpose
`Source`	Name the ingested content is grouped under. Changing it after the first run leaves earlier data behind under the old name.
`TenantID`, `ClientID`, `ClientSecret`	The app registration to use. Leave empty to reuse the Microsoft SSO credentials.
`SitesAllowListWebUrls`	Sites to sync, as full site URLs. Empty means every site the connecting user can see.
`Parallelization`	How many users sync concurrently (default: one at a time).

Have users connect

Each user connects their own Microsoft account from Connect apps (#/spaces/connect-apps), which sends them through the consent screen and stores their refresh token on the connector. A connector with no connected users reports "No user has authorized access to their data yet" and does nothing.

Alternatively, enable Connect Sharepoint on Login in the Microsoft SSO settings: the workspace then creates the connector on first login and enrols each user automatically as they sign in, with no separate consent step. See Connecting SharePoint at login.

Restricting the sites synced (`SitesAllowListWebUrls`)

By default the connector syncs every site each connecting user can read, which on a large tenant means a slow first run and a lot of content nobody asked for. SitesAllowListWebUrls narrows that to a fixed list. It is a JSON array of site URLs on the connector's settings:

[
  "https://contoso.sharepoint.com",
  "https://contoso.sharepoint.com/sites/Marketing",
  "https://contoso.sharepoint.com/sites/Marketing/Campaigns",
  "https://contoso.sharepoint.com/teams/Engineering"
]

An empty array (the default) disables the filter. A non-empty array is applied to every site the connector discovers, for every user.

Matching rules

Each entry is compared to the site's Microsoft Graph webUrl with an exact string comparison, so:

Rule	Consequence
No prefix matching	`https://contoso.sharepoint.com` matches the root site only — not `/sites/Marketing`. The tenant root is a site in its own right, which is why prefixes would be unusable.
Subsites are separate sites	Listing `/sites/Marketing` does not include `/sites/Marketing/Campaigns`. List each one.
No trailing slash	`https://contoso.sharepoint.com/sites/Marketing/` does not match.
Case-sensitive	Use the casing Microsoft Graph returns (normally the casing used when the site was created).

To collect the URLs, use the Active sites list in the SharePoint admin center, or GET https://graph.microsoft.com/v1.0/sites?search=* in Graph Explorer — that is close to what the connector itself enumerates. The site's URL is what you see in the browser up to and including the /sites/<name> (or /teams/<name>) segment.

What it affects

Both files and pages. The filtered site list feeds document-library discovery and site-page discovery, so an excluded site contributes neither.
Not access. The allowlist can only narrow. Each user still sees exactly what their own Microsoft account can read within the listed sites.
Not already-ingested content. Removing a site from the list stops it being refreshed; what was already ingested stays in the graph until the connector or the user is reset.

Changes wait on the per-user site cache

The filtered list is cached per user for 120 hours, because site enumeration is the slowest part of a run. Editing the allowlist therefore does not take effect on the next scheduled run. A user's cache is cleared when that user triggers a sync from their own data-source card; an admin "Run now" from the scheduling page does not clear it.

Common uses: keeping personal or archived sites out of the index, scoping a pilot to a couple of department sites, and splitting a large tenant across several connectors — each with its own site list and sync schedule, with users authorizing each connector once.

Access control mapping

Access is mirrored per connecting user rather than by importing SharePoint's own groups:

Source	Carried into the graph?
Per-user site, library, folder, and file access	Yes — each connected user gets a hidden access group (`<source> <email>`), and every item their account could read at sync time is granted to that group.
Nested folders	Yes — a newly discovered subfolder inherits the permissions of its parent folder.
SharePoint site collection visitor / member / owner groups	No — SharePoint's own groups and role assignments are not imported as workspace access groups.

In practice this means a user sees in Curiosity exactly the SharePoint content their own Microsoft account can open, and nothing more. Content nobody has connected an account for is not ingested at all, and a user who never connects sees nothing from this connector. When several users can see the same file, it is granted to each of their access groups, so removing one user's authorization does not hide it from the others.

Sync cadence

Default cron: every 59 minutes (heavier APIs warrant a slower cadence).
Incremental sync: Microsoft Graph delta links per drive in each site. Sites themselves are cached for 120 hours (the site enumeration is the slowest part).
Idle users: a user who has not been active in the workspace for more than seven days is skipped until they return.
Expired authorization: when a refresh token stops working, that user is flagged for reconnection and skipped; everyone else keeps syncing.

Notable

Concurrent per-user locks prevent two workers from sync-ing the same site simultaneously.
A global rate-limit guard is shared across all SharePoint connector runs in the workspace.
A connector-version stamp lets the workspace upgrade schemas across releases without re-ingesting everything.
The connector also registers "New SharePoint Word Document / Excel Sheet / PowerPoint" commands in the workspace launcher.