Skip to content

feat(sso): three-tier roles with access-key role association - #2

Merged
jplorier merged 1 commit into
mainfrom
feat/sso-api-key-roles
Oct 29, 2026
Merged

jplorier merged 1 commit into
mainfrom
feat/sso-api-key-roles

Conversation

@jplorier

Copy link
Copy Markdown
Owner

Why

Two gaps in the current proxy-auth overlay:

  1. No role on API tokens. The role guard decides admin-vs-viewer from the request's X-Forwarded-Groups header. Access-key requests (/api/v2, /mcp) carry no such header, so the guard treated them as viewers and denied every write — which is why the Terraform provider's PUT /api/v2/dashboards returns 403 Read-only access.
  2. Two coarse roles. admin or read-only viewer; no "can edit dashboards but not manage sources/connections/team".

Context: click-api.topia.io (the token host) is being scoped to /api/v2 in metaversecloud-com/infra-terraform#214, because the header-trusting app routes were reachable there unauthenticated. This PR is what makes /api/v2 writes work again once that lands — authorized by the token owner's role, not by headers.

Change

  • models/proxyAuthRole.ts — persists each user's last proxy-asserted role (viewer|member|admin), groups and lastSeenAt. Access-key requests have no proxy headers, so they are authorized against this record.
  • middleware/proxyAuthRoles.ts — app-wide guard mounted before every router:
    • Browser (proxy) requests: role from X-Forwarded-Groups; the record is refreshed (at most hourly unless it changes).
    • Access-key requests (/api/v2, /mcp): resolve the key owner, read the stored role, ignore headers. Keys whose owner hasn't signed in via SSO within PROXY_AUTH_ACCESS_KEY_MAX_IDLE_DAYS are rejected, so removing someone from the IdP group revokes their key.
    • MCP multiplexes tools over one POST /mcp, so writes are gated per tool (read-only tools -> viewer, *_source -> admin, rest -> member).
    • Non-admin clickhouse-proxy queries are forced to readonly=2.
  • integrate.mjs — the guard is imported from proxyAuthRoles; a new codemod step gates MCP tools in mcp/utils/registerTool.ts. Rebased onto main, so it sits alongside the x-axis step from fix(sso): show dates on time-chart x-axis ticks for ranges over a day #1: axis is step 4, MCP gating step 5.
  • New env: PROXY_AUTH_MEMBER_GROUPS, PROXY_AUTH_ACCESS_KEY_MAX_IDLE_DAYS (default 30).
  • Default build tag moved to @hyperdx/app@2.42.0.

Roles

Role Who Can
admin PROXY_AUTH_ADMIN_GROUPS everything
member PROXY_AUTH_MEMBER_GROUPS viewer + author dashboards, saved searches, alerts, webhooks, pinned filters
viewer everyone else read; run searches/charts; own favorites, onboarding, access key

Validation

  • Integrates cleanly against @hyperdx/app@2.39.1 and 2.42.0 (all five codemod steps; idempotent on re-run).
  • Every import the overlay needs (User.accessKey, getCounter, models ObjectId, registerTool anchors) exists in both tags.
  • integrate.mjs passes node --check and prettier.
  • Not run locally: full TypeScript type-check / unit run — left to the CI image build (same as fix(sso): show dates on time-chart x-axis ticks for ranges over a day #1).

Deploy notes

  • On a fresh deploy of this build the ProxyAuthRole collection is empty. Each user's record is created on their first browser SSO sign-in. So the provider's API-key owner must sign in once (as member/admin) on the new image before /api/v2 writes are authorized — otherwise the key is rejected as "inactive".
  • Confirm the build tag vs chart appVersion: ClickStack chart 3.4.0 pins appVersion 2.39.1; the default here is now 2.42.0. Build the tag that matches what the chart renders for, or bump the chart.

Adds member between admin and viewer, and authorizes access-key requests
(/api/v2, /mcp) by the key owner's stored role instead of request headers —
so a user can hold an API token without their token carrying write access.

- models/proxyAuthRole.ts: persists each user's last proxy-asserted role
  (viewer|member|admin), groups and lastSeenAt. Access-key requests carry no
  proxy headers, so they are authorized against this record.
- middleware/proxyAuthRoles.ts: app-wide guard. Browser (proxy) requests take
  the role from X-Forwarded-Groups and refresh the record; access-key requests
  resolve the owner, read the stored role, and reject keys whose owner has not
  signed in within PROXY_AUTH_ACCESS_KEY_MAX_IDLE_DAYS. MCP writes are gated
  per tool (read-only tools need viewer, *_source need admin, rest need member).
  Non-admin clickhouse-proxy queries are forced to readonly=2.
- integrate.mjs: role guard now imported from proxyAuthRoles; new step gates
  MCP tools in mcp/utils/registerTool.ts.
- New env: PROXY_AUTH_MEMBER_GROUPS, PROXY_AUTH_ACCESS_KEY_MAX_IDLE_DAYS.
- Default build tag moved to @hyperdx/app@2.42.0.
@github-actions github-actions Bot added the review/tier-3 Standard — full human review required label Oct 29, 2026
@github-actions

Copy link
Copy Markdown

🟡 Tier 3 — Standard

Introduces new logic, modifies core functionality, or touches areas with non-trivial risk.

Why this tier:

  • Diff size: 454 production lines changed (Tier 2 max: < 250)

Review process: Full human review — logic, architecture, edge cases.
SLA: First-pass feedback within 1 business day.

Stats
  • Production files changed: 4
  • Production lines changed: 454 (+ 410 in test files, excluded from tier calculation)
  • Branch: feat/sso-api-key-roles
  • Author: jplorier

To override this classification, remove the review/tier-3 label and apply a different review/tier-* label. Manual overrides are preserved on subsequent pushes.

@github-actions

Copy link
Copy Markdown

PR Review

⚠️ The review did not complete: reviewer produced no structured output.

The next push will retry automatically.

@jplorier
jplorier merged commit e3d20b6 into main Oct 29, 2026
18 of 25 checks passed
@jplorier
jplorier deleted the feat/sso-api-key-roles branch October 29, 2026 17:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

review/tier-3 Standard — full human review required

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant