History

Halit Aksoy 29fa443b93 build: add shared Postgres and Valkey to compose - postgres replaces keycloak-db and holds a keycloak and a mancala database, each with its own user, created by apps/postgres/init - valkey with an append-only file for live game state and caches - backend gets DATABASE_URL and VALKEY_URL		2026-10-16 00:05:21 +03:00
..
extension	feat(keycloak): add Keycloak with guest login extension	2026-10-14 01:46:48 +03:00
realm	feat(keycloak): add Keycloak with guest login extension	2026-10-14 01:46:48 +03:00
.dockerignore	feat(keycloak): add Keycloak with guest login extension	2026-10-14 01:46:48 +03:00
.gitignore	feat(keycloak): add Keycloak with guest login extension	2026-10-14 01:46:48 +03:00
Dockerfile	feat(keycloak): add Keycloak with guest login extension	2026-10-14 01:46:48 +03:00
README.md	build: add shared Postgres and Valkey to compose	2026-10-16 00:05:21 +03:00

README.md

Mancala Keycloak

Keycloak is the only auth system for Mancala. Players can either log in with an account or play as a guest, and both come back as normal Keycloak tokens from the mancala realm.

extension/ adds a mancala-guest-authenticator to Keycloak. When an authorization request has guest=true, it creates a new user named guest-xxxxxxxx, gives it the guest realm role and logs it in without showing a form. Requests without the parameter fall through to the normal login form.

/realms/mancala/protocol/openid-connect/auth?client_id=mancala-web&response_type=code
    &scope=openid%20offline_access&redirect_uri=...&code_challenge=...&code_challenge_method=S256
    &guest=true

Clients can tell guests apart by "guest" in the access token's realm_access.roles.
Guests should request offline_access so they keep their identity after the SSO session ends (offline sessions expire after 30 days without use).
A scheduled task deletes guests that are older than a day and have no session or offline session left. Its timing can be changed with server options such as KC_SPI_AUTHENTICATOR__MANCALA_GUEST_AUTHENTICATOR__CLEANUP_INTERVAL_SECONDS (default 3600), ..._CLEANUP_MIN_AGE_SECONDS (default 86400) and ..._CLEANUP_MAX_DELETES_PER_RUN (default 1000).
Each guest login creates a user, so the auth endpoint is rate limited per IP in config/nginx.conf.

Realm

realm/mancala-realm.json holds the realm: the mancala-web public client (PKCE S256), the browser with guest flow, the guest role, and the required actions with "Verify Profile" turned off so guests are not asked for an email or a name.

Keycloak imports the file only if the realm does not exist yet. After changing it, apply the change in the admin console too, or delete the realm and restart Keycloak.

Running

cd apps
cat > .env <<EOF
POSTGRES_PASSWORD=change-me
KEYCLOAK_DB_PASSWORD=change-me
KEYCLOAK_ADMIN_PASSWORD=change-me
MANCALA_DB_PASSWORD=change-me
EOF
docker compose up -d --build keycloak

Keycloak uses the keycloak database of the shared postgres service; apps/postgres/init creates it the first time the Postgres volume is initialised.

Keycloak is then at http://localhost:8080 and the admin console at http://localhost:8080/admin. In production set KEYCLOAK_HOSTNAME=https://auth.playmancala.app; nginx proxies that host to port 8080.

Tests

cd apps/keycloak/extension
mvn test

The tests start Keycloak with the extension and the real realm file in a container, so they need Docker.

Upgrading Keycloak

The extension uses Keycloak's authenticator SPI, which Keycloak marks as internal. When upgrading, change the version in extension/pom.xml and in Dockerfile together and run the tests.