From dcb325b111e417d81535d5168cabd09ac5faf625 Mon Sep 17 00:00:00 2001
From: Jonas Braathen <jonas@ponas.no>
Date: Fri, 9 Oct 2026 16:15:31 +0200
Subject: [PATCH] dnscms: document Galtinn login and user linking

---
 README.md | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/README.md b/README.md
index 07976b5..294c6f7 100644
--- a/README.md
+++ b/README.md
@@ -50,3 +50,31 @@ curl -X POST -H "X-Revalidate-Secret: $SECRET" https://<frontend>/api/revalidate
 ```
 
 Note: ISR is off under `npm run dev`; use `npm run build && npm run start` to test caching.
+
+## CMS login via Galtinn
+
+Editors log in to the CMS with their Galtinn account over OIDC (see `dnscms/dnscms/oidc.py`).
+Access follows membership of one Galtinn group, which is checked at every login:
+members become Wagtail editors, and a linked user who has left the group is deactivated.
+Users are identified only by their stored Galtinn ID, never by username or email,
+so an existing local user must be linked by hand under `/django-admin/` before they can use it.
+Linked users have no local password; unlinked local users still log in with theirs.
+
+Set these in `dnscms/dnscms/settings/local.py` or env. The Galtinn button only shows when the group and client ID are set.
+
+| Setting | Value |
+|---|---|
+| `GALTINN_BASE_URL` | Galtinn's public URL, defaults to `https://galtinn.neuf.no` |
+| `GALTINN_EDITOR_GROUP` | name of the Galtinn group that grants editor access |
+| `OIDC_RP_CLIENT_ID`, `OIDC_RP_CLIENT_SECRET` | the OAuth application registered in Galtinn's admin |
+| `WAGTAIL_BASE_URL` | must be the CMS's public URL; the callback is `<WAGTAIL_BASE_URL>/oidc/callback/` |
+
+To link existing local users in bulk, match them against Galtinn and review the result by hand:
+
+```bash
+uv run manage.py galtinn_users export > cms-users.csv                 # in dnscms
+uv run manage.py match_cms_users cms-users.csv > matched.csv          # in galtinn, suggests a galtinn_id per row
+uv run manage.py galtinn_users link matched.csv                       # in dnscms, dry run; add --apply to save
+```
+
+Rows with an empty `galtinn_id` stay local users. A linked user keeps their password until their first Galtinn login.