Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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

AlternativeReason rejected
Verifier in vendor/queryfabricIt is a foreign repository; reuse its principal type instead.
jsonwebtoken or openidconnectAdds a dependency when existing Ed25519 and base64 libraries suffice.
rauthy-clientAdds dependencies and its own handlers and principal; it does not provide dual acceptance, live authorization or the CLI flow.
Dioxus as OIDC clientDuplicates the API’s PKCE, state and return binding.
Store Rauthy tokens for the browser sessionSynDB does not call Rauthy on the user’s behalf; logout needs only the session ID.
Verify DPoP proofs on API and FlightThe decision protects refresh; access tokens are short-lived and Flight lacks proof URL and method rules.
SCIM provisioningRequires a SynDB SCIM server; just-in-time provisioning is simpler.
Map client credentials to subConfuses service and human identity resolution; services use azp.
Trust token roles or groupsAuthorization must come from SynDB.
HAProxy snippet or nginx sidecar for reset denialA standard Ingress path avoids controller-specific configuration and another container.
Device-code login nowDevice refresh tokens are not DPoP-bound; the CLI uses the sender-constrained loopback flow instead.
Password grant for servicesRetains passwords in automation instead of using client credentials.
Postgres for RauthyHiqlite 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.