Keycloak erlaubt es externe Datenquellen anzubinden, in der die Benutzerdaten wie Benutzername und Passwort stehen. ChurchTools bietet eine REST API, um Daten auszulesen und sich einzuloggen.
Dieses kleine Projekt verbindet diese beide Funktionen, sodass man sich per OpenID Connect mit dem ChurchTools Account in allen Systemen einloggen kann, die OpenID Connect unterstützen. Darunter zählen Systeme wie WordPress, Synology oder Nextcloud.
Getestet mit Keycloak 24.0.4.
Zunächst muss ein ChurchTools Konto für diesen Storage Provider erstellt werden:
- Eine Person mit E-Mail-Adresse in ChurchTools hinzufügen.
Für solche API Benutzer bietet sich außerdem ein eigener Status (Mitglied, Freund, API-Nutzer) an - Die neu erstellte Person zu ChurchTools einladen.
- Auf den Einladungslink klicken und ein Passwort festlegen.
- Im Browser https://example.church.tools/api/whoami öffnen, um die ID der neuen Person nachzuschlagen.
- Im Browser https://example.church.tools/api/person/${ID}/logintoken öffnen, um das zeitlich unbegrenzt gültige Login Token nachzuschlagen.
Schritt 4. und 5. können auch über die Weboberfläche ausgeführt werden: Official Documentation
⚠️ Aus Sicherheitsgründen sollte dieser Storage Provider nicht mit einem ChurchTools Administrator Konto betrieben werden.
Folgende Berechtigungen für das neu erstellte Konto gewähren:
- Personen & Gruppen > "Personen & Gruppen" sehen
churchdb:view - Personen & Gruppen > Sicherheitslevel Personendaten (Stufe 1-3)
churchdb:security level person(1,2,3) - Personen & Gruppen > Alle Personen des jeweiligen Bereiches sichtbar machen (Alle)
churchdb:view alldata(-1)
Da es Zeit erfordert, sich in eine sichere Einrichtung von Keycloak mit Docker einzuarbeiten,
bieten wir ein Compose File als Orientierung an.
In einer Umgebung mit NGINX Reverse Proxy ist es ausreichend, user-storage-churchtools.jar aus den
Releases herunterzuladen,
die Passwörter und ChurchTools Zugangsdaten im Compose File anzupassen und es ansonsten unverändert zu übernehmen.
Anschließend muss die user-storage-churchtools.jar aus den
Releases
heruntergeladen und in keycloak/providers gespeichert werden.
Die ChurchTools Zugangsdaten aus dem ersten Schritt müssen anschließend z.B. in keycloak/conf/keycloak.conf
konfiguriert werden.
spi-storage-churchtools-user-storage-host=demo.church.tools
spi-storage-churchtools-user-storage-login-token=DuIojxSyqCIM...rfH1foJvwaxNach dem ersten Start von Keycloak empfiehlt es sich, einen eigenen Realm für ChurchTools zu erstellen
und anschließend unter User Federation den Provider Churchtools-user-storage hinzufügen.
Anschließend kann man testweise unter Users nach * suchen. Dann sieht man alle Personen,
die sich künftig über Keycloak bei Drittanwendungen anmelden können.
Solche Drittanwendungen wie Nextcloud, WordPress, usw. kann man unter Clients hinzufügen.
Dieser Storage Provider ignoriert Zwei-Faktor-Authentifizierung von ChurchTools. Benutzername und Passwort sind zum Anmelden in Keycloak ausreichend. Falls 2FA zum Einsatz kommen soll, muss außerdem keycloak-churchtools-totp-provider eingerichtet werden.
Die Benutzer ID (sub claim) von Keycloak entspricht dem Format f:<keycloak uuid>:<churchtools id>.
Bei manchen Anwendungen sorgen die Doppelpunkte allerdings für Probleme:
Das Projekt kann mit Java 17 und Maven gebaut werden.
mvn clean installAnschließend findet man die JAR-Datei unter target/user-storage-churchtools.jar.