Microsoft 365 connector setup

This page is the setup half — creating the OAuth app Microsoft 365 needs in the Microsoft Entra admin center and getting its client id and secret into this deployment. Authorising a connection afterwards is the Authenticate control on the plugin sheet, which is what actually sends you to Microsoft.

This plugin bundles three connectors — mail, calendar and files — behind one app registration. One plugin, one consent, three connectors, and therefore one redirect URL, saying microsoft-365; there is none for outlook-mail, outlook-calendar or onedrive on their own.

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 — this is your own registration, not Botseon's.

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/microsoft-365/callback
   

3. Under Certificates & secrets, create a new client secret. The registration's Overview pane shows you the Application (client) ID; the secret's value is shown once — copy both now.

2. Scopes

Request the narrowest set that covers the tools this connector exposes (F-PLUG-1: minimum scopes per capability, read and write requested separately), as delegated permissions:

• Mail.Read — read messages and folders; no writes.
• Mail.ReadWrite — create, update and delete drafts and messages.
• Mail.Send — send a message the member approved.
• Calendars.Read — read calendars and events; no writes.
• Calendars.ReadWrite — create, update and delete events.
• Files.Read.All — read files and their metadata; no writes.
• Files.ReadWrite.All — create and edit files.
• User.Read — read the signed-in account's own profile, so a connection can be labelled with whose it is.
• offline_access — issue a refresh token, so the connection survives past the access token's own short lifetime.

User.Read and offline_access are requested once, with the read half, because without them there is no refresh token and no account identity to label — the same grant covers all three connectors.

3. Enter the app

One command, with the client secret on standard input — there is no flag that takes it and no environment variable that holds it (see docs/connectors/README.md):

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

Both URLs are read from Microsoft's own current documentation of the v2.0 endpoints (Microsoft identity platform and OAuth 2.0 authorization code flow), not invented here; the common tenant covers both work/school and personal Microsoft accounts.

It stores the secret encrypted and prints the redirect URL from step 1 back, so you can check the two match. botseon oauth-app show --org <organisation id> --slug microsoft-365 says whether an app is configured and under which client id; nothing prints the secret back.

Never put either value in a bot's description, a memory, or anywhere else a model reads as ordinary text.