Trino Gateway Authentication: BFF API
This page covers how the BFF API authenticates management operations against the Trino Gateway — cluster registration, activation, deactivation, and routing rule updates.
These are administrative operations, not data queries. They do not execute SQL or pass through Ranger.
For user-facing data queries via the gateway, see SQL Auth — Superset, Trino & Ranger.
Routes Covered
All routes are defined in src/routes/trinoRoute.js and protected by validateJWT + exchangeTokenForBackendMiddleware.
| Method | Route | Purpose |
|---|---|---|
GET | /trino/gateway/backend/all | List all registered clusters |
GET | /trino/gateway/backend/active | List active clusters |
POST | /trino/gateway/backend/modify/add | Register a new cluster |
POST | /trino/gateway/backend/modify/update | Update cluster registration |
POST | /trino/gateway/backend/modify/delete | Remove a cluster |
POST | /trino/gateway/backend/activate/:clusterName | Activate a cluster |
POST | /trino/gateway/backend/deactivate/:clusterName | Deactivate a cluster |
POST | /trino/webapp/updateRoutingRules | Update gateway routing rules |
End-to-End Flow
Step 1: JWT Validation — BFF
The validateJWT middleware runs first on every request to these routes. It verifies:
- Token signature against Keycloak's public key
- Token expiry
- Token issuer
If validation fails, the request is rejected before any downstream call is made.
Step 2: Token Exchange — BFF to Keycloak
The exchangeTokenForBackendMiddleware(trinoGatewayAudience) middleware exchanges the validated user JWT for a new token scoped specifically to the Trino Gateway:
- Audience:
${extWorkspaceId}-${config.trino.gatewayAudience}(default:{workspaceId}-trino-gw) - The exchanged token is stored on
req.exchangedToken - The user's original session token is never forwarded to the gateway
- Exchanged tokens are cached in Valkey with a configurable TTL (default: 180s)
The exchange uses the Keycloak RFC 8693 token exchange grant type, implemented in src/clients/keycloakClient.js.
Step 3: Forwarded Request — BFF to Trino Gateway
src/services/trinoService.js (genericTrinoGatewayRequest) forwards the request to the gateway using the exchanged token:
Authorization: Bearer ${req.exchangedToken}
The Trino Gateway validates the token against Keycloak's public key and verifies the audience matches its configured client ID.
These routes manage cluster topology, not data. No X-Trino-User header is set and Ranger is not involved — the gateway itself enforces access based on the token's audience and claims.
Auth Bypass (Break-Glass)
The Trino Gateway also accepts basic authentication via the gateway preset user, credentials stored in the trino-gw-basic-auth Kubernetes secret. This path is not used by the BFF under normal operation — it exists as a break-glass fallback for internal platform tooling.
TODO: Document which platform components (if any) use the basic auth fallback in production, and whether there are alerting or audit controls on its use.
Use of the break-glass credential is not audited or alerted on. Queries submitted via this path are indistinguishable from normal gateway traffic unless Ranger is explicitly configured to flag the gateway username. See Security Gaps.
Configuration
| Config key | Env var | Default | Purpose |
|---|---|---|---|
trino.gatewayUrl | TRINO_GATEWAY_URL | TRINO_URL | Gateway endpoint |
trino.gatewayAudience | TRINO_GATEWAY_AUDIENCE | trino-gw | Keycloak audience for exchange |
Go Deeper
- Token Exchange and Data Access — token exchange model
- Trino Gateway Auth — gateway OAuth2 setup and audience configuration
- SQL Auth — Superset, Trino & Ranger — data query auth (separate flow)