Setting Up M365 Connectors

Connect ThreadWeave to Exchange Online, SharePoint, and Microsoft Copilot via Microsoft Graph.

ThreadWeave has three M365 connectors that use app-only client credentials to read your organization's Microsoft 365 data. This guide walks through the Azure setup for each one.

What You'll Set Up

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
• For Graph External Connector: a tenant with Microsoft Graph connectors support (M365 E5, or the Graph connectors add-on)
• 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>"

App 2: ThreadWeave-CopilotConnector

Used by the Graph External Connector to sync ThreadWeave entries to Copilot.

Repeat the same registration steps, with these differences:

• Name: ThreadWeave-CopilotConnector
• Permission: ExternalConnection.ReadWrite.OwnedBy (Application)
• Grant admin consent

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"

# For Graph External Connector (Copilot)
export THREADWEAVE_GRAPH_TENANT_ID="your-tenant-id"
export THREADWEAVE_GRAPH_CLIENT_ID="your-copilotconnector-client-id"
export THREADWEAVE_GRAPH_CLIENT_SECRET="your-copilotconnector-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.

Graph External Connector

Creates an external connection and registers the ThreadWeave schema:

uv run python -c "
from threadweave.connectors.graph.connector import ThreadWeaveGraphConnector

connector = ThreadWeaveGraphConnector()
print(f'Configured: {connector.is_configured}')

# Create connection and register schema
result = connector.register_schema()
print(f'Schema registered: {result}')

# Verify connection
info = connector.get_connection()
print(f'Connection state: {info}')
"

Expected: connection created (201), schema registered. If schema registration fails with 400, your tenant may lack Graph Connectors licensing.

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