Skip to content

[#1] Keycloak login and access for Platform, CKAN and GeoServer - #2

Merged
dedenbangkit merged 15 commits into
mainfrom
feature/1-keycloak-configuration
Nov 15, 2026
Merged

dedenbangkit merged 15 commits into
mainfrom
feature/1-keycloak-configuration

Conversation

@zuhdil

@zuhdil zuhdil commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Closes #1.

Summary

Keycloak is the one identity source. Users never see a Keycloak page: password login goes through the password grant, and Google login redirects straight to Google (kc_idp_hint).

sequenceDiagram
    participant Admin as User manager
    participant P as Platform (Next.js + FastAPI)
    participant KC as Keycloak
    participant M as Mailpit
    participant U as Invited user
    Admin->>P: invite email + roles
    P->>KC: create user, map realm roles
    P->>M: invite link (7 days, single use)
    U->>P: open link, set name + password (or Google)
    P->>KC: complete account
    U->>P: log in: CKAN, GeoServer layers follow the roles
Loading
Realm role Grants
super-admin everything, and the only one who can grant user-manager
user-manager invite users with roles the inviter holds
ckan-access log in to CKAN (its own login form, or Google)
geoserver-access read the restricted amconnect GeoServer layers
 keycloak/realm-amconnect.json   # realm, roles, clients, Google, invite-only first login
+keycloak-config (compose)       # keycloak-config-cli applies the realm file on every `up`, keeps users
 backend/                        # /auth/*, /me, /invitations (+ table, migration)
 frontend/                       # /login, /, /invite, /invite/[token] (Auth.js)
 ckan/ckanext-amconnect/         # amconnect_keycloak plugin
 geoserver/entrypoint.sh         # sec-oidc bearer-token filter, layer ACL
+Makefile, .github/workflows/    # make check / make test, same in CI
+CLAUDE.md (AGENTS.md)           # limits and conventions

Code checks follow the Akvo code-quality plan, repo-local for now: ruff, Pyrefly, ESLint with size and complexity limits, Prettier, tsc, Vale (report only), and 80% coverage of changed backend lines. c75935a is formatting only and is listed in .git-blame-ignore-revs.

Evidence

  • Before: no login, no access control on CKAN or GeoServer, no checks.
    After:
    • ./scripts/e2e-issue-1.sh against the demo stack: 22/22 pass (super admin invites A; A invites B with CKAN and C without; B logs in to CKAN, C is refused; only A reads GeoServer layers; re-inviting a signed-in user is refused, an unaccepted invite can be sent again; short passwords are refused; A stays logged in after access and refresh tokens expire, checked with 10s/20s tokens).
    • Google login through an invite, by hand: works, no name prompt.
    • make check and make test: pass, 38 backend tests, 98% coverage.
    • Realm changes applied to a running Keycloak with users kept: role added and removed, super admin password kept.

Not checked: token expiry against GeoServer.

Manual testing

Setup: put COMPOSE_PROFILES=demo, AMCONNECT_SEED=true and AMCONNECT_HARVEST=true in .env (README "Demo data"), then docker compose up -d --build and wait until docker compose ps shows CKAN and GeoServer healthy. For a fresh start, run docker compose down -v first.

  1. Login: open http://localhost:3000, log in as admin@example.org / admin12345. Home shows the roles and the GeoServer layers you can see.
  2. Invite: "Invite a user", email a@example.org, tick user-manager and ckan-access. Open the email in Mailpit (http://localhost:8025), follow the link, set a name and password. A password under 8 characters is refused.
  3. Grant limits: log in as a@example.org. On /invite, only the roles A holds are offered (no geoserver-access, no user-manager). Invite b@example.org with ckan-access and c@example.org with none; accept both from Mailpit.
  4. Re-invite: inviting a@example.org again is refused; inviting an address whose email was never accepted works and only the newest link opens.
  5. CKAN: at http://localhost:5000/user/login, B logs in; C is refused and no CKAN account is created.
  6. GeoServer: with a token from curl -s localhost:8000/auth/login -H 'content-type: application/json' -d '{"email":"admin@example.org","password":"admin12345"}', request
    http://localhost:8080/geoserver/amconnect/wms?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&LAYERS=amconnect:thailand_geology&STYLES=&SRS=EPSG:4326&BBOX=97,5,106,21&WIDTH=64&HEIGHT=64&FORMAT=image/png
    with -H "authorization: Bearer <access_token>": an image. Without the header, or with B's token: 404.
  7. Session: stay logged in on the platform for over 30 minutes, clicking around now and then: still logged in. "Log out" returns to the login page.
  8. Google (optional): set GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET in .env (README "Google login"), docker compose up -d. Invite your Google address, choose "Continue with Google" on the invite page: logged in, no name prompt. A Google account that was not invited sees the "ask for an invitation" page.
  9. Realm changes: add a role to keycloak/realm-amconnect.json, docker compose up -d: the role appears in the Keycloak admin console (http://localhost:8180/admin, admin / admin) and existing users and passwords are kept.

Automated version of 1–7: ./scripts/e2e-issue-1.sh.

Merge Danger

Door: two-way

Nothing is deployed yet. Dev stacks need docker compose up -d --build; a Keycloak database from before keycloak-config-cli is updated in place.

Blast Radius: dev-stack

  • CKAN users are now named by Keycloak user id; the local sysadmin moved to ckan-admin@example.org (CKAN emails must be unique).
  • All amconnect GeoServer layers need geoserver-access, so CKAN's map preview is empty for them.
  • Passwords need 8 characters and must not be the email; failed logins lock the account (Keycloak default, 30 tries). A SUPERADMIN_PASSWORD under 8 characters may be refused on a fresh realm.
  • Known limits: Google login still works after an invite expires; a Google acceptance marks the invitation accepted only when its link is next opened; the access token is readable in the Auth.js session.

zuhdil added 15 commits November 9, 2026 10:47
Users never see a Keycloak page, so the backend does password login
with the password grant and invites through the admin API using the
`platform-admin` service account. Invitees are created in Keycloak at
invite time with a verified email and no password, so Google login can
link to them at once; the emailed Platform link sets name and password.
An inviter grants only roles they hold, and only a super admin creates
user managers. Keycloak always issues tokens for localhost:8180 while
containers reach it at keycloak:8080.
Auth.js holds the session. Password login goes through the backend;
Google goes through Keycloak with `kc_idp_hint=google`, so Keycloak
only redirects. Its authorize URL is the browser address while token
and userinfo calls use the container address, which also skips
discovery. Tokens refresh through the backend, and logout ends the
Keycloak session. The access token is in the Auth.js session, so
browser JavaScript can read it; acceptable since it is the user's own.
A new `amconnect_keycloak` plugin checks CKAN's own login form against
Keycloak with the password grant, and adds a Google route that only
redirects through Keycloak. Users without `ckan-access` are refused
before a CKAN account exists. Logins Keycloak does not know fall
through to CKAN's own users, which keeps the local sysadmin working;
its default email moves to ckan-admin@example.org because CKAN emails
must be unique and the Keycloak super admin uses admin@example.org.
GeoServer moves to 3.0.1 for the sec-oidc extension, whose login filter
in resource-server mode checks Bearer tokens against Keycloak and maps
realm roles. GeoServer reads filter and chain config only at startup
and has no REST API for it, so an entrypoint writes the XML before
Tomcat starts, booting once on a fresh volume to let GeoServer create
its defaults. Both seeds read restricted layers as GeoServer admin; in
CKAN only the `seed` command gets those credentials, so its public API
never probes restricted layers.
On a fresh volume the entrypoint boots GeoServer once to let it create
its defaults, and that temporary instance already passed the
healthcheck, so the demo seed could start just before the restart. The
entrypoint now writes a ready marker right before the real start and
the healthcheck requires it.
`scripts/e2e-issue-1.sh` runs the issue's acceptance flow against the
running stack: invites, accepting through the mailed link, CKAN login
and refusal, and GeoServer access per role. Google login needs a real
account, so the README covers its setup for checking by hand. The
Keycloak theme rewords the one page a user can meet there: Google login
without an invitation.
Keycloak's own import only fills an empty database, so realm changes needed
a reset that deleted users. keycloak-config-cli applies the realm file to the
running Keycloak instead and keeps users. It deletes only what it created
itself, and sets the super admin password only on creation.

The default role is now declared as a role with an explicit empty `account`
list; without it the account-console roles stay.
Formatting and import order only, no behavior change. The CKAN extension
moves from black and isort to ruff with the same settings (79 columns,
quotes kept), so its diff stays small. Prettier uses a 100-column width.
`make check` runs ruff, Pyrefly, ESLint, Prettier, tsc and Vale; locally in
the compose containers, in CI on the runner through the same targets.
Backend and frontend get the Akvo limits (complexity 10, nesting 3, 50-line
functions, 5 parameters) and typed public functions. The CKAN extension,
GeoServer seed and demo get format and basic lint only.

Pages over 50 lines were shortened by hoisting server actions and sharing
an `Input` component. Swallowed exceptions now log at debug level instead
of `noqa`. Vale only reports.
The 80% changed-line coverage gate needs them. Only the boundaries are
faked: Keycloak's HTTP API through `httpx2.MockTransport`, its signing key
with a generated RSA key, and SMTP.
Python and frontend jobs call the `make` targets; a PR also needs 80% of
its changed backend lines covered (`diff-cover`). Vale on docs and the PR
description only reports.
AGENTS.md links to it for other agents.
setup-uv publishes only exact tags, so it is pinned to v10.3.3. tsc needs
Next's generated route types (`LayoutProps`), which only `next dev` wrote
until now; `next typegen` makes them on a clean checkout.
…ites

`auth()` in server components cannot set cookies, so refreshed tokens were
dropped and users were logged out when the first refresh token expired.
`proxy.ts` runs it where cookies can be written.

Passwords need 8 characters (the seeded super admin's is 10) and failed
logins lock the account.

Inviting an email again replaces the user when they never signed in (no
password, no Google link), so an expired or failed invite no longer blocks
the address. The e2e script checks all three.
An invitee who joins with Google never marks the invitation accepted, so
the link could still set a password on the live account. Opening a link
now checks with Keycloak whether the user can already sign in, and if so
marks it accepted and refuses it. Costs one Keycloak call per open.

`verify()` requires `typ == "Bearer"`: ID tokens share issuer and `azp`.

SMTP gets a 10s timeout so a stalled mail server cannot hold a request.
@zuhdil
zuhdil requested a review from dedenbangkit November 9, 2026 07:41
@dedenbangkit
dedenbangkit merged commit 57fe805 into main Nov 15, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

POC Keycloak configuration

2 participants