SharePoint connector setup

Operator·5 minutes to read

This page is the setup half: registering the app SharePoint needs in the Microsoft Entra admin center and getting its client id and secret into this deployment. A member then adds SharePoint from the catalogue and presses Authenticate, which signs them in with their work or school account and asks for reading only. Saving files is a second consent the member asks for later with Allow sending on the same account.

SharePoint is its own plugin, with its own redirect URL saying sharepoint. It is not part of the microsoft-365 plugin, so a member who connected Microsoft 365 keeps that connection unchanged.

1. Register the app in the Microsoft Entra admin center

  1. Open the Microsoft Entra admin center and register a new application under Identity → Applications → App registrations. Under Supported account types, choose Accounts in any organizational directory: SharePoint sites belong to work and school accounts. You may reuse the Microsoft Teams registration instead, as long as it also carries this page's redirect URL and permissions.

  2. Under Redirect URIs (platform Web), add the redirect URL from docs/connectors/README.md. With the quickstart's default BOTSEON_PUBLIC_URL, that is:

    http://127.0.0.1:3000/api/oauth/sharepoint/callback

  3. Under Certificates & secrets, create a new client secret. Copy the Application (client) ID from Overview and the secret's value, which is shown once.

2. Scopes

All are Microsoft Graph delegated permissions: the bot acts as the member and opens only what the member can open. A search is trimmed by Microsoft to the files the member may read. The first sign-in asks for the read half:

  • User.Read: the member's own profile, to label the connection.
  • offline_access: a refresh token, so the connection outlives the hour-long access token.
  • Sites.Read.All: the sites, libraries, folders and files the member can open.
  • Files.Read.All: what Microsoft's search asks for to search files.

Allow sending asks for the write half on top:

  • Sites.ReadWrite.All: save a file into a library folder the member can edit.

Every upload waits on an approval card that names the folder ("Site / Library / Folder"). Before saving, the connector reads that folder's own name back from Microsoft and saves nothing if it is not the one on the card. An upload never replaces a file of the same name.

Admin consent. Many organisations turn off user consent for apps. Then the member's sign-in stops at Microsoft with "Need admin approval" until an administrator of the member's own organisation grants consent once for the app (Enterprise applications → the app → Permissions → Grant admin consent). That is Microsoft's rule for the member's tenant. Botseon adds no approval step of its own.

3. Enter the app

Pass the client secret on standard input. No flag takes it and no environment variable holds it (see docs/connectors/README.md):

printf %s "$CLIENT_SECRET" | botseon oauth-app set \
  --org <organisation id> --slug sharepoint \
  --client-id <the client ID from step 1> \
  --auth-url https://login.microsoftonline.com/organizations/oauth2/v2.0/authorize \
  --token-url https://login.microsoftonline.com/organizations/oauth2/v2.0/token \
  --configured-by <your user id>

organizations (not common) is the authority that accepts work and school accounts only. No --revoke-url is set: Microsoft has no endpoint an app can call to revoke a member's delegated grant (the Microsoft Teams page explains what Remove does instead).

An existing organisation sees the new tile after an owner or admin accepts the new catalogue seed hash with botseon catalogue import --org <organisation id> --accept --accepted-by <their user id>.

4. The optional list of allowed sites

An organisation's admin may narrow where bots look. On Organisation → Policies, under SharePoint sites, list the only sites bots may search and read, one address per line, as each site's home page shows it (https://contoso.sharepoint.com/sites/Finance). A site includes its libraries, folders and subsites, and nothing beside it: /sites/Finance does not allow /sites/Finance-Archive.

With a list saved:

  • a search keeps only results on listed sites, and tells the bot how many it left out and why;
  • listing a site's libraries or folders, or reading a file, on a site that is not listed returns nothing and says the site is not on the organisation's list;
  • an upload to a site that is not listed saves nothing.

The run reads the list fresh before every call, so a change applies from the next search or read. An empty list allows every site a member's own account can open, which is also what an organisation that never opens the control gets. Every change is recorded in the audit log as org.connector_site_list_changed.

5. The nightly live check

packages/connectors/src/sharepoint.live.test.ts runs every SharePoint tool against a real Microsoft tenant in the nightly connector-live workflow: search, finding sites, browsing, reading, the opt-in upload, and the allowed-sites list. Its test site and refresh token are set up on docs/operations/connector-live-setup/sharepoint.md.

6. SharePoint for the whole team

A team admin can connect SharePoint once for the whole team on Organisation → Team connectors (S-96504): Delegated or Application permissions, the team's Microsoft tenant ID, an optional Allow write access switch, then Connect team, which sends the admin to Microsoft's admin consent for that tenant (request shapes). Nothing new is registered for it: the consent returns to the same redirect URL as step 1.

  • Delegated uses the delegated permissions above; members still sign in with their own account, and the admin's consent means nobody is asked for approval again.
  • Application needs, on the same app registration, Application permissions for Microsoft Graph: Sites.Read.All, and Sites.ReadWrite.All if the team allows write access. Bots then use the team's app-only token (client credentials, with the client secret from step 3) and read only the sites the admin picks on Team connectors. Sites.Selected is not enough: the per-site search Botseon uses does not support it.
  • Until Microsoft's consent comes back, members' bots answer "This team does not have the SharePoint integration". Without the write switch no member can save files.

Application-level consent can fail at Microsoft with AADSTS50011 when the redirect URL is not registered on the Web platform; Delegated is the workaround. What to check when a team's setup does not work: sharepoint-team-runbook.md.

Last verified against build 76e3778.