MechaCat02
bf2e542182
Summarises the running container's keepalive: extension count, latest budget, transient failures, rejections, restarts. It deliberately makes no API call. Any authenticated request slides the session TTL, so a checker that talked to Schulcloud would be sustaining the session itself and could not report on whether the keepalive is doing it — the same confound that made the first endurance test ambiguous. Reading container logs observes without participating. Warns when the reported budget drops below 7000s, which is the early signal that extensions have stopped taking effect. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
175 lines
8.3 KiB
Markdown
175 lines
8.3 KiB
Markdown
# Authentication
|
|
|
|
## What this server uses
|
|
|
|
The `jwt` cookie from a logged-in browser session, sent verbatim as
|
|
`Authorization: Bearer <token>`. That is the whole mechanism.
|
|
|
|
This was worth confirming rather than assuming, because the obvious reading of
|
|
"it's a cookie" leads somewhere much more complicated. Verified live:
|
|
|
|
```
|
|
Authorization: Bearer <jwt> → 200 # what this server does
|
|
Cookie: jwt=<jwt> → 200 # also works
|
|
(no auth) → 401
|
|
```
|
|
|
|
`connect.sid`, `SERVERID` and `isLoggedIn` are **not** needed — there is no
|
|
cookie jar. There *is* a session to keep alive, though not in the way the
|
|
cookies suggest; see the next section.
|
|
|
|
## Token lifetime, and the thing that actually kills it
|
|
|
|
Two clocks govern the token:
|
|
|
|
| Clock | Value | Notes |
|
|
|---|---|---|
|
|
| **Session** — a whitelist entry in Valkey, `jwt:{accountId}:{jti}` | `JWT_TIMEOUT_SECONDS` = **7200 s** | **Sliding**: every authenticated request re-sets it |
|
|
| **Hard expiry** — the JWT's own `exp` claim | **30 days** | Cannot be extended |
|
|
|
|
`JwtStrategy.validate()` calls `JwtWhitelistAdapter.isWhitelisted()`, which
|
|
reads the key, throws
|
|
`'Session was expired due to inactivity - autologout.'` if it is gone, and then
|
|
**re-sets it** with a fresh TTL. The legacy Feathers implementation does the
|
|
same. So the window really does slide with use, and a keepalive holds a session
|
|
up to the 30-day ceiling.
|
|
|
|
### But a browser tab will log this server out
|
|
|
|
The trap is not a clock at all. **The `jwt` cookie you copy is the browser's own
|
|
session token — same `jti`.** This server and that tab share one session, and
|
|
the tab will end it:
|
|
|
|
1. On login the front end starts a **purely client-side** timer:
|
|
`sessionTimeoutTimestamp = Date.now() + JWT_TIMEOUT_SECONDS`. It is reset
|
|
only on *route change* — `watch(router.currentRoute, startTimer)` — never by
|
|
API activity, and never read back from the server's real TTL.
|
|
(`nuxt-client/src/modules/data/application/application.store.ts`)
|
|
2. After `JWT_SHOW_TIMEOUT_WARNING_SECONDS` (3600 s) remain it shows the
|
|
"Sitzung verlängern" dialog. (`AutoLogoutWarning.vue`)
|
|
3. At zero it calls `autoLogout()` →
|
|
`location.replace('/logout?auto-logout=true')`.
|
|
4. That route, in the legacy client, issues `POST /api/v3/logout`
|
|
(`schulcloud-client/controllers/login.js:439`) →
|
|
`removeJwtFromWhitelist(jwt)` → **the shared key is deleted.**
|
|
|
|
An idle tab therefore revokes this server's token about two hours after login,
|
|
no matter how diligently the server refreshes it. Measured exactly that way: a
|
|
keepalive pinged successfully at t+0/30/60/90 and was dead by t+120, ~2 h after
|
|
login, while `exp` still had 29 days left.
|
|
|
|
Note the timer is client-side and reset only by navigation. That is why the
|
|
dialog appears after an idle hour even in a tab you consider "in use", and why
|
|
no amount of API traffic prevents it.
|
|
|
|
### So: close the tab
|
|
|
|
**After copying the `jwt` cookie, close the Schulportal tab** — all of them; the
|
|
front end also syncs logout across tabs over a `BroadcastChannel`. Closing a tab
|
|
runs no logout itself (`autoLogout` fires only from the expiry timer), so the
|
|
session survives on the server with nothing left to revoke it.
|
|
|
|
The tidiest recipe is a **private/incognito window**: log in there, copy the
|
|
`jwt`, close the window. That session is separate from your normal browsing, and
|
|
`POST /api/v3/logout` only ever removes its own `jti`, so your everyday session
|
|
and this server cannot end each other.
|
|
|
|
With no tab attached, the keepalive holds the session to the 30-day hard expiry,
|
|
and replacing the token becomes the monthly chore it looked like at first.
|
|
|
|
### There is no longer window available
|
|
|
|
`config/default.schema.json` documents `JWT_EXTENDED_TIMEOUT_SECONDS`
|
|
(2629746 s ≈ 1 month), reachable in the legacy stack via a `privateDevice`
|
|
login flag. On the current NestJS server that is vestigial: `privateDevice` has
|
|
no references in `apps/server/src`, and `generateJwtAndAddToWhitelist` calls
|
|
`addToWhitelist` with no TTL override. A "remember me" login buys nothing.
|
|
|
|
## How this server stays alive
|
|
|
|
`src/keepalive.ts` calls `POST /api/v3/authentication/refresh-session` every 30
|
|
minutes (`KEEPALIVE_INTERVAL_MS`; `0` disables it), from both entry points and
|
|
independently of whether any MCP client is connected — the session expires on
|
|
wall time, not on usage. It logs the budget each time:
|
|
|
|
```
|
|
[schulcloud-mcp] keepalive: session extended, 7200s (120 min) of budget left
|
|
```
|
|
|
|
A plain `GET` would also slide the TTL today. `refresh-session` is used anyway
|
|
because it states the intent contractually rather than relying on a side effect
|
|
of an unrelated read — upstream has refactored this whitelist twice in 2026, and
|
|
a GET-based keepalive would fail *silently* if extend-on-check ever went away.
|
|
The budget readout also turns "is the session healthy" into something the log
|
|
answers directly.
|
|
|
|
**It is the one non-GET request in the server.** No body, touches only the
|
|
caller's own session, cannot read or modify user data, and is not exposed as a
|
|
tool — so no model-driven call can ever be a POST, and the property that matters
|
|
is intact: nobody reaching this endpoint can act as the user in Schulcloud.
|
|
|
|
A transient failure retries in 5 minutes. A `401` stops the keepalive
|
|
permanently and says what to do, because a deleted whitelist entry cannot be
|
|
revived by retrying — and if it happens roughly two hours after login, suspect
|
|
an open tab before anything else.
|
|
|
|
Two ways to check that a token is holding:
|
|
|
|
- `npm run keepalive-status` reads the running container's logs and summarises
|
|
its extensions. It makes **no** API call on purpose — any authenticated
|
|
request slides the TTL, so a checker that talked to Schulcloud would be
|
|
keeping the session alive itself and could not tell you whether the keepalive
|
|
works.
|
|
- `npm run session-diagnose` calls refresh-session every 10 minutes for ~2.5 h
|
|
and logs the budget, for when there is no container to read logs from.
|
|
|
|
**Operational consequence:** if the container is down for over two hours the
|
|
session lapses on its own, and restarting will not recover it. The startup log
|
|
says so immediately:
|
|
|
|
```
|
|
[schulcloud-mcp] keepalive: token rejected (401). The session is gone …
|
|
```
|
|
|
|
## Why not username + password
|
|
|
|
The instance's login redirects to Keycloak (realm `TIS`) with a `redirect_uri`
|
|
pointing back at Schulcloud's own server, so the authorization-code exchange
|
|
happens server-side with a client secret only Schulcloud holds. A third party
|
|
cannot replicate that flow. `POST /api/v3/authentication/local` exists but is
|
|
for accounts with local credentials, which federated school accounts do not
|
|
have.
|
|
|
|
Given a keepalive that holds a session to its 30-day ceiling, the pasted-JWT
|
|
approach is the right trade: one manual step a month against re-implementing an
|
|
OAuth client whose secret we cannot hold. If that monthly step ever becomes
|
|
unacceptable, the honest options are a service account issued by the school's
|
|
IDM, or driving the Keycloak login with a headless browser — not a
|
|
reimplementation of the code exchange. If this ever needs to be unattended, the honest options are a service
|
|
account issued by the school's IDM, or a headless browser login — not a
|
|
reimplementation of the Keycloak exchange.
|
|
|
|
## Protecting this server's own endpoint
|
|
|
|
Distinct from the above, and just as important. The MCP endpoint is reachable
|
|
from the public internet by construction: Claude's connectors call it from
|
|
Anthropic's cloud, not from your machine. It is protected by `MCP_AUTH_TOKEN`,
|
|
a shared secret checked in constant time on every `/mcp` request
|
|
(`src/http/auth.ts`), accepted as either `Authorization: Bearer …` or
|
|
`X-Api-Key`. `/healthz` is deliberately open and reveals nothing.
|
|
|
|
Generate one with `openssl rand -hex 32`. If it is unset the server logs a loud
|
|
warning and serves unauthenticated — only acceptable bound to localhost.
|
|
|
|
Rotating it: change `MCP_AUTH_TOKEN` in `.env`, restart the container, update
|
|
the connector in Claude. Nothing else stores it.
|
|
|
|
## Blast radius
|
|
|
|
Every path in this server is a `GET`, including the `api_get` escape hatch,
|
|
which rejects anything not starting with `/api/` and anything carrying a scheme
|
|
or host. Someone who obtained both the endpoint URL and `MCP_AUTH_TOKEN` could
|
|
read this account's Schulcloud data; they could not post, submit, delete, or
|
|
otherwise act as the user. Keep it that way — adding a single write tool would
|
|
change that property entirely.
|