Addition of Microsoft Teams Channel - User Setup Guide

[Proxicon]

Summary

Refresh the Microsoft Teams channel documentation so the public Netclaw website matches the current Teams implementation being proposed upstream.

This documentation accompanies the main implementation PR:

• Microsoft Teams Channel Integration netclaw#2184 — Microsoft Teams Channel Integration

The page has been updated from the earlier/basic Teams guide to cover the current Phase 1 / Phase 1.1 implementation, including Azure Bot provisioning, Microsoft Entra configuration, Graph permissions, Teams resource-specific consent, Group Chats, TUI-first configuration, access controls, attachments, validation, and troubleshooting.

What changed

Azure Bot and Entra setup

• document the requirement for a valid Azure subscription and Azure Bot resource
• explain the Azure resource layout: subscription, resource group, Azure Bot, Teams channel, and public /api/messages endpoint
• document the single-tenant Entra application setup
• clarify that the same application identity is used across the Azure Bot, Netclaw Teams configuration, and Teams application package
• document client-secret handling and rotation without placing secrets in normal Netclaw configuration

Microsoft Graph permissions

Add the current Graph application permissions used by the Teams integration and explain why each is needed:

Permission	Type	Purpose
Team.ReadBasic.All	Application	Team discovery and display metadata
Channel.ReadBasic.All	Application	Channel discovery and metadata
User.Read.All	Application	User discovery and canonical Entra identity metadata
GroupMember.Read.All	Application	Group discovery and membership-based authorization
Chat.ReadBasic.All	Application	Optional Group Chat metadata/name discovery

The guide also clarifies that the commonly pre-created delegated User.Read permission is not required by Netclaw.

Teams resource-specific consent

Document the Teams package RSC permissions separately from Microsoft Graph permissions:

• ChannelMessage.Read.Group
• ChatMessage.Read.Chat

This makes the distinction between Teams message delivery consent and Graph directory/discovery access explicit.

Current Teams channel capabilities

Update the guide for the current implementation:

• personal chats
• standard Team channels and threaded conversations
• approved Group Chats
• established channel-thread continuation
• interactive tool approvals through Adaptive Cards
• proactive/reminder delivery
• bounded image attachment handling
• canonical user/group/channel/chat authorization
• Graph-backed directory discovery and group authorization

TUI-first configuration

Make the supported operator workflow the primary setup path:

netclaw config
  -> Channels
  -> Microsoft Teams

The guide now covers:

• Teams connection and credentials
• Team/channel discovery
• user and group authorization
• Group Chat discovery
• Group Chat ingress enable/disable
• manual canonical-ID fallback
• channel-specific access controls
• audience overrides

Manual JSON configuration remains documented as an advanced/reference path.

Group Chats

Add the current Group Chat behavior and requirements:

• Group Chat ingress is disabled by default
• canonical Group Chat IDs remain authoritative
• friendly name discovery can use Chat.ReadBasic.All
• manual canonical-ID configuration remains available without that optional permission
• enabling ingress does not itself authorize a chat
• saved Group Chat IDs are retained when ingress is disabled
• principal authorization and mention policy still apply

Identity and access control

Correct the older identity guidance to reflect current canonical Entra identities and document:

• AllowedUserIds
• AllowedGroupIds
• ChannelAccessOverrides
• ChannelAudienceOverrides

The guide also explains the difference between access authorization and audience/tool-policy classification.

Attachments

Replace the older blanket unsupported-upload guidance with the current bounded attachment behavior:

• AllowAttachments remains disabled by default
• supported image candidates pass through the Teams trust/download/verification pipeline
• unsafe or ambiguous attachments fail closed
• normal channel and Group Chat file handling remains deliberately restrictive

Validation and troubleshooting

Refresh the end-to-end setup verification and troubleshooting guidance for:

• Azure Bot endpoint/TLS problems
• tenant, Client ID, and Bot ID mismatches
• missing client secret
• Teams app installation/RSC problems
• Graph admin consent
• Team/channel/user/group authorization
• Group Chat ingress and discovery
• structured mention requirements
• audience mapping
• attachment rejection

Relationship to the implementation PR

This documentation is intended to land with, or after:

netclaw-dev/netclaw#2184 — Microsoft Teams Channel Integration

PR #2184 implements the Teams channel functionality described here, including the current Microsoft Teams SDK 2.x runtime, Graph-backed directory support, Group Chats, approvals, proactive delivery, TUI management, and attachment handling.

The website update should therefore not be treated as a standalone feature change; it documents the behavior introduced by the companion Netclaw implementation PR.

Validation

The documentation change was originally prepared and reviewed in:

• docs: refresh Microsoft Teams channel setup guide Proxicon/netclaw-website#2 — docs: refresh Microsoft Teams channel setup guide

Source validation included:

• git diff --check
• verification against the current Teams implementation and manifest
• sanitized Teams package generation confirming manifest.json, color.png, and outline.png
• review to ensure no customer-specific subscription IDs, tenant IDs, resource groups, application IDs, endpoints, or secrets are published

Scope

Documentation only.

No Netclaw runtime, Teams package, permissions, or application behavior is changed by this PR.