Setting Up M365 Connectors

Connect ThreadWeave to Exchange Online and SharePoint via Microsoft Graph.

ThreadWeave has three M365 connectors for your organization's Microsoft 365 data: the email watcher and the SharePoint watcher read app-only with client credentials, and the Teams bot receives messages through the Bot Framework. This guide walks through the Azure setup for each one.

What You'll Set Up

uv run python -m threadweave.cli email login

export THREADWEAVE_PROFILE=personal
uv run python -m threadweave.cli email watch

Prerequisites

• An Azure subscription with an Entra ID (Azure AD) tenant
• Global Administrator or Application Administrator role in that tenant (to grant admin consent)
• For Email Watcher & SharePoint Watcher: Exchange Online and SharePoint Online licenses in the tenant
• ThreadWeave installed and running (threadweave serve)

Step 1: Create the Azure App Registrations

We recommend two separate app registrations — different permissions, different security boundaries.

App 1: ThreadWeave-GraphReader

Used by the Email Watcher and SharePoint Watcher.

1. Go to Azure Portal → Microsoft Entra ID → App registrations → New registration
2. Name: ThreadWeave-GraphReader
3. Supported account types: "Accounts in this organizational directory only"
4. Redirect URI: leave blank (app-only flow)
5. Click Register

After creation, note these values:

Application (client) ID:  _______________
Directory (tenant) ID:    _______________

Now create a client secret and set permissions:

1. Certificates & secrets → New client secret → name it → 24 months → Add
2. Copy the secret Value immediately (not the Secret ID — that's different)
3. API permissions → Add a permission → Microsoft Graph
4. Select the Application permissions tab (not Delegated)
5. Add: Mail.Read, Sites.Read.All
6. Click "Grant admin consent for <tenant>"

Step 2: Set Environment Variables

Set these before starting ThreadWeave:

# For Email Watcher + SharePoint Watcher
export AZURE_TENANT_ID="your-tenant-id"
export AZURE_CLIENT_ID="your-graphreader-client-id"
export AZURE_CLIENT_SECRET="your-graphreader-secret"

On Windows PowerShell:

$env:AZURE_TENANT_ID = "your-tenant-id"
$env:AZURE_CLIENT_ID = "your-graphreader-client-id"
$env:AZURE_CLIENT_SECRET = "your-graphreader-secret"

Step 3: Verify Authentication

Before running the connectors, verify your app registrations work:

from msal import ConfidentialClientApplication
import json, base64

app = ConfidentialClientApplication(
    client_id="your-client-id",
    client_credential="your-secret",
    authority=f"https://login.microsoftonline.com/your-tenant-id",
)
result = app.acquire_token_for_client(scopes=["https://graph.microsoft.com/.default"])

if "access_token" not in result:
    print(f"FAILED: {result.get('error_description', result)}")
else:
    token = result["access_token"]
    parts = token.split('.')
    payload = base64.urlsafe_b64decode(parts[1] + '=' * (4 - len(parts[1]) % 4))
    claims = json.loads(payload)
    roles = claims.get('roles', [])
    print(f"OK — roles: {roles}")

If roles is empty:

• You used Delegated permissions instead of Application — switch tabs in API permissions and re-add
• Admin consent wasn't granted — click the button in API permissions
• You copied the Secret ID instead of the Value — the Value looks like Xmf8Q~...

Step 4: Test Each Connector

Email Watcher

Fetches unread emails from an Exchange Online inbox and reconstructs conversation threads:

uv run python -c "
import asyncio, os, sys
sys.path.insert(0, '.')
from threadweave.connectors.email.watcher import MailWatcher

async def test():
    watcher = MailWatcher()
    emails = await watcher.fetch_unread(
        mailbox='user@your-tenant.com',
        max_results=5,
    )
    print(f'Fetched {len(emails)} unread emails')
    for e in emails:
        print(f'  {e.subject[:60]} — {e.sender_name}')

asyncio.run(test())
"

Expected: lists unread emails from the specified mailbox.

SharePoint Watcher

Discovers SharePoint sites in your tenant:

uv run python -c "
import asyncio, os, sys
sys.path.insert(0, '.')
from threadweave.connectors.sharepoint.watcher import GraphClient

async def test():
    client = GraphClient()
    sites = await client.list_sites()
    print(f'Found {len(sites)} SharePoint sites')
    for s in sites:
        print(f'  {s.display_name} — {s.web_url}')

asyncio.run(test())
"

Expected: lists SharePoint sites. If you get 400 Bad Request: Tenant does not have a SPO license, your tenant lacks SharePoint Online.

Step 5: Install the Teams App

The Teams bot is distributed as an app package. Build it with the packaged CLI so every org gets a validated, deterministic zip:

uv run python -m threadweave.cli teams package \
  --bot-id YOUR-BOT-APP-ID --version 1.0.1
# → dist/threadweave-teams-app-1.0.1.zip

Two ways to get the package into an org. For a pilot, upload it manually in the Teams admin center:

admin.teams.microsoft.com → Teams apps → Manage apps → Upload new app → Publish

For customer onboarding, publish it with one command. The admin signs in once with a device code, and the app lands in the org catalog pending approval:

uv run python -m threadweave.cli teams publish \
  --package dist/threadweave-teams-app-1.0.1.zip
# 1. Open https://microsoft.com/devicelogin
# 2. Enter the code, sign in as a Teams admin
# → Uploaded, then approve in admin.teams.microsoft.com → Publish

Setup notes for the publish command:

• Set THREADWEAVE_PUBLISH_CLIENT_ID to an app registration with the delegated AppCatalog.Submit permission and public client flows enabled
• Set AZURE_TENANT_ID; the sign-in authority must be tenant-scoped, the generic common authority fails with AADSTS50059
• The upload uses requiresReview=true; AppCatalog.Submit submits for review only, a direct upload returns 403 even for global admins
• Users install the approved app from Teams → Apps → Built for your org

Troubleshooting

Production Checklist

• Client secrets expire — set a calendar reminder for 24 months from creation
• Store secrets in a vault (Azure Key Vault, HashiCorp Vault), not in shell history
• Use separate app registrations per environment (dev/staging/prod)
• Monitor the audit log at /api/v1/audit/recent for connector activity
• Test with --dry-run and small --max values before full ingestion
• Pilot the Teams app in one team before org-wide rollout; the bot only sees conversations it is installed in
• For Teams Store distribution, enter the Microsoft 365 and Copilot program in Partner Center; free to list, 3% store fee only on paid transact offers

View on GitHub