# 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.

## Running

```sh
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

```sh
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.