Skip to content

Commit 14801eb

Browse files
Dumbrisclaude
andauthored
feat(scope): IdP-group server grants, one entitlement predicate, tenant session on core REST and Web UI (Spec 107 PR-C) (#1293)
* docs(specs): Spec 107 — server edition SSO front door hardened for real IdPs Generic OIDC provider, IdP-group → server allowlist, attributable JSONL audit line, and a freeze/cut of the latent multiuser/credential-injection code, split into four PRs (A freeze/cut, B OIDC + front door + telemetry, C entitlement predicate + tenant session, D audit line). Judge-panel drafted; cross-model reviewed over nine rounds (codex gpt-5.6-sol), ~130 findings resolved. Un-parks roadmap epic sso. * test(spec-107): PR-A red tests, server-tag lint job and release notice Related #1177 * refactor(serveredition): freeze the latent credential-injection chain and normalise removed config keys (Spec 107 PR-A) Related #1177 * fix(storage): enforce the agent-token cap per owner, not per deployment (Spec 107 PR-A) Closes #1177 * fix(spec-107): address adversarial review of PR-A * fix(spec-107): codex round 1 for PR-A * fix(spec-107): codex round 2 for PR-A * fix(spec-107): codex round 3 for PR-A * fix(spec-107): codex round 4 for PR-A * docs(spec-107): PR-A verification and task ticks * docs(roadmap): link PR-A * test(oauthserver): fake OIDC identity provider and server-edition dev rig (Spec 107 PR-B) * test(serveredition): red tests for the generic OIDC provider, subject binding and refusals (Spec 107 PR-B) * feat(serveredition): generic OIDC provider with JWKS-verified ID tokens, groups capture and subject binding (Spec 107 PR-B) Related #1169 * test(serveredition): red tests for trusted proxies, public URL, cookie security and forced MCP auth (Spec 107 PR-B) * feat(serveredition): front door behind an ingress — public URL, trusted proxies, cookie security policy, forced MCP auth, provider probe (Spec 107 PR-B) * feat(config,telemetry): hot-reload clauses, docs and OAS for the PR-B keys; telemetry v13 server-edition fields (Spec 107 PR-B) * fix(spec-107): gate fixes for PR-B * docs(spec-107): PR-B automated-check evidence * fix(spec-107): cross-review round 1 for PR-B * fix(spec-107): cross-review round 2 for PR-B * fix(spec-107): cross-review round 3 for PR-B * fix(spec-107): cross-review round 3 for PR-B * fix(spec-107): cross-review round 4 for PR-B * fix(spec-107): cross-review round 5 for PR-B * fix(spec-107): cross-review round 6 for PR-B * docs(spec-107): PR-B real-instance verification, gate re-run, task ticks T062/T063: real-instance verification of the OIDC front door (happy-path login, groups, /auth/me, agent-token mint + /mcp initialize/tools-list, ErrorMode tamper matrix, cookie Secure matrix behind a simulated trusted vs untrusted proxy) and the telemetry v13 payload (server vs personal). T064: full gate set re-run on HEAD after cross-review round 6 touched the config load path, oauth_handler.go and telemetry.go — all green. T066: tick completed PR-B tasks (T032-T066); ROADMAP.md regenerated. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * docs(roadmap): link PR-B Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * fix(ci): pull forward the Windows heap-corruption + Pass-2 race fix (#1288) This branch diverged from main before #1288 landed, so PR-B's CI hit the exact regression it fixed: handleAddFromRegistry's success path dereferenced a nil cfg, chi's recoverer turned the panic into a bare 500, and the recovered hardware fault corrupted the Go heap on windows/amd64 under Go 1.26 (golang/go#81238) — the internal/httpapi test binary crashed with "found pointer to free object" and took the whole Windows unit-test job (and the binaries job's httpapi/scanner test bundle) down with it. Cherry-picked the same fix main already carries: the nil-config guard with a JSON 500 (and its pinning test), plus the unrelated Pass-2 temp-dir teardown race fix in the scanner test this same upstream commit bundled. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * docs(spec-107): record the CI red/fix cycle for PR-B Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * docs(spec-107): record PR-B CI green Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * fix(spec-107): cross-review round 7 for PR-B * fix(spec-107): cross-review round 8 for PR-B * test(serveredition): two-fixture non-disclosure harness and single-predicate guard (Spec 107 PR-C) * test(scope): red tests for group grants, owner resolution, scoped index search and minting doors (Spec 107 PR-C) * feat(scope): one entitlement predicate with IdP-group grants, owner resolution on every authentication, scoped index search (Spec 107 PR-C) Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com> * test(httpapi,frontend): red tests for the tenant session principal, route allowlist and Web UI gating (Spec 107 PR-C) * feat(httpapi,web): tenant session principal on core REST, profiles/SSE/activity projections, Web UI on the SSO session alone (Spec 107 PR-C) T083: SessionPrincipalResolver type in internal/httpapi/session_principal.go; rewrote apiKeyAuthMiddleware with FR-001 precedence (X-API-Key > Authorization > ?apikey > session cookie). Auth context now excludes session principals from CanRevealSecrets. T084: Session principal resolver built in setup.go via userHandlers.ResolveAgentTokenOwner, installed via Dependencies and wired in serveredition_wire.go. T085: GET /profiles omits profiles whose entitlements don't intersect session scope; GET /profiles/active returns empty when active profile is hidden. SSE and activity paths re-resolve session principals before every frame for live-narrowing. T086: Activity filtering and masking for tenant sessions; GET /user/activity added; admin_user principals answer unconditionally with empty list (SC-006). T088–T089: Frontend principal-kind gating for tenant sessions (onboarded to /login, hidden config/routing/servers/stats/security/activity surfaces). AdminUsers adds Groups column; AdminServers shows server-scoped group/grant chips. Playwright e2e test added (quickstart.md spec). Both editions build clean; all unit-tests.yml -tags server race suites pass. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com> * docs(spec-107): access block reference, agent-token invariant, hot-reload and OAS wiring for PR-C * fix(spec-107): gate fixes for PR-C Full plan.md gate set run against PR-C HEAD (1e379ff): all gates pass, no PR-C code required fixing. golangci-lint's pinned v2 binary refuses the go1.26 module (pre-existing tooling gap); the @latest fallback found 16 issues, all pre-existing and outside the PR-C diff. The isolated test-api-e2e.sh run's two failures (launcher-lifecycle reconnect/log capture) are spec-046 fixture flakes unrelated to any PR-C file, reproduced identically on two runs. Records the full pass/fail table under '## PR-C / ### Automated checks' in verification.md. * fix(spec-107): cross-review round 1 for PR-C Four genuine defects found and fixed across three opencode gpt-5.6-sol/terra review chunks (a fourth chunk was clean plus two low-value findings rejected as pinned-by-design or non-security): - tenantSessionAllowlist matched on the DECODED r.URL.Path, but chi routes on RawPath — a server name containing a literal "/" (nothing forbids one; only ":" is refused) reaches the real handler via its percent-encoded id while the allowlist Cuts the decoded path on the wrong boundary, bypassing the named must-refuse for /servers/{id}/tool-calls. Fixed by matching on RawPath when set. - visibleSharedServers/visibleSharedServer independently re-read the live admin-config snapshot after the entitlement predicate had already read its own, opening a hot-reload race where a server could be entitled against one snapshot and disclosed from another. Fixed with tenantEntitledSnapshot, which fetches the snapshot once and threads it through both the predicate and the disclosure lookup. - GET /user/activity read AllowedServers off the AuthContext, but the ServerEditionAuthMiddleware this door is actually mounted behind never populates that field (only the separate SessionPrincipalResolver path does) — so every tenant on this door saw every user's activity for every server, entitled or not. Fixed by resolving the entitlement set live through the one predicate instead. - Dashboard.vue's loadActivitySummary was the one dashboard loader missing the tenant guard its four siblings already carry, drawing a spurious 403 against the now-allowlist-refused /activity/summary on every tenant page load and 30s refresh. Also corrected RELEASE_NOTICE.md's inverted claim about the access block's default (absent = Shared-only, NOT deny-all; only a present- but-empty block is deny-all) and widened the Playwright refused-route smoke list with several named must-refuse examples. Two findings verified and rejected: the nil-vs-empty access-block collapse in ServerEditionAccessProjection is deliberate, pinned by an existing config_hotreload_serveredition_test.go case; rejecting an empty group_servers key is defensive config validation, not a spec violation. * docs(spec-107): record PR-C cross-review round 1 Appends the round 1 entry (4 genuine findings fixed, 2 rejected with reasons, full verification command list) under PR-C. * fix(spec-107): cross-review round 2 for PR-C Cross-model review (opencode gpt-5.6-sol/terra) round 2 of PR-C: - entitledServerNamesFor read the admin-config servers once (round 1's fix) but the access block through a separate, independent live call, so a hot reload landing between the two reads could splice a servers snapshot from one configuration version to an access snapshot from another. A new EntitlementSnapshotProvider derives both values from one liveConfig() read, wired in setup.go. - The /events heartbeat branch never re-resolved the session principal, unlike its status/runtime-event siblings, so a disabled tenant's otherwise-idle stream never closed (FR-005). - The tenant profile projection only omitted a profile when scoping narrowed a non-empty effective set to empty, missing the case where the effective set was already empty. - Three tenant-dashboard call sites (Usage.vue's activity/usage poll, refreshSecurityScannerStatus, the ModeSwitcher control) and one Activity.vue fallback path issued or exposed admin-only core requests to a tenant session, contradicting FR-041; a doc paragraph misattributed an administrator-only capability to tenants. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * docs(spec-107): record PR-C cross-review round 2 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * docs(spec-107): PR-C real-instance verification, gate re-run, task ticks T079/T090: real-instance verification against the dev-server-edition rig (quickstart §5-§7) - entitlement-filtered REST, non-disclosing by-name refusals matching a nonexistent server, "*" token materialisation to the entitled set, hot reload narrowing a live session/token with no restart or rotation, JWT self-renewal refused, live administrator parity. Web UI/Playwright run against the rig with a properly embedded frontend (make build-server, since the rig script's bare go build does not embed it): 4/5 pass; the 5th hit a pre-existing router deep-link/reload bug (title updates, body does not) unrelated to the PR-C diff, flagged as a follow-up rather than fixed inline. T093: full gate set re-run against HEAD (aac5053, after both cross-review rounds), since review landed code changes after the prior gate run. All 19 non-e2e gates green; isolated test-api-e2e.sh run twice (63/65 both times, same pre-existing launcher-lifecycle pair, unrelated to PR-C). Ticks T067-T095 in tasks.md; ROADMAP.md regenerated. * docs(roadmap): link PR-C * fix(spec-107): cross-review round 3 for PR-C * docs(spec-107): record PR-C cross-review round 3 * fix(spec-107): wait for PhaseReady before seeding the group-scope fixture (PR-C CI) TestMCPGroupScope_TwoFixtureParity_GroupScopedToken failed in CI (not locally) because newGroupScopeFixture wrote directly to storage/upstream manager right after NewServer(), racing StartBackgroundInitialization's async LoadConfiguredServers — which treats cfg.Servers as the source of truth and unconditionally re-saves every entry (including the disabled shared-server placeholders this fixture registers) before flipping the runtime to PhaseReady. When that reconciliation write lands after the fixture's own Enabled:true write, the server reverts to Enabled:false in storage and isExactToolCallable drops its indexed tool from retrieve_tools — exactly the observed empty-vs-populated mismatch. Same race already fixed once in this codebase (see newLogsTestServer/server_logs_missing_file_test.go); this applies the same require.Eventually(PhaseReady) guard here. --------- Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
1 parent 673e83c commit 14801eb

99 files changed

Lines changed: 9799 additions & 576 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/RELEASE_NOTICE.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,3 +95,15 @@ When `server_edition.enabled` is true, `/mcp` now behaves as if `require_mcp_aut
9595
- **Refusals are uniform**: every denied login renders one generic `403` page ("Sign-in was not permitted") with a reference id; the reason (`email_unverified`, `subject_mismatch`, `state_invalid`, …) reaches only the server log and the `auth_event` line under that id. IdP-side failures (`discovery_failed`, `provider_error`) and proxy-side failures after verification (`internal_error`) render a `503` "Sign-in is temporarily unavailable" instead, so an outage is never shown as "not permitted" (FR-024).
9696
- **Login page label and edition probe**: public `GET /api/v1/auth/provider` returns only `{"display_name": "…"}` — never the issuer, client id, tenant, scopes or domains — so the Web UI labels the sign-in button and detects the edition before login; the personal build answers `404` (FR-030).
9797
- Guide: [multi-user authentication](https://docs.mcpproxy.app/development/server-edition-multiuser-auth/).
98+
99+
## Server edition: group-based server access, and credential minting is now session-cookie-only
100+
101+
A tenant — anyone who signs in through the team's IdP rather than through the API key or the local socket — now sees, uses, mints tokens for, connects to and diagnoses exactly the servers their IdP group grants (spec 107, FR-004/FR-009), on the REST API, the Web UI and every agent token they own. Administrators (API key, socket, and any `admin_email` user) are unaffected.
102+
103+
- **New config**: `server_edition.access.group_servers` maps an IdP group name to a list of shared server names (or `["*"]` for every shared server); `access.default_servers` covers a user whose groups match no key. A user's grant is the union of their groups' entries; a server must be **both shared and granted** to appear for them — sharing alone is not enough once the map is active. **The `access` block itself must be present to change anything**: an *absent* block keeps today's `Shared`-only behaviour (every shared server visible to every tenant, unchanged); a *present* block — even `{}`, with no `group_servers`/`default_servers` entries — is deny-all for every tenant that matches none of it. Add the block to narrow access; there is no config that widens it beyond `Shared`.
104+
- **Non-disclosing**: a server outside a tenant's grant does not exist for them on any surface — not its name, tools, prompts, counts, status, logs or activity. This applies to core REST (`/api/v1/*`, `/events`), the Web UI and agent tokens a tenant owns.
105+
- **Agent tokens narrow on every use, not just at mint**: an owned token's effective scope is recomputed from the user's *current* groups and the *current* `access` map on every authentication (one `GetUser` per call) — so **enabling, editing or removing an `access` entry takes effect on the token's very next call**, without rotating or re-minting it. The same is true for a tenant's session on core REST and its SSE stream (the per-frame refresher re-resolves the principal, so un-sharing narrows the next frame). Widening a user's access (the IdP adds them to a group, or the map is edited to include them) only takes effect once they sign in again — groups themselves refresh only at login.
106+
- **Credential-minting doors are session-cookie-only**: `POST /api/v1/auth/token` (JWT renewal), `POST /api/v1/user/tokens` and `POST /api/v1/user/tokens/{name}/regenerate` now accept only the browser session cookie — a bearer JWT or an agent token gets `401`. A derived credential can no longer mint another credential, closing the chain where a JWT could renew itself indefinitely and then mint a 30-day agent token in its last second. `POST /api/v1/user/tokens` also now caps `expires_in` at 365 days (previously unbounded), matching core `/api/v1/tokens`. The practical freshness bound is now **session TTL + the longer of JWT TTL and the longest-lived owned agent token (≤ 365 days)**; an administrator `disable` still takes effect immediately.
107+
- **Subject-rebind procedure for a re-created IdP account**: if your IdP re-creates a user's account (new subject, same email), the login is refused (`subject_mismatch`) rather than silently taking over the existing record. An administrator re-arms the binding by disabling the user and then re-enabling them — this arms a single-use, persisted rebind window — and the user's *next successful login* accepts the new subject and rebinds automatically. No other action is needed and no record is deleted.
108+
- **Tenant Web UI**: a signed-in tenant now gets a working dashboard, server list and activity view built entirely from the session cookie and the tenant-allowed routes — no `?apikey=`, no calls to administrator-only or global-state endpoints (`/info`, `/routing`, `/docker/status`, `/connect`, `/stats/tokens`, `/security/overview`, `/onboarding/state`, core `/activity*`, core `/config`); those cards, chips and pages are hidden rather than issued-and-403'd — Settings stays an administrator-only page (its own personal-server and token management live under `/my/servers`, `/my/tokens`). Diagnostics and history use the tenant-scoped `/user/diagnostics` and `/user/activity` endpoints. The `access` map is edited by an administrator through Settings' Raw JSON tab and shown read-only as group chips on the admin server page and on `AdminUsers`.
109+
- No action needed if you do not set `server_edition.access` at all: every tenant keeps seeing every `Shared` server exactly as before this release, on group grants alone. To start restricting tenants by IdP group, add the `access` block — from that point on, only a matching group entry (or `default_servers`) grants a shared server; a present-but-empty block denies every tenant until you populate it. Administrators are unaffected either way.

‎ROADMAP.md‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -426,16 +426,16 @@ graph LR
426426
classDef done fill:#1f7a1f,stroke:#0d3d0d,color:#ffffff;
427427
classDef in_progress fill:#1f6feb,stroke:#0b3d91,color:#ffffff;
428428
classDef todo fill:#6e7781,stroke:#3d4248,color:#ffffff;
429-
class sso_pr_a_freeze_cut done;
430-
class sso_pr_b_oidc_front_door in_progress;
431-
class sso_pr_c_group_allowlist,sso_pr_d_audit_line todo;
429+
class sso_pr_a_freeze_cut,sso_pr_b_oidc_front_door done;
430+
class sso_pr_c_group_allowlist in_progress;
431+
class sso_pr_d_audit_line todo;
432432
```
433433

434434
| Task | Status | Refs |
435435
| --- | --- | --- |
436436
| PR-A freeze/cut latent code + config normaliser + per-owner token cap (US5, US6) | 🟢 Done | #1287 |
437-
| PR-B generic OIDC provider + front door behind ingress + telemetry v13 (US2, US7) | 🔵 In progress | #1292 |
438-
| PR-C one entitlement predicate, group grants, tenant Web UI session principal (US1, US4) | ⚪ Todo | — |
437+
| PR-B generic OIDC provider + front door behind ingress + telemetry v13 (US2, US7) | 🟢 Done | #1292 |
438+
| PR-C one entitlement predicate, group grants, tenant Web UI session principal (US1, US4) | 🔵 In progress | #1293 |
439439
| PR-D attributable JSONL audit line + auth_event + config/doctor/metrics (US3) | ⚪ Todo | — |
440440

441441
</details>
@@ -896,7 +896,7 @@ graph LR
896896
| Telemetry v7: honest funnel + churn instrumentation | In progress | P1 | — | [080-telemetry-v7-churn](./specs/080-telemetry-v7-churn/) | |
897897
| MCP protocol upgrade to 2026-07-28 revision | In progress | P1 | 19/81 (23%) | [058-mcp-2026-upgrade](./specs/058-mcp-2026-upgrade/) | |
898898
| Planning/docs truth automation | In progress | P2 | — | | |
899-
| Spec 107 server edition SSO front door hardened for real IdPs | In progress | P2 | 69/126 (55%) | [107-server-edition-sso-hardening](./specs/107-server-edition-sso-hardening/) | |
899+
| Spec 107 server edition SSO front door hardened for real IdPs | In progress | P2 | 100/126 (79%) | [107-server-edition-sso-hardening](./specs/107-server-edition-sso-hardening/) | |
900900
| Discovery-quality eval harness (Spec 065 second half) | In progress | P3 | — | [065-evaluation-foundation](./specs/065-evaluation-foundation/) | |
901901
| tpa-db: versioned TPA signature database for the offline scanner | Todo | P1 | — | [101-tpa-db](./specs/101-tpa-db/) | |
902902
| Auto routing mode: budget-fitted tool surface per session (spec 104) | Todo | P1 | — | [104-auto-routing-mode](./specs/104-auto-routing-mode/) | |
@@ -1038,4 +1038,4 @@ Legend: `shipped` ≥95% checked · `in-flight` 1–94% · `drafted` 0% · `—`
10381038
| [104-auto-routing-mode](./specs/104-auto-routing-mode/) | — | — |
10391039
| [105-agent-scope-hardening](./specs/105-agent-scope-hardening/) | `in-flight` | 12/109 (11%) |
10401040
| [106-security-residual-fixes](./specs/106-security-residual-fixes/) | `shipped` | 18/19 (95%) |
1041-
| [107-server-edition-sso-hardening](./specs/107-server-edition-sso-hardening/) | `in-flight` | 69/126 (55%) |
1041+
| [107-server-edition-sso-hardening](./specs/107-server-edition-sso-hardening/) | `in-flight` | 100/126 (79%) |

‎docs/configuration/config-file.md‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -314,6 +314,15 @@ strings emitted at boot, by `PATCH /api/v1/config` and by `/config/apply`
314314
| `oauth.groups_claim` | string | `"groups"` | Restart | `oidc` only. Name of the ID-token (then userinfo) claim carrying group memberships. Accepted shapes: a flat JSON array of strings or a single string; anything else is treated as absent. Compared as exact strings by the group → server map |
315315
| `oauth.email_verified_policy` | `refuse_false` \| `require_true` \| `ignore` | `refuse_false` | Restart | `server_edition.oauth.email_verified_policy must be one of: refuse_false, require_true, ignore`. See the cost note below |
316316
| `oauth.display_name` | string | provider family name | Restart | Login-button label; at most 64 characters (`server_edition.oauth.display_name must be at most 64 characters`). It is the **only** field returned by the public `GET /api/v1/auth/provider` probe (never the issuer, client id, tenant, scopes or domains) |
317+
| `access` | object | absent (Shared-only semantics) | **Live** | Absent = today's behaviour, unchanged: every tenant sees every `shared` server. **Present = active**, with no silent allow-all: a tenant sees a shared server only through a group grant or `default_servers`; a user whose groups match no key and who has no default grant sees none. Read live through the config provider on every entitlement decision, so it hot-reloads (see [Group access map](/development/server-edition-multiuser-auth#group-access-map-server_editionaccess-and-entitlement-spec-107-pr-c)) |
318+
| `access.group_servers` | map[string]string[] | `{}` | Live | Group value (compared exactly, case-sensitive) → admin-config server names, or `"*"` for every shared server. Non-empty only with `oauth.provider: "oidc"` — `server_edition.access.group_servers requires oauth.provider "oidc" (legacy providers yield no groups)`. A group with no map entry contributes nothing (silent, not an error) |
319+
| `access.default_servers` | string[] | `[]` (no default grant) | Live | The grant for a user whose stored groups match no `group_servers` key. Absent, `null` and `[]` all mean "no default"; `"*"` is honoured here too |
320+
321+
An access-map entry (in `group_servers` or `default_servers`) that names no
322+
configured server is accepted, not refused — it may be written ahead of the
323+
server it names — but `mcpproxy doctor` reports it: `server_edition.access
324+
names N server(s) that match no configured server (…): those entries grant
325+
nothing until a server with that exact name exists`.
317326

318327
#### `email_verified_policy` — what each value costs
319328

@@ -372,7 +381,7 @@ See [Upstream Servers](/configuration/upstream-servers) for detailed server conf
372381

373382
MCPProxy watches the configuration file for changes and automatically reloads when modifications are detected. No restart is required for most configuration changes.
374383

375-
Exceptions that require a restart include `listen`, `data_dir`, `api_key`, the TLS block, the three `http_*_timeout` options, and — in the Server edition — every `server_edition` key except `admin_emails` (see [Server Edition](#server-edition)). `trusted_proxies` is live.
384+
Exceptions that require a restart include `listen`, `data_dir`, `api_key`, the TLS block, the three `http_*_timeout` options, and — in the Server edition — every `server_edition` key except `admin_emails` and `access` (see [Server Edition](#server-edition)). `trusted_proxies` is live.
376385

377386
## Environment Variable Overrides
378387

0 commit comments

Comments
 (0)