docs(sso): document single sign-on - #531
Merged
Merged
Conversation
The feature shipped with no user-facing documentation at all — no mention in the README, docs/, the env-var table or anywhere else. That matters more than usual given it is self-hosted only: a self-hoster had no way to discover it exists, and a cloud user meeting a 404 had nothing explaining why. docs/sso.md covers registering the app at the provider, mapping directory groups to roles, requiring SSO, recovery codes, and turning all of it off again. Two Entra constraints that cost real time are called out: only Security and Microsoft 365 groups can be assigned to an application (distribution lists cannot), and group assignment does not cascade to nested groups. It also records, rather than glosses, how tool restriction actually behaves: the per-server endpoint filters `tools/list`, while the global `/mcp` endpoint lists every tool of the workspace and enforces only on `tools/call`. A restricted user can never invoke a tool their roles do not grant, but on the global endpoint they can still see the inventory — so the doc points people at a per-server endpoint when they rely on role restriction. Also fixes a comment in role-sync.service.ts that pointed at `RolesService.getUserToolAccess`, which does not exist; the method is `getAllowedToolIds`.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Single sign-on shipped with no user-facing documentation at all — no mention in the README,
docs/, the env-var table or anywhere else.That matters more than usual given the feature is self-hosted only: a self-hoster had no way to discover it exists, and a cloud user meeting a 404 had nothing explaining why.
What is added
docs/sso.md— registering the application at the provider, mapping directory groups to roles, requiring SSO, recovery codes, and turning all of it off again. Linked from the README feature list,docs/guides.md, and theDEPLOYMENT_MODErow of the deployment env table.Two Entra constraints that cost real time during the build are called out explicitly:
Tool restriction is documented as it behaves
Verified with a non-admin user and a real MCP key:
tools/listtools/call/mcp/<serverId>/mcp(global)A restricted user can never invoke a tool their roles do not grant on either endpoint, but on the global endpoint they still see the inventory. The doc records this and points people at a per-server endpoint when they rely on role restriction, rather than implying the list is filtered everywhere. A fix for the global endpoint is separate work.
Also
Corrects a comment in
role-sync.service.tsthat pointed atRolesService.getUserToolAccess, which does not exist — the method isgetAllowedToolIds.