diff options
| author | Pjotr Prins <pjotr.public01@thebird.nl> | 2026-10-04 09:20:41 +0000 |
|---|---|---|
| committer | Pjotr <wrk@bosa.lan> | 2026-10-04 09:20:41 +0000 |
| commit | 0a58bfdbec94d3c249a905226bd33480198f2e95 (patch) | |
| tree | 1add70a7555473cd464f3e56ad53f8ebbfde60eb /docs | |
| parent | 6a5f9ef61d19b2a1a3204df223e2ffb21691a988 (diff) | |
| download | genenetwork4-0a58bfdbec94d3c249a905226bd33480198f2e95.tar.gz | |
doc: Update gn-auth.md and RELEASE_NOTES.md for the Rust implementation.
* docs/gn-auth.md: Document the GN2 public>0 AND confidentiality<1 threshold (the test for whether data needs a gn-auth authorization call at all, versus just a valid token), the now-implemented src/auth.rs mechanism, and the four gn-auth bugs found and fixed while building it. * RELEASE_NOTES.md: Likewise. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XDDpXvZBQat9uSgDeEMJ8d
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/gn-auth.md | 59 |
1 files changed, 49 insertions, 10 deletions
diff --git a/docs/gn-auth.md b/docs/gn-auth.md index 42ff910..27bcd88 100644 --- a/docs/gn-auth.md +++ b/docs/gn-auth.md @@ -185,14 +185,53 @@ has many more (`/auth/role/...`, `/auth/user/...`, genenetwork4 doesn't need to talk to gn-auth for every request -- only for the two things above: verifying a presented token's signature (cache the JWKS, refresh periodically, don't refetch per-request), and --- for endpoints that should be scoped to a specific group/species -- -asking gn-auth what that token's holder is allowed to do on that -resource. Endpoints with no sensitive data behind them don't need to -call gn-auth at all. - -This document describes the mechanism; implementing it in Rust -- -likely a custom Axum extractor that verifies the JWT (e.g. via the -`jsonwebtoken` or `josekit` crate for RS256) and yields the resolved -user to handlers that opt in, so endpoints that don't need auth aren't -forced to go through it -- is still to be done. +-- for data that isn't public -- asking gn-auth what that token's +holder is allowed to do on a specific resource. Endpoints with no +sensitive data behind them don't need to call gn-auth at all. + +Whether data "is public" is answered by GeneNetwork's own schema, not +by asking gn-auth: GeneNetwork2 treats a dataset (`ProbeSetFreeze`, +`PublishFreeze`, `GenoFreeze`) as public exactly when +`public > 0 AND confidentiality < 1` (`wqflask/api/router.py`, used +consistently throughout GN2/GN3). `InbredSet`/group rows carry a +`public` column too, but GN2 never actually filters on it anywhere -- +it's informational only there -- so groups/species endpoints need no +gating at all, matching GN2's own behavior. For data that *is* public +by this test, still require a valid token (don't skip verification +entirely), but skip the resource-authorization call to gn-auth -- one +less network round trip for what is, in practice, most of the data. + +### Implemented, in `src/auth.rs` + +- `AuthToken`, an Axum extractor (`impl FromRequestParts`): verifies a + bearer token's RS256 signature and standard time claims (`exp`/`nbf`, + checked when present -- gn-auth itself treats them as optional, + confirmed against its own validator) against a cached, periodically + refreshed JWKS. Add it as a handler parameter to require a valid + token; omit it for endpoints that don't need one. +- `is_publicly_readable(public, confidentiality)`: the GN2 threshold + above, as a plain function a handler calls on its own fetched row. +- `authorise(auth_server_url, token, resource_id, privilege)`: the two + gn-auth calls (resource-id resolution is the caller's job -- + `GET /auth/resource/populations/resource-id/...` -- `authorise` + itself only wraps `POST /auth/resource/authorisation`), with the + per-(user, resource) answer cached briefly so repeated requests for + the same resource by the same user don't each cost a round trip. +- `tests/auth.rs` runs all of this against a real gn-auth instance + (set `GN4_TEST_AUTH_TOKEN`/`GN4_TEST_RESOURCE_ID`; skips otherwise). + +Wiring this into specific existing endpoints (which ones should +require a token at all, and which privilege string each should check) +is a separate decision, not yet made here. + +### Found wrong in gn-auth while building this + +Four bugs in gn-auth itself blocked this integration before they were +fixed (see gn-auth's own `RELEASE_NOTES.md` and its +`fix-fresh-deployment-bugs` branch): a JWKS cache that could stay empty +for hours after a fresh deployment's first token was issued, a dev +client whose secret was never hashed so it could never authenticate, +`public_resources()` crashing on every fresh deployment, and +`POST /auth/resource/authorisation` crashing (instead of degrading to +the anonymous view) on an invalid rather than missing bearer token. |
