teams/README.md's Graph permission list is wrong and has been copied into published docs and a legal answer

Open Beginner friendly
#2,157 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
1/5
Estimated time
Under an hour
Newbie friendliness
85/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
python
Domain
documentation

Research direction

Read item 4 of core/switch_core/bridges/collaboration/teams/README.md, then confirm the enforced set in teams/identity.py (REQUIRED_GRAPH_ROLES) and the all-or-nothing check in teams/install.py (_granted_roles). Rewrite item 4 split into the distributed-app route (all eight roles, nothing optional) and the self-registered route, and add a comment pointing at REQUIRED_GRAPH_ROLES as the authority. Done when the list matches the code exactly and both routes read separately.

Written by the indexing model from the issue text.

Description

What's wrong

core/switch_core/bridges/collaboration/teams/README.md, under the administrator-owned environment setup, item 4:

Graph API permissions with admin consent, for channel capture + provisioning: ChannelMessage.Read.Group (RSC, preferred) or tenant-wide ChannelMessage.Read.All; plus Channel.Create, Channel.ReadBasic.All, User.ReadBasic.All, and TeamMember.ReadWrite.All / ChannelMember.ReadWrite.All.

Three problems:

  1. TeamMember.ReadWrite.All is not what Switch asks for. teams/identity.py declares TeamMember.ReadWriteNonOwnerRole.All — a materially narrower permission that cannot change owner roles. This one matters most, because it is the line an administrator copies into Azure when granting consent.
  2. Two permissions are missing: Team.ReadBasic.All and TeamsAppInstallation.ReadWriteSelfForTeam.All, both in REQUIRED_GRAPH_ROLES.
  3. The required/optional framing does not hold for the distributed app. REQUIRED_GRAPH_ROLES is checked as a whole in install.py (_granted_roles), and the install is refused unless the organisation's token carries every one of the eight — "Switch was not approved for the whole organisation: … Start again from Switch, and tick 'Consent on behalf of your organization'." So for that route there is no "RSC preferred" alternative and nothing is conditional.

The README is not simply stale: it is describing the self-registered Azure AD app route, where an administrator supplies app_id, a secret and tenant_id and no role check runs. On that route RSC genuinely is an option. But it reads as the permission list for Switch-and-Teams generally, and item 1 is wrong on both routes.

Why it is worth fixing here rather than only downstream

This text has been copied twice:

  • into the published Microsoft Teams page (microsoft-teams.mdx, "Before you begin"), which is being corrected now;
  • into an internal reference that fed an answer to a customer legal question, which had to be retracted.

Both copies reproduced the same three errors, because the README is the most discoverable description of what Teams needs. Correcting the copies leaves the source intact for the next person.

Suggested fix

Split item 4 by route, and name the enforced set for the distributed app:

  • Distributed Switch Teams app — all eight of REQUIRED_GRAPH_ROLES, no alternatives and nothing optional: ChannelMessage.Read.All, Channel.Create, Channel.ReadBasic.All, TeamMember.ReadWriteNonOwnerRole.All, ChannelMember.ReadWrite.All, User.ReadBasic.All, Team.ReadBasic.All, TeamsAppInstallation.ReadWriteSelfForTeam.All. Approval needs a Global Administrator or Privileged Role Administrator.
  • Self-registered app — the administrator's choice, described by consequence: ChannelMessage.Read.Group (RSC) or tenant-wide ChannelMessage.Read.All for capture, RSC not covering private or shared channels; Channel.Create for provisioning; Channel.ReadBasic.All; User.ReadBasic.All; TeamMember.ReadWriteNonOwnerRole.All and ChannelMember.ReadWrite.All for adding people.

A comment pointing at REQUIRED_GRAPH_ROLES as the authority would stop the list drifting again.

Verified at switch-v0.32.1.

Dominant language
Python
Stars
4.5k
Forks
348
Avg merge
1d 17h
Merged PRs (30d)
287

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from sandbox-quantum/switch

All issues in sandbox-quantum/switch

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.