Skip to content

Commit 1f2cc18

Browse files
Dumbrisclaude
andauthored
feat(serveredition): generic OIDC provider, front door behind an ingress, telemetry v13 (Spec 107 PR-B) (#1292)
* 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 * fix(web-ui): update hard-reload auth-guard test for the FR-030 provider probe The merge of origin/main (#1294, shared in-flight auth probe) into 107-b-oidc-front-door (#1292, generic OIDC provider) combined without a conflict, but PR-B's auth store change (probe() now calls authApi.getProvider() instead of api.getStatus() for edition detection, Spec 107 FR-030/FR-041) left the test file's mocks pointed at the old api.getStatus() call, so every test silently no-oped through probe()'s catch block. Repoint the spy at authApi.getProvider() and update the resolved payload shape ({ display_name } instead of { data: { edition } }); the in-flight-probe-sharing behaviour under test is unchanged. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * fix(test): match TestLoadConfig_ListenFlag to loadConfig's 3-value signature Mirrors main's ce5c2f7 fix for the same loadConfig signature mismatch that broke the Build Binaries CI job on this PR. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
1 parent 4b1ca73 commit 1f2cc18

120 files changed

Lines changed: 15381 additions & 651 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: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,3 +54,44 @@ The server edition now enforces a **25-token quota per signed-in user** on top o
5454
- Server edition: a user at 25 tokens gets a `409 Conflict` from `POST /user/tokens` that names *their* quota — permanently deleting one of their unused tokens frees a slot — so one user can no longer take the whole pool. The 100-record deployment cap remains and every stored token still counts toward it, so a deployment whose stored records add up to 100 refuses the next token for everyone until an administrator frees records; a caller who is still under their own quota then gets the `409` that says the limit is shared and points at an administrator (the quota is checked first, so a user already at 25 sees their own-quota message instead). A user who already holds more than 25 tokens keeps them; they cannot create another until they are back under the quota.
5555
- Personal edition: every token is ownerless, so the quota does not apply and the 100-token limit is unchanged.
5656
- No configuration change is needed. Details: [agent tokens](https://docs.mcpproxy.app/features/agent-tokens/).
57+
58+
## Server edition: `/mcp` always requires a credential
59+
60+
When `server_edition.enabled` is true, `/mcp` now behaves as if `require_mcp_auth` were `true` whatever the file says (spec 107, FR-029). Before this release a server-edition deployment with `require_mcp_auth` off (the default) handed every unauthenticated `/mcp` caller an **anonymous administrator** context.
61+
62+
- No credential → `401`. A session cookie or a user JWT on `/mcp` → `401` (they were never valid there; they are no longer silently promoted). Agent tokens (`mcp_agt_…`), the global API key and the Unix socket work exactly as before.
63+
- An explicit `"require_mcp_auth": false` is **not** a validation error, so no deployment fails to boot on upgrade. It logs one notice — `require_mcp_auth: false is overridden to true because server_edition.enabled is true` — and `mcpproxy doctor` reports the same line. Remove the key, or set it to `true`, to silence both.
64+
- Personal edition: unchanged; `require_mcp_auth` keeps its configured value.
65+
- If an AI client reached `/mcp` on a server-edition deployment without any credential, it now needs an agent token: each user mints one from the Web UI or `POST /api/v1/user/tokens` and sends it as `Authorization: Bearer mcp_agt_…`.
66+
67+
## `trusted_proxies` now gates every forwarded header — behind an ingress, set it or `public_url`
68+
69+
`X-Forwarded-For`, `X-Real-IP`, `X-Forwarded-Proto` and `X-Forwarded-Host` used to be believed from **any** peer: a direct client could choose its own session IP, force the OAuth callback to `https`, or move it to another host. They are now honoured only when the request's `RemoteAddr` is inside the new top-level `trusted_proxies` list (CIDRs or addresses; env `MCPPROXY_TRUSTED_PROXIES`, comma-separated; hot-reloadable; both editions), taking the right-most hop that is not itself a trusted proxy as the client IP. The default is empty — **trust nobody** (FR-027).
70+
71+
**What changes behind a reverse proxy or ingress if you do nothing**
72+
73+
- The OAuth `redirect_uri` sent to your IdP is built from the listener's own scheme and `Host` — typically `http://…` — instead of the ingress's `X-Forwarded-Proto: https`. Your IdP's exact-match registration then refuses the callback and every SSO login fails.
74+
- The session's recorded IP, the audit `client.ip`, the connect-flow base URL and the swagger server URL all show the ingress's address, not the user's.
75+
76+
**Fix (either one)**
77+
78+
- Set `server_edition.public_url` to the origin users reach (`https://mcp.example.com`; env `MCPPROXY_PUBLIC_URL`). It becomes the sole source of the callback URL (`<public_url>/api/v1/auth/callback`), the connect-flow base URL and the cookie `Secure` decision; `Host` and `X-Forwarded-*` are ignored for those (FR-025). When it is unset and the listener is not loopback — the published image listens on `0.0.0.0:8080` — boot logs a warning and `mcpproxy doctor` reports it; it is not a validation error.
79+
- Or list your ingress in `trusted_proxies` (`["10.0.0.0/8"]`, `["fd00::/8"]`, a single address). Do both if you also want the real client IP in sessions and audit lines.
80+
- An invalid entry (`trusted_proxies[0] "…" is not a valid CIDR or IP address`) is a validation error at load and on `PATCH /api/v1/config`. No forwarded header ever feeds the local/remote or administrator classification. Details: [reverse proxy](https://docs.mcpproxy.app/operations/reverse-proxy/), [config file](https://docs.mcpproxy.app/configuration/config-file/), [environment variables](https://docs.mcpproxy.app/configuration/environment-variables/).
81+
82+
**Session cookie** — `server_edition.session_cookie_secure` is new: `auto` (default) sets `Secure` when the effective scheme is https (`public_url`, in-process TLS, or `X-Forwarded-Proto: https` from a *trusted* proxy), `true` forces it, `false` disables it. Earlier releases never set `Secure`. Validation refuses `false` together with an `https://` `public_url` or in-process TLS; an explicit `false` elsewhere is honoured with one boot warning and a `mcpproxy doctor` finding. `HttpOnly` and `SameSite=Lax` are unchanged (FR-026).
83+
84+
**Post-login redirect** — `redirect_uri` on `GET /api/v1/auth/login` is accepted only as a same-origin path (a single leading `/`, no scheme, host, `//`, `/\`, backslash or control character); anything else lands on `/ui/` and the login's `auth_event` line carries `redirect_rejected`. The Web UI is unaffected (FR-028).
85+
86+
## Server edition: generic `oidc` identity provider
87+
88+
`server_edition.oauth.provider` accepts `oidc` next to `google`, `github` and `microsoft`, so Okta, Entra ID, Keycloak, Authentik, Auth0 and any other OpenID Connect provider work without provider-specific code (FR-020). The three existing providers behave exactly as before.
89+
90+
- **Configuration**: `issuer_url` (required; `https`, or `http` only for a loopback host **and** `allow_insecure_issuer: true`), `scopes` (default `["openid","profile","email"]`; `openid` is added if missing), `groups_claim` (default `"groups"`), `email_verified_policy` (default `refuse_false`), `display_name` (login-button label; falls back to the provider name). `client_id`/`client_secret` stay `${env:}`-referenced; there is no environment variable for nested keys. `authorization_endpoint`, `token_endpoint`, `jwks_uri` and `userinfo_endpoint` come from `<issuer_url>/.well-known/openid-configuration`, fetched lazily on the first login and cached, so boot and readiness never wait on the IdP.
91+
- **Every ID token is verified before any claim is read**: signature against the issuer's JWKS (RS/PS/ES families only — never `none`, never HS*), exact `iss`, `aud`/`azp`, `exp`/`nbf`/`iat` with 60 s skew, and a per-login `nonce`. Discovered endpoints must be absolute `https` (same loopback exception), and the back-channel client never follows a redirect: the client secret and code are still sent to your configured token endpoint (and a bearer token to your configured userinfo endpoint) as normal, but a 3xx answer from any of the token, JWKS or userinfo endpoints refuses the login instead of being followed — so a compromised or misconfigured endpoint cannot redirect that credential to another host (FR-021).
92+
- **`email_verified_policy`** — `refuse_false` (default) refuses a login whose ID token says `email_verified: false` and admits one where the claim is absent; `require_true` also refuses an absent claim; `ignore` admits both. Pick `require_true` when your IdP always sets the claim; `refuse_false` exists so providers that omit it still work out of the box. `email` itself is required (`email_missing` otherwise).
93+
- **Groups are captured**: on every successful `oidc` login the user record stores the groups claim from the verified ID token (or from `userinfo` when the token lacks it — accepted only when the userinfo `sub` equals the token's `sub`), replacing the previous list wholesale with a `groups_updated_at` timestamp; a missing or malformed claim stores `[]` and logs `groups_claim_missing`. `google`/`github`/`microsoft` logins store `[]`. `GET /api/v1/auth/me` returns your groups; `GET /api/v1/admin/users` shows every user's groups and `groups_updated_at`. Storing groups has no authorisation effect on its own; they are the input to the server-edition `access` grant (FR-008).
94+
- **Subject binding**: a user record now remembers `(provider, provider_subject_id)` and refreshes both on every login. Same provider, same email, **different** subject is refused (`subject_mismatch`), so an IdP email collision cannot take over an existing account; an administrator re-arms the binding for a genuinely re-created IdP account by disabling and re-enabling the user — the next successful login rebinds (FR-023).
95+
- **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).
96+
- **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).
97+
- Guide: [multi-user authentication](https://docs.mcpproxy.app/development/server-edition-multiuser-auth/).

‎ROADMAP.md‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -423,16 +423,18 @@ graph LR
423423
sso_pr_b_oidc_front_door --> sso_pr_c_group_allowlist
424424
sso_pr_c_group_allowlist --> sso_pr_d_audit_line
425425
426+
classDef done fill:#1f7a1f,stroke:#0d3d0d,color:#ffffff;
426427
classDef in_progress fill:#1f6feb,stroke:#0b3d91,color:#ffffff;
427428
classDef todo fill:#6e7781,stroke:#3d4248,color:#ffffff;
428-
class sso_pr_a_freeze_cut in_progress;
429-
class sso_pr_b_oidc_front_door,sso_pr_c_group_allowlist,sso_pr_d_audit_line todo;
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;
430432
```
431433

432434
| Task | Status | Refs |
433435
| --- | --- | --- |
434-
| PR-A freeze/cut latent code + config normaliser + per-owner token cap (US5, US6) | 🔵 In progress | #1287 |
435-
| PR-B generic OIDC provider + front door behind ingress + telemetry v13 (US2, US7) | ⚪ Todo | — |
436+
| 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 |
436438
| PR-C one entitlement predicate, group grants, tenant Web UI session principal (US1, US4) | ⚪ Todo | — |
437439
| PR-D attributable JSONL audit line + auth_event + config/doctor/metrics (US3) | ⚪ Todo | — |
438440

@@ -894,7 +896,7 @@ graph LR
894896
| Telemetry v7: honest funnel + churn instrumentation | In progress | P1 | — | [080-telemetry-v7-churn](./specs/080-telemetry-v7-churn/) | |
895897
| MCP protocol upgrade to 2026-07-28 revision | In progress | P1 | 19/81 (23%) | [058-mcp-2026-upgrade](./specs/058-mcp-2026-upgrade/) | |
896898
| Planning/docs truth automation | In progress | P2 | — | | |
897-
| Spec 107 server edition SSO front door hardened for real IdPs | In progress | P2 | 32/126 (25%) | [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 | 69/126 (55%) | [107-server-edition-sso-hardening](./specs/107-server-edition-sso-hardening/) | |
898900
| Discovery-quality eval harness (Spec 065 second half) | In progress | P3 | — | [065-evaluation-foundation](./specs/065-evaluation-foundation/) | |
899901
| tpa-db: versioned TPA signature database for the offline scanner | Todo | P1 | — | [101-tpa-db](./specs/101-tpa-db/) | |
900902
| Auto routing mode: budget-fitted tool surface per session (spec 104) | Todo | P1 | — | [104-auto-routing-mode](./specs/104-auto-routing-mode/) | |
@@ -1036,4 +1038,4 @@ Legend: `shipped` ≥95% checked · `in-flight` 1–94% · `drafted` 0% · `—`
10361038
| [104-auto-routing-mode](./specs/104-auto-routing-mode/) | — | — |
10371039
| [105-agent-scope-hardening](./specs/105-agent-scope-hardening/) | `in-flight` | 12/109 (11%) |
10381040
| [106-security-residual-fixes](./specs/106-security-residual-fixes/) | `shipped` | 18/19 (95%) |
1039-
| [107-server-edition-sso-hardening](./specs/107-server-edition-sso-hardening/) | `in-flight` | 32/126 (25%) |
1041+
| [107-server-edition-sso-hardening](./specs/107-server-edition-sso-hardening/) | `in-flight` | 69/126 (55%) |

‎cmd/mcpproxy/listen_flag_test.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ func TestLoadConfig_ListenFlag(t *testing.T) {
5555
t.Fatal(err)
5656
}
5757

58-
cfg, err := loadConfig(cmd)
58+
cfg, _, err := loadConfig(cmd)
5959
if err != nil {
6060
t.Fatalf("loadConfig: %v", err)
6161
}

‎docs/configuration.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -654,6 +654,7 @@ See [OAuth Documentation](mcp-go-oauth.md) for complete details.
654654
{
655655
"api_key": "your-secret-api-key",
656656
"trusted_hosts": ["mcp.example.com"],
657+
"trusted_proxies": ["127.0.0.1"],
657658
"read_only_mode": false,
658659
"disable_management": false,
659660
"allow_server_add": true,
@@ -665,6 +666,7 @@ See [OAuth Documentation](mcp-go-oauth.md) for complete details.
665666
|-------|------|---------|-------------|
666667
| `api_key` | string | Auto-generated | API key for REST API authentication. Required; if empty, one is auto-generated and enforced (logged on startup) |
667668
| `trusted_hosts` | string[] | `[]` | Non-loopback `Host` header values accepted on loopback listeners (reverse-proxy deployments). See below |
669+
| `trusted_proxies` | string[] | `[]` (trust nobody) | CIDRs or IP addresses whose `X-Forwarded-For` / `X-Real-IP` / `X-Forwarded-Proto` / `X-Forwarded-Host` headers are honoured; any other peer's forwarded headers are ignored and `RemoteAddr` is used. Env `MCPPROXY_TRUSTED_PROXIES`. Hot-reloadable. Invalid entry: `trusted_proxies[N] "value" is not a valid CIDR or IP address` (boot, PATCH and apply). See [Reverse Proxy Deployment](operations/reverse-proxy.md#trusted_proxies-forwarded-headers) |
668670
| `read_only_mode` | boolean | `false` | Prevent all configuration modifications |
669671
| `disable_management` | boolean | `false` | Disable server management operations (restart, enable, disable) |
670672
| `allow_server_add` | boolean | `true` | Allow adding new servers via API/tools |
@@ -1627,6 +1629,8 @@ Many configuration options can be overridden via environment variables:
16271629
|----------------------|--------------|-------------|
16281630
| `MCPPROXY_LISTEN` / `MCPP_LISTEN` | `listen` | Network binding address |
16291631
| `MCPPROXY_API_KEY` | `api_key` | API key for authentication (empty values trigger auto-generation; auth remains enabled) |
1632+
| `MCPPROXY_TRUSTED_HOSTS` | `trusted_hosts` | Comma-separated `Host` allowlist for loopback listeners behind a reverse proxy |
1633+
| `MCPPROXY_TRUSTED_PROXIES` | `trusted_proxies` | Comma-separated CIDRs/IPs whose `X-Forwarded-*` headers are honoured |
16301634
| `MCPPROXY_TLS_ENABLED` | `tls.enabled` | Enable HTTPS/TLS |
16311635
| `MCPPROXY_TLS_REQUIRE_CLIENT_CERT` | `tls.require_client_cert` | Enable mTLS |
16321636
| `MCPPROXY_CERTS_DIR` | `tls.certs_dir` | Custom certificates directory |

0 commit comments

Comments
 (0)