mancala/apps/keycloak/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.

Guest login

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.

Login theme

themes/mancala/login gives the login, registration and password reset pages the game's look: its app bar and logo, the board's colors and a board with stones on top of the card. It extends Keycloak's keycloak.v2 theme and only adds resources/css/mancala.css, so its templates and behaviour stay Keycloak's own and upgrades need no template changes. The colors come from LightTheme and DarkTheme in packages/core/src/theme; the dark ones are used when the system prefers a dark color scheme. The realm turns the theme on (loginTheme) and offers English and Turkish; the web app passes its language as ui_locales.

To try a change without rebuilding the image, copy the theme into the running container, clear Keycloak's gzip cache (it survives restarts) and restart:

docker cp apps/keycloak/themes/mancala apps-keycloak-1:/opt/keycloak/themes/
docker exec apps-keycloak-1 rm -rf /opt/keycloak/data/tmp/kc-gzip-cache
docker restart apps-keycloak-1

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, the real realm file and the login theme 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.