mancala/docs/specs/keycloak-auth/design.md

Login with Keycloak: design

See requirements.md for what is built; requirement ids (R1.1, …) are referenced below.

Decisions

Decision	Reason
Keycloak is the only auth system; guests are Keycloak users too	Considered first: a separate auth service issuing guest tokens next to Keycloak, and guest tokens issued by the backend. Both meant two auth systems. With guests inside Keycloak, the backend trusts one token issuer (R8.1).
Guests via a custom authenticator (Java SPI extension), not the admin API	Creating guests through the admin API needs a privileged service account and a second component; an authenticator runs inside the normal login flow, so guests get ordinary sessions and refresh tokens.
The guest flow is triggered by a guest=true parameter on the authorization request	Keycloak keeps extra request parameters as client notes (client_request_param_guest), so the authenticator can read it without UI. Requests without it get the login form.
Guests are marked with a realm role, not a user attribute	Roles are in the access token by default (realm_access.roles) and need no user profile changes; the cleanup task can list role members.
Guests request offline_access	Offline sessions outlive the SSO session (30 days idle), which keeps a guest's identity across browser restarts (R1.2).
"Verify profile" is disabled for the realm	Otherwise Keycloak asks every new guest for an email and name. Registration still asks for the required fields.
The backend verifies tokens offline with the realm's public keys (jose)	No call to Keycloak per connection; Keycloak being down only stops new logins (R8.1).
The WebSocket authenticates with a first auth message, not a URL parameter	Tokens in URLs end up in proxy logs; browsers cannot set headers on WebSockets.
Keycloak user ids are prefixed with kc:	Legacy userKeys are UUIDs chosen by the client; the prefix makes it impossible for a legacy client to claim a Keycloak user's id (R7.2).
Web login with oidc-client-ts	Standard OIDC with PKCE and refresh tokens, without tying the app to a Keycloak-specific library.
Login, sign up and log out only on the home page	Changing identity during a game would lose the player's seat (R3.3).

Keycloak (apps/keycloak)

• Image: Dockerfile builds the extension with Maven and copies it with the realm file into quay.io/keycloak/keycloak:26.7.5, started with --import-realm (the realm is imported only if it does not exist).
• Realm mancala (realm/mancala-realm.json):
  • Client mancala-web: public, authorization code with PKCE S256, redirect URIs http://localhost:1234/* and https://playmancala.app/*, the same post-logout redirects.
  • Browser flow browser with guest: cookie (alternative) → mancala-guest-authenticator (alternative) → username/password form (alternative). A returning user with a session is let through by the cookie step, so guest=true with an existing session reuses that identity.
  • Realm role guest; offline session idle timeout 30 days; registration and password reset on; brute force protection on; required actions as Keycloak's defaults with VERIFY_PROFILE disabled.
• Extension (extension/, package app.playmancala.keycloak.guest):
  • GuestAuthenticator: with guest=true creates guest- + 8 random hex characters, grants the guest role and succeeds; otherwise attempted().
  • GuestCleanupTask (R1.3): scheduled through Keycloak's TimerProvider; deletes guests created more than cleanup-min-age-seconds ago (default 86400) that have neither a user session nor an offline session; runs every cleanup-interval-seconds (default 3600), at most cleanup-max-deletes-per-run (default 1000) per run. Options are set as KC_SPI_AUTHENTICATOR__MANCALA_GUEST_AUTHENTICATOR__….
• Compose: keycloak service on 127.0.0.1:8080, KC_HOSTNAME from KEYCLOAK_HOSTNAME, proxy headers on.
• nginx (config/nginx.conf): auth.playmancala.app proxies to Keycloak; the authorization endpoint is limited to 10 requests per minute per IP with bursts of 20 (R1.4).

Backend (apps/backend/src/auth, rtmt/rtmt_websocket.ts)

• KeycloakTokenVerifier checks signature (RS256, keys from KEYCLOAK_JWKS_URL or the issuer's certs endpoint, cached by jose), iss, exp, typ: Bearer and that azp is one of KEYCLOAK_CLIENT_IDS (R2.2). It returns { id: "kc:" + sub, name: preferred_username, isGuest: has role guest }.

• WebSocket protocol (channels in @mancala/core):

  Channel	Direction	Payload
  auth	client → server	{ token }, right after connecting and after every token refresh
  on_auth	server → client	{ user: AuthUser }
  on_auth_error	server → client	{ reason }, then the socket is closed with code 4001

  Messages before on_auth are ignored; no auth within 5 seconds closes the socket (R2.4). A socket may send a new token for the same user but not switch users.

• Connections: Map<userId, Set<WebSocket>>; messages go to every socket of a user; the user is offline when the set is empty; a closing socket only removes itself (R4).

• Legacy: with LEGACY_USERKEY_AUTH=true, ?userKey=<uuid> binds the socket to that id directly and /register issues ids; non-UUID keys (e.g. kc:…) are refused (R7).

• Games store each player's name and guest flag when they start and send them in the connection info (R5.1).

• Malformed messages are ignored instead of throwing.

Variable	Default
KEYCLOAK_ISSUER	http://localhost:8080/realms/mancala
KEYCLOAK_JWKS_URL	issuer + /protocol/openid-connect/certs
KEYCLOAK_CLIENT_IDS	mancala-web
LEGACY_USERKEY_AUTH	true

Shared client code (packages/core)

• RTMTWS.connectWebSocket(url, getToken?): with a token provider it sends auth on every (re)connect and reports connected (and emits open) only after on_auth; reauthenticate(token) sends a renewed token on the open connection (R6.1); user holds the authenticated user.
• getPlayerDisplayName(player, t) formats names, including guests (R5.1).
• English and Turkish strings for the account menu.

Web app (apps/frontend)

• AuthService wraps an oidc-client-ts UserManager: tokens in local storage, automaticSilentRenew with the refresh token, scope: "openid offline_access".
  • loginAsGuest(): redirect with guest=true; login(): prompt=login, so the form appears even with a guest session; signUp(): prompt=create; logout(): end-session redirect.
  • The page the user started from is passed as state and restored after the callback (/auth/callback).
• Startup (MancalaApp): finish a login redirect if this is the callback, else load the stored session (renewing an expired one), else redirect as a guest; then connect the WebSocket with getAccessToken as token provider. If the session cannot be renewed, start over as a guest (R6.2). Renewed tokens are passed to reauthenticate.
• AccountMenu on the home page: guests see Log In and Sign Up, accounts see their name and Log Out (R3, R5.2).
• KEYCLOAK_URL is a build variable (default http://localhost:8080).

Mobile app

Unchanged apart from calling connectWebSocket(url) without a token provider; it keeps the legacy userKey login.

Testing

• Extension: integration tests start Keycloak with the extension and the real realm file in a container (testcontainers-keycloak): guest login without a form and with the guest role and an offline refresh token, a new user per guest login, the login form without guest=true, and the cleanup task.
• Backend: KeycloakTokenVerifier against locally signed tokens (valid, guest, wrong key, issuer, expiry, ID and refresh tokens, other client, unsigned); WebSocket tests for the handshake, timeout, token refresh, several sockets per user, late close after reconnect, legacy on and off, and malformed messages.
• End to end in Chrome against Keycloak, the backend and the dev server: first visit as guest, two guests matched with names, reload keeping the identity, guest logging in to an account, logging out to a new guest, and token renewal over an open connection with a 75-second token lifetime.