Skip to content

Embedded UI Gateway Contract v1

As of: April 10, 2026

Purpose

Define the platform-owned gateway contract for exposing third-party or workload-owned UIs inside the GPUaaS workload shell.

This document exists because embedding an app UI is not an iframe styling task. It is an auth, session, cookie, WebSocket, and support-boundary decision.

Scope

In scope: 1. supported exposure modes, 2. reverse-proxy route shape, 3. auth and session ownership, 4. cookie and origin rules, 5. WebSocket behavior, 6. CSP and frame policy expectations, 7. explicit link-out fallback criteria.

Out of scope: 1. implementation of the gateway itself, 2. app-specific proxy adapters, 3. final browser UX polish, 4. replacing app-native authorization models internally.

Decision Summary

The platform supports three UI exposure modes:

  1. native
  2. embedded
  3. link_out

Embedding is allowed only when the app satisfies the platform gateway contract. If it does not, the platform must intentionally use link_out.

link_out is a first-class product mode, not a degraded failure case.

Non-Negotiable Rules

  1. The platform owns user authentication at the workload shell boundary.
  2. The platform decides whether embedding is allowed.
  3. The app manifest may declare capability, but it does not unilaterally force embedding.
  4. Browser traffic for embedded UIs must pass through a platform-controlled reverse proxy.
  5. Raw app cookies and browser trust assumptions must not bypass the platform shell.

Supported Modes

native

No external app UI is embedded.

The workload detail page remains platform-native and surfaces: 1. status, 2. members, 3. events, 4. access details, 5. any platform-owned controls.

Examples: 1. early self-managed Kubernetes where kubeconfig is delivered but no dashboard is embedded, 2. native Slurm first slice.

embedded

The app UI is presented inside the workload shell through a platform reverse proxy and must satisfy this contract.

Examples that may fit: 1. Grafana, 2. a future Rancher UI if the auth model is made safe, 3. certain internal dashboards.

The workload shell shows an Open app action and opens the app in a new tab or window.

Use this when: 1. auth cannot be safely proxied, 2. the app requires incompatible cookie behavior, 3. the app assumes unsupported path or origin behavior, 4. the app relies on browser features that the embedded gateway cannot support.

Examples: 1. Open OnDemand until the full auth/filesystem model is understood, 2. applications with complex login redirects and cross-site session assumptions.

Route Shape

Embedded traffic should be routed through a stable platform path family.

Directionally:

/workloads/{instance_id}/ui
/workloads/{instance_id}/ui/{proxy_path...}

or internally:

/api/v1/workloads/{instance_id}/ui/session
/internal/v1/workloads/{instance_id}/ui/proxy/{proxy_path...}

The exact public shape may vary, but the invariant is: 1. workload identity is explicit, 2. the platform gateway remains the browser-facing origin, 3. authorization is checked against workload access before proxying.

Auth Ownership

Platform-owned shell session

The browser authenticates to GPUaaS first.

The shell evaluates: 1. user identity, 2. tenant/project scope, 3. workload visibility, 4. workload access policy.

Gateway-minted app session

For embedded, the gateway may establish an app-side session on behalf of the user, but only after workload access is authorized by the platform.

Allowed directionally: 1. header injection, 2. short-lived gateway session token, 3. app-specific bootstrap handshake through the proxy.

Not allowed: 1. exposing raw long-lived app credentials to the browser, 2. bypassing platform access checks, 3. depending on query-string tokens.

Session Model

The platform must define which session is authoritative.

Required invariant

The GPUaaS shell session remains the outer authority.

That means: 1. logout from GPUaaS invalidates future embedded access, 2. access revocation at the platform boundary stops new proxy requests, 3. workload UI exposure must not outlive the platform decision indefinitely.

Direction for embedded sessions

If the app requires its own session, it should be: 1. short-lived, 2. minted by the gateway, 3. bound to workload and user context, 4. renewable only through the platform boundary.

Cookie handling is the main reason many apps fail to embed safely.

Allowed direction

The embedded gateway should prefer same-origin proxy behavior where the browser only sees platform-origin traffic.

This lets the platform: 1. keep app cookies off unrelated origins, 2. avoid third-party-cookie dependence, 3. align CSRF and logout handling.

App requirements for embedded

The app must tolerate: 1. proxied path prefixes or rewritten root paths, 2. same-origin gateway behavior, 3. forwarded headers that identify original host/scheme, 4. cookie scoping compatible with the proxied path/origin.

If the app cannot tolerate these, use link_out.

CSRF Model

For embedded, the gateway must make the CSRF story explicit.

Directionally the platform should support: 1. same-origin proxying, 2. app sessions scoped to the gateway origin/path, 3. forwarded headers needed for app-side CSRF checks, 4. deny-by-default behavior when the app assumes unsupported cross-site patterns.

The gateway must not suppress CSRF protections just to make embedding work.

WebSocket Contract

Some UIs depend on live upgrades: 1. terminals, 2. dashboards, 3. streaming consoles, 4. interactive control-plane views.

For embedded, the gateway must support: 1. HTTP upgrade, 2. workload-scoped auth on upgrade, 3. correct forwarding of connection headers, 4. bounded session lifetime, 5. audit visibility for connect/disconnect when appropriate.

If the app requires unsupported socket behavior, use link_out.

Content Security Policy and Frame Rules

The platform should not rely on permissive iframe behavior.

Preferred direction: 1. same-origin reverse proxy, 2. no dependence on third-party framing, 3. explicit CSP for proxied routes, 4. deny apps that require unsafe frame or script behavior.

Practical rule

If an app requires broad frame-ancestors *, unsafe script exceptions, or host-level browser settings to embed, it is not ready for embedded.

App Capability Declaration

The app catalog or app artifact metadata may directionally declare: 1. ui.mode_supported 2. ui.requires_websocket 3. ui.path_prefix_safe 4. ui.same_origin_proxy_safe 5. ui.cookie_constraints

But that declaration is only capability metadata.

The platform still decides final exposure mode based on: 1. environment support, 2. gateway support, 3. security review, 4. product support boundary.

The platform must choose link_out when any of these hold:

  1. app auth cannot be safely initiated by the gateway,
  2. app cookies require unsupported cross-site behavior,
  3. app breaks behind path-prefix proxying and cannot be normalized,
  4. app requires unsupported WebSocket or streaming semantics,
  5. app CSP or frame requirements violate platform security posture,
  6. app logout/session expiry cannot be reconciled with the platform shell,
  7. product support wants the app to remain operationally separate.

Audit Expectations

The platform should audit: 1. gateway session issuance, 2. exposure-mode decision where it is operator-controlled, 3. denied embedded access, 4. link-out token/session issuance if any exists, 5. privileged configuration changes enabling embedded mode.

The platform does not need to mirror every app-internal click. It does need to audit the platform boundary.

Environment and DNS Assumptions

Embedded UI routes must follow the platform endpoint model.

They should not depend on: 1. raw node IPs, 2. direct app hostnames that bypass platform TLS and auth, 3. browser trust exceptions.

This keeps embedded UI aligned with: 1. doc/architecture/Platform_DNS_Cert_Endpoint_Model_v1.md 2. the workload route model in the navigation design.

Product Support Boundary

An embedded app is not automatically equivalent to a fully platform-owned app.

The product must still document: 1. what the platform supports, 2. what remains the tenant's responsibility, 3. whether the platform only proxies the UI or also owns lifecycle and health.

This matters especially for: 1. Rancher, 2. Grafana, 3. Open OnDemand.

First Application of This Contract

Recommended sequence:

  1. Keep early self-managed Kubernetes as native.
  2. Treat Grafana as the first realistic embedded validation candidate.
  3. Treat Rancher as link_out until the full auth/session model is proven safe.
  4. Treat Open OnDemand as link_out until filesystem and audit boundaries are intentionally defined.

Immediate Follow-On Work

  1. reserve workload UI capability metadata in the app/runtime model,
  2. define gateway-issued session/token semantics if embedding is implemented,
  3. add workload-shell App UI tab behavior for native, embedded, and link_out,
  4. implement only after the security and auth boundary is explicitly approved.

Non-Goals

  1. promising that every app can embed,
  2. replacing app-native IAM internally,
  3. solving filesystem semantics for OOD in this document,
  4. implementing the proxy in this slice.
  1. doc/product/Navigation_Redesign_App_Platform_v1.md
  2. doc/architecture/Kubernetes_Platform_Options_v1.md
  3. doc/product/Slurm_UI_Options_v1.md
  4. doc/architecture/Platform_DNS_Cert_Endpoint_Model_v1.md