Reference implementation

FINNS built a small booking site that implements this whole integration, so the contract is proven end to end. It has no real inventory: checkout books a fixed demo package. Use it to see the flows working and to compare behaviour.

Test URL: https://trident-poc-booking.juna.workers.dev

Runtime

Cloudflare WorkersTypeScript 6no framework

Storage

Cloudflare D1 (SQLite)Read replication off: a sign-out must be visible to the very next request.

Libraries

oauth4webapi (OIDC)jose (logout token)

Protection

Workers rate limitingsealed cookies (AES-GCM)

Tests

Vitest@cloudflare/vitest-plugin

Routes

flowchart LR
  classDef page fill:#E3F4F3,stroke:#13686C,color:#12191B
  classDef api fill:#ffffff,stroke:#13686C,color:#12191B
  classDef ours fill:#13686C,stroke:#0B4A4D,color:#ffffff
  classDef ext fill:#F3ECDF,stroke:#B9A88B,color:#12191B

  home["GET /<br/>silent sign-in"]:::page
  login["GET /auth/login · /redirect<br/>OIDC sign-in"]:::page
  ho["GET, POST /auth/handoff<br/>peek, confirm, redeem"]:::page
  co["GET, POST /checkout<br/>fresh sign-in, report booking"]:::page
  out["POST /auth/logout<br/>this site only"]:::page

  kc["Keycloak"]:::ext
  core["Core"]:::ours

  rev["POST /auth/revoke"]:::api
  bcl["POST /auth/backchannel-logout"]:::api

  home --> kc
  login --> kc
  ho --> core
  co --> core
  kc --> bcl
  core --> rev

Table (D1)	Holds
session	SHA-256 of the session id, sub, sid, source (handoff or oidc), reauth_at, expiry
revoked_sid	Signed-out Keycloak sessions, kept 1 h
signed_out_sub	Signed-out members, kept 10 h
logout_jti	Seen logout tokens, to block replay

Vendor checklist

• Register a Keycloak client: redirect URIs, back-channel logout URL with session required.
• Handoff: code out of the URL, peek on GET, confirmation page, redeem on same-origin POST, rate limit per IP.
• OIDC sign-in with PKCE and nonce; silent sign-in at most once per visit window.
• Fresh sign-in (prompt=login, max_age=0, check auth_time) before every payment; handoff sessions can never pay.
• Report each paid booking with a stable bookingId, from the backend, retried with the same body until answered.
• /auth/revoke at the origin root: constant-time bearer check, delete sessions, remember the sign-out, answer 200.
• Back-channel logout with full JWT verification and jti replay protection.
• Short, absolute sessions; only hashes of session ids stored.
• Never log codes, session ids, tokens, emails, sub or booking ids.

Local development only

Demo tokens in the repository’s .dev.vars, plain cookie names over http://localhost, the fixed demo booking total, and the test helpers that fake Keycloak and core are for local development only.