ADR-009: Rauthy OIDC Authentication
Date: 2026-11-17
Status: Accepted (pending cutover)
Context
ADR-001 relies on a shared symmetric key for user tokens. The API and Flight now run as separate services, so both need that minting secret. SynDB also maintains its own login, token issuance and refresh flows. We want an identity provider without moving SynDB’s authorization policy out of SynDB.
Decision
Use Rauthy for login and issuance of EdDSA-signed OIDC tokens. The API and
Flight use the same local verifier and Rauthy’s public JWKS. For access tokens,
pin alg to EdDSA, the exact issuer including its trailing slash, audience
to syndb-api, header typ to at+jwt, and claim typ to Bearer. Do not
negotiate algorithms. ID and logout tokens have their own pinned types and
client audience.
Cache Ed25519 public keys by kid. For an unknown key, serialize refreshes,
recheck the cache and attempt a JWKS fetch at most once per 60 seconds, with a
five-second timeout. A successful fetch replaces the key set. Known keys remain
usable during fetch failures; an unknown key fails closed, reporting unavailable
if its fetch failed.
For JWTs, resolve human subjects and service client IDs to SynDB users and read
authorization from Postgres on each request. Never trust token role claims.
Service roles are persisted in SynDB. The web flow keeps the existing API-owned
browser session; backchannel logout revokes it. The CLI uses authorization
code with PKCE, a loopback redirect and DPoP. Automation uses
client_credentials. Rauthy uses Hiqlite with S3 backups in a dedicated bucket.
During migration, API and Flight accept both legacy PASETO and Rauthy JWTs. After cutover, stop issuing user PASETOs and drain or revoke legacy refresh tokens. Remove the legacy user-token path only after PASETO validations have been flat for 7 days and no host or Job still holds a password credential. Federation delegation remains a separate PASETO trust domain.
Alternatives Considered
| Alternative | Reason rejected |
|---|---|
Verifier in vendor/queryfabric | It is a foreign repository; reuse its principal type instead. |
jsonwebtoken or openidconnect | Adds a dependency when existing Ed25519 and base64 libraries suffice. |
rauthy-client | Adds dependencies and its own handlers and principal; it does not provide dual acceptance, live authorization or the CLI flow. |
| Dioxus as OIDC client | Duplicates the API’s PKCE, state and return binding. |
| Store Rauthy tokens for the browser session | SynDB does not call Rauthy on the user’s behalf; logout needs only the session ID. |
| Verify DPoP proofs on API and Flight | The decision protects refresh; access tokens are short-lived and Flight lacks proof URL and method rules. |
| SCIM provisioning | Requires a SynDB SCIM server; just-in-time provisioning is simpler. |
Map client credentials to sub | Confuses service and human identity resolution; services use azp. |
| Trust token roles or groups | Authorization must come from SynDB. |
| HAProxy snippet or nginx sidecar for reset denial | A standard Ingress path avoids controller-specific configuration and another container. |
| Device-code login now | Device refresh tokens are not DPoP-bound; the CLI uses the sender-constrained loopback flow instead. |
| Password grant for services | Retains passwords in automation instead of using client credentials. |
| Postgres for Rauthy | Hiqlite and its separate backups reduce coupling to SynDB’s Postgres. |
Consequences
Positive:
- The API and Flight need public verification keys, not Rauthy’s signing key.
- Live authorization makes account and role changes effective on the next request.
- Cached known keys allow existing access tokens to work during a Rauthy outage until they expire, provided Postgres remains available.
Negative:
- A Rauthy outage blocks login and refresh; an unknown signing key cannot be verified without a successful JWKS fetch. Postgres failures also block JWT authorization.
- DPoP constrains refresh tokens, not access-token use at API or Flight. Device-code login stays disabled for now.
- Self-service password reset is disabled at the edge for now; account recovery is operator-assisted, as it is today.
- Password changes do not revoke existing sessions or tokens; this regression was accepted. Academic verification and association remain in SynDB.