Expose the Orbit web server directly on token-exchange authentication (Orbit out of the monolith)

Problem to solve

Orbit's query path runs inside a Rails request: Rails authenticates the caller, mints the scope token, opens the gRPC stream, answers redaction in-process and streams the result back (ADR 022, 2026-10-28). No client connects to Orbit directly: the web server listens on gRPC 50054 only, and the only HTTP listener is the health check. Every change to the query path is a Rails change, every query holds a Puma thread, and slow queries count against the Rails apdex.

Proposed solution

Move the front door to Orbit. Clients call the Orbit web server directly and Rails becomes an authentication and authorization service that Orbit consults.

Authentication follows the Artifact Registry pattern: a short-lived Rails-issued JWT from POST /api/v4/token_exchange, validated locally against the instance JWKS, swapped for a GATE URT once the STS exists (AUTH-021).

Authorization does not follow AR. AR owns its roles and evaluates them in embedded GLAZ. Orbit mirrors Rails permissions, and tier-3 redaction depends on rules only Rails has (confidential issues, SAML, IP restrictions, custom roles), so Orbit keeps asking Rails per entity over #1495 until GATE L2 carries fine-grained permissions in the token.

Done means the Orbit dashboard, glab orbit, DAP flows and REST callers reach Orbit without a Rails request in the path, on GitLab.com first.

Design

  1. Clients authenticate with an exchanged token, not a GitLab credential. Add a gitlab-orbit audience to SUPPORTED_AUDIENCES. The token carries the AUTH-021 payload plus Orbit's scope claims (group_traversal_ids with access levels, source_type, root_namespace_id, token_type). Entitlement (enabled_for?, license, enabled namespaces) is checked at mint, as AR does. Max TTL for this audience is 5 minutes, the lifetime the scope token has today. glab already has the credential-helper hook (#1204); the dashboard fetches its token from Rails on the session; DAP mints inside the flow.
  2. Orbit validates RS256 against the instance JWKS. Replace the HS256-only validator with a JWKS client (kid, rotation overlap). Use aws-lc-rs for the RSA verify, already Orbit's FIPS module, so RUSTSEC-2023-0071 on the rsa crate is not a blocker. Closes #181 for the query path; the shared secret stays for the indexer's service token.
  3. Redaction becomes Orbit-initiated over #1495. Orbit calls batch_check with its service credential and forwards the caller's exchanged token as the user proof. This drops the qid binding from #1495, because Rails no longer opens the query; exp and aud bind the call instead. Fail closed as specified there.
  4. Orbit grows an HTTP front: REST query, context, grep, skills, and MCP. Envoy in the Orbit clusters is the ingress (planned for code indexing in #1277); it terminates TLS, holds rate limits (replacing check_rate_limit!(:orbit_query)) and records client IP. On GitLab.com the Cells HTTP Router routes /-/orbit/ to that ingress, so the dashboard stays same-origin with no CORS or cookie scoping. KAS at /-/kubernetes-agent/ is the precedent.
  5. Rails keeps /api/v4/orbit/* as a compatibility proxy that exchanges the caller's credential and forwards to Orbit. Removed one milestone after the last client moves. Nothing in Rails is deleted before shadow traffic shows parity.
  6. MCP moves last. Direct MCP needs Orbit to be an OAuth resource server; Doorkeeper tokens are opaque, so this lands with IAM-issued JWT access tokens (gliamat-, AUTH-011 rollout) rather than an introspection callback.

Delivery (proposed sequence, milestones indicative)

  1. 19.7, gitlab-org/gitlab: gitlab-orbit audience and scope claims in token exchange, behind a feature flag. Context Systems with Authentication review.
  2. 19.7, knowledge-graph: JWKS validator (#181); keep HS256 for the indexer.
  3. 19.7–19.8, both repos: #1495 batch_check and the Orbit Check provider with stream and http transports. Shared API ownership to settle with the Authorization group.
  4. 19.8, knowledge-graph and Orbit clusters: HTTP listener plus Envoy ingress (#1277 scope) on staging.
  5. 19.8, Cells HTTP Router: /-/orbit/ rule to the Orbit ingress on staging, then production behind a percentage. With Tenant Scale.
  6. 19.9, gitlab-org/gitlab: dashboard, glab and DAP switch to direct calls; Rails path becomes the proxy. REST deprecation notice.
  7. 19.10+: MCP direct once IAM access tokens are live; remove the proxy.

Open questions

  • Shape of the user proof for batch_check when Rails is not the caller: the exchanged token itself, or a second capability token minted at exchange. @dgruzd @skundapur
  • Where /api/v4/internal/authz/ lives organizationally (Authorization group or Context Systems). @grzesiek
  • Whether the Cells HTTP Router takes a path rule for Orbit before GATE L1 Envoy exists. @meddington and Tenant Scale.
  • Client IP and SAML state without a Rails request (see Risks). @ggray-gitlab and AppSec.

Auth stack contacts: @grzesiek, @skundapur, @meddington. AR precedent: &21743, &22004.

Agent context: current state, verification, alternatives, risks, sources

Current state (gitlab-org/gitlab master 6e4429dd, knowledge-graph main, 2026-11-13)

  • Workhorse path removed on 2026-10-18 (gitlab-org/gitlab@38da7b20); 19.6 ships Rails-only.
  • Rails per request: authenticate!, read_api scope, KnowledgeGraph.enabled_for?, OrbitLicense.available_for?, enabled namespaces, orbit_query rate limit, source-type classification (frontend, dws, mcp, rest, code_intelligence) for billing, then mints an HS256 JWT with group_traversal_ids capped at 500 (jwt_auth.rb).
  • Orbit's validator accepts HS256 only; asymmetric keys open since February (#181).
  • Redaction runs in the stream with Rails as caller; #1495 (2026-11-12) proposes /api/v4/internal/authz/batch_check with a Rails-signed ES256 capability token.
  • Token exchange is experimental: RS256 via Cloud Connector keys, audiences gitlab-artifact-registry and gitlab-autoflow, ".com-only at launch; SM/federated origins TBD" (token_issuer.rb).
  • GATE L2 STS and Envoy are not deployable on Omnibus or CNG yet; L1/L2 authorization alphas are open past their dates (&17711 children). Plan for the interim token, design for the URT.
  • Precedent for exposing a sidecar through GitLab's edge: KAS at /-/kubernetes-agent/ with its own Rails JWT; KAS links GLAZ via glaz-ffi (AUTH-018).

Verification

  • glab orbit query against /-/orbit/ on staging returns the same rows as /api/v4/orbit/query for the same user: shadow comparison on a capped sample, zero unexplained differences before the flip.
  • A token with a tampered group_traversal_ids claim, an expired token, and a token for another audience are each rejected before compilation.
  • Redaction over batch_check matches the in-stream exchange for confidential issues, IP-restricted groups and SAML-enforced groups (the #1495 acceptance tests).
  • p50 and p99 end-to-end latency at or under ADR 022's Rails numbers (45 ms / 757 ms on 2026-10-28).
  • AppSec review of the ingress, the token audience and the IP/SAML handling before the compatibility proxy is removed.

Alternatives considered

  • Keep Rails as the front door and only cache the scope token: fixes the per-request AuthorizationContext cost but leaves every query on a Puma thread and every path change a Rails change.
  • Orbit accepts PATs and exchanges them on behalf of the caller: Orbit would hold user credentials in memory; rejected for the same reason AR never sees client credentials.
  • Embed GLAZ in Orbit, as AR does: Orbit has no roles of its own and tier 3 depends on Rails-only rules; revisit when GATE L2 mints URTs with permissions.
  • Separate Rails fleet for Orbit queries: rejected in ADR 022.
  • Wait for GATE L2 STS and Envoy: no deployable path on Omnibus/CNG and open alphas; the interim token exists now and the URT swap is a key-source change, as AR's plan assumes.

Risks

  • Client IP and SAML state no longer come from a Rails request: #1495 carries IP in a Rails-signed claim, which standalone cannot do. Envoy must stamp a trusted IP header and SAML session enforcement needs a stateless form or re-evaluation.
  • Token exchange is .com-only and signs with Cloud Connector keys (EE). SM and Dedicated direct ingress waits on the SM origin shape (AUTH-021 cross-realm) or GATE L2 in CNG; the Rails path stays for them.
  • Billing classification (source_type) moves into the exchange; mint it from the credential type in Rails, never from a client header.
  • If the HTTP Router rule slips, fall back to a Workhorse location block for /-/orbit/ (the KAS pattern), which also serves SM later.
  • Rate limits and quota checks split across Envoy and Orbit; one owner per limit, written down before the flip.

Sources

ADR 022, ADR 008; #1495, #181, #1277, #570, #1314; gitlab-org/gitlab@38da7b20, gitlab-org/gitlab@dfb289d4, gitlab-org/gitlab@45e1ab28; AUTH-016, AUTH-018, AUTH-021, proposal 014; AR and Auth Platform interface agreement; Orbit security docs; Zoekt query authorization spec; &17711, &21743, &22004, &23581.