Proposal: optional Microsoft Teams provisioning helper (Entra app, Azure Bot, app package via az CLI)

[EldarPolitkin]

Short version. Setting up the Teams chat connector is the longest manual setup of all the chat providers. We run a script that does it with the Azure CLI for our own bots, and we would like to contribute a generic version. We will not write any code until a maintainer says whether this fits and where it belongs.

Problem

doc/plans/chat-adapters/2026-09-04-chat-adapters-minimum-setup-v6.md says "No provisioning helper is part of the shipped path" for Teams. Today an operator does all of this by hand, in three Microsoft portals:

1. Entra: register a single-tenant app, create a client secret, create its service principal.
2. Azure portal: create an Azure Bot with that app id, enable the Microsoft Teams channel, set the messaging endpoint to <public origin>/api/chat-webhooks/<publicId>/microsoft-teams.
3. Teams Developer Portal: build the app package (bot id, personal/team/groupChat scopes, the RSC entries ChannelMessage.Read.Group and ChatMessage.Read.Chat, webApplicationInfo), then download or upload it.
4. Paste client id, tenant id and client secret into Paperclip.

Every value has to match in three places. The Teams live-qualification record shows that a wrong or missing webApplicationInfo binding is easy to get wrong. Slack has one manifest URL for the same job.

What the helper does

A non-interactive command that drives the operator's own signed-in az CLI and does steps 1 to 3 in one go:

• creates the single-tenant Entra app, its service principal and a client secret (with a label and expiry the operator chooses),
• creates the Azure Bot (F0 by default) with the Teams channel enabled and the Paperclip messaging endpoint set,
• writes the Teams app package zip (manifest.json built from the same field map the setup wizard already shows, plus the two icons) to a path the operator picks, ready for custom upload or admin publication,
• prints client id and tenant id, and gives the client secret to Paperclip without printing it (see below),
• is safe to re-run: it finds the app and bot by name and updates them, rather than creating duplicates.

Possible CLI shape (open to whatever fits your CLI conventions):

paperclipai connect teams provision \
  --endpoint <publicId>            # or --messaging-endpoint https://.../microsoft-teams
  --bot-name maya                   # display name, also used for resource names
  --resource-group <rg> [--subscription <id>] [--location global] [--sku F0]
  --package-out ./maya-teams.zip
  [--secret-years 2] [--dry-run]

--dry-run prints the az calls it would make, so an admin can review them or hand them to someone with the rights.

What the operator still needs

• az login as a Microsoft 365 work/school account that may register applications (or an admin to run it).
• Contributor on one Azure resource group for the Bot resource.
• Custom-app upload permission in Teams, or a tenant admin to publish the zip. The helper does not install the app: Microsoft's install needs an interactive M365 sign-in, so that step stays a human action.

How it fits the current Teams docs and connector

• No change to the connector, the credential fields (clientId, tenantId, clientSecret) or the setup wizard. The helper only produces the same three values and the same manifest block the wizard already documents.
• The secret goes straight into Paperclip's secret store through the existing connection API (or is written to stdin of a command the operator chooses). It is never printed or written to a file by default.
• The docs gain one optional "Automated setup (Azure CLI)" section beside the manual path. The manual path stays the default.
• If you prefer, this can live outside core: as a script under scripts/, a separate package, or a plugin. We read CONTRIBUTING's guidance to prefer the plugin system for extensions, and we are happy to go that way.

Alternatives considered

• A Bicep/ARM template only: it covers the Bot resource but not the Entra app or the Teams package, and still needs the three values matched by hand.
• Microsoft 365 Agents Toolkit (atk provision): heavy, wants its own project layout, and its token cache fails under conditional-access MFA policies in a way the plain az login does not.
• Microsoft Graph calls from the Paperclip server: needs a privileged app registration inside Paperclip, which is a bigger trust change than running az as the operator.

Proof plan for the PR (if you agree)

• Unit tests with the az runner faked: the exact command sequence, re-run idempotency, dry-run output, and that the secret never reaches stdout or a log.
• A manifest test against the same field map the wizard uses, so the two cannot drift.
• One live run on a real work tenant, with the output scrubbed of ids: the app and Bot created, a client_credentials token minted for https://api.botframework.com/.default with the new secret, the zip accepted by Teams custom upload, and one message round trip through the connector. The inbound round trip depends on the open Teams webhook 401 (Microsoft Teams webhooks rejected with 401 in authenticated mode (actorMiddleware consumes Bot Framework Bearer before chat-webhook handler) #13468, fix in fix(auth): delegate canonical Teams webhooks to provider authentication #15185).

Related

• Microsoft Teams webhooks rejected with 401 in authenticated mode (actorMiddleware consumes Bot Framework Bearer before chat-webhook handler) #13468 Teams webhooks rejected with 401 in authenticated mode, fix(auth): delegate canonical Teams webhooks to provider authentication #15185 its open fix
• docs: allow the chat webhook ingress hostname in private mode #18301 docs: allow the chat webhook ingress hostname in private mode
• docs: record a Teams work-tenant qualification attempt on v2026.1023.0 #18302 docs: Teams work-tenant qualification attempt on v2026.1023.0
• [AGENTS] Integrations Hub — Teams C1: webhook service + modal + test-send endpoint #3328 Integrations Hub Teams C1 (webhook service)

We have the Azure CLI version running in production for several bots and would port it to TypeScript (or keep it a script) as you prefer. Questions: does this fit the roadmap, and where should it live (CLI command, scripts/, plugin, or not upstream at all)?