linuxmuster-koha

Schüler und Lehrkräfte aus einer edulution-Instanz (linuxmuster.net) automatisch als Leser in Koha anlegen und aktuell halten.

Das Skript koha-edulution-sync.py liest die Benutzer aus dem Keycloak von edulution, das seine Benutzer per LDAP aus dem linuxmuster-AD bekommt, und schreibt sie über die Koha-REST-API. Es braucht nur Python 3.9 oder neuer mit der Standardbibliothek, keine Zusatzpakete. Es läuft auf jedem Linux-Rechner, der Keycloak und Koha per HTTPS erreicht, zum Beispiel auf dem Koha-Server.

Was das Skript tut

Quelle in edulution/Keycloak	Ergebnis in Koha
Mitglied der Gruppe <klasse>-students, z. B. 05a-students	Leser der Kategorie STUDENT_CATEGORY, Klasse in „Statistik 1“ (sort1)
Mitglied der Gruppe role-teacher	Leser der Kategorie TEACHER_CATEGORY, „Statistik 1“ = Kollegium
Benutzername (Schul-Login)	Koha-Benutzername (userid), daran wird abgeglichen
Vorname, Nachname, E-Mail	werden übernommen und bei Änderungen nachgezogen

• Neu in edulution: Der Leser wird in Koha angelegt.
• Geändert (Name, E-Mail, Klassenwechsel): Der Leser wird aktualisiert.
• Verschwunden (Schulabgang): Der Leser wird nicht gelöscht, weil er noch Medien ausgeliehen haben kann. Er bekommt das Ablaufdatum „gestern“. Ausleihen und Rückgaben bleiben in Koha sichtbar, neue Ausleihen sperrt Koha. Kommt er zurück, wird das Konto wieder verlängert.
• Lehrkräfte, die zugleich in einer Schülergruppe stehen, zählen als Lehrkräfte.
• In Keycloak deaktivierte Konten werden nicht übernommen.

Was das Skript nicht anfasst:

• Leser in anderen Kategorien. Bibliotheksmitarbeiter mit Kategorie „Personal“ bleiben unberührt, auch wenn ihr Benutzername gleich ist.
• Von Hand angelegte Leser ohne die Kennzeichnung edulution-sync in „Statistik 2“ (sort2). Sie werden nie automatisch auf abgelaufen gesetzt.

Sicherheitsbremse: Würden mehr als MAX_EXPIRE Leser (Standard 50) auf abgelaufen gesetzt, bricht das Skript vor jeder Änderung ab. Das schützt, falls Keycloak einmal leere Gruppen liefert. Nach dem Schuljahreswechsel den Wert für einen Lauf erhöhen.

Einrichtung

1. edulution: Keycloak-Client für den Lesezugriff anlegen

Das Skript meldet sich mit einem eigenen Dienstkonto an, nicht mit dem Keycloak-Admin.

1. Keycloak-Adminkonsole öffnen: https://<edulution-server>/auth/admin/, als Keycloak-Admin anmelden.

2. Oben links den Realm edulution wählen, nicht master.

3. Clients → Create client

   • Client type: OpenID Connect, Client ID: koha-sync → Next
   • Client authentication: On
   • Authentication flow: nur Service accounts roles anhaken, Standard flow und Direct access grants abwählen → Next → Save

4. Im Client koha-sync den Reiter Service accounts roles öffnen → Assign role → Filter Filter by clients → aus realm-management diese beiden Rollen zuweisen:

   • view-users
   • query-groups

   Mehr ist nicht nötig. Der Client kann damit nur lesen.

5. Reiter Credentials → Client secret kopieren. Es kommt in die Konfiguration als KEYCLOAK_CLIENT_SECRET.

Prüfen, ob die Klassengruppen ankommen: In Keycloak unter Groups sollten Gruppen wie 05a-students und role-teacher zu sehen sein. linuxmuster legt sie an, edulution synchronisiert sie über die LDAP-Anbindung.

2. Koha: API-Zugang einrichten

Alle Schritte in der Koha-Mitarbeiteroberfläche als Superbibliothekar.

1. Systemeinstellung (Administration → Globale Systemeinstellungen, Suche nach RESTOAuth2ClientCredentials): auf Aktivieren stellen.

2. Leserkategorien (Administration → Leserkategorien): Kategorien für Schüler und Lehrkräfte anlegen, z. B. ST „Schüler“ und T „Lehrkräfte“. Man kann auch vorhandene Kategorien verwenden und deren Codes in die Konfiguration eintragen. Nicht die Personal-Kategorie nehmen.

3. API-Benutzer anlegen: einen eigenen Leser, z. B. api-edulution-sync, in der Kategorie Personal (Staff).

4. Berechtigungen dieses Lesers (Mehr → Berechtigungen festlegen):

   • catalogue (Zugang zur Mitarbeiteroberfläche)
   • unter borrowers: edit_borrowers, list_borrowers und view_borrower_infos_from_any_libraries

   Kein Superbibliothekar nötig.

5. API-Schlüssel erzeugen: beim API-Benutzer Mehr → API-Schlüssel verwalten → Generate a new client id/secret pair. Client-ID und Secret kommen in die Konfiguration (KOHA_CLIENT_ID, KOHA_CLIENT_SECRET). Der Menüpunkt erscheint erst, wenn Schritt 1 erledigt ist.

6. Den Bibliothekscode notieren (Administration → Bibliotheken, z. B. CPL). Neue Leser kommen in diese Bibliothek.

3. Skript installieren

Auf dem Rechner, auf dem der Sync laufen soll, als root:

git clone https://git.az-it.net/az/linuxmuster-koha.git /opt/linuxmuster-koha
install -d -m 700 /etc/linuxmuster-koha
install -m 600 /opt/linuxmuster-koha/sync.conf.example /etc/linuxmuster-koha/sync.conf
vim /etc/linuxmuster-koha/sync.conf      # URLs, Secrets, Kategorien eintragen

4. Trockenlauf

python3 /opt/linuxmuster-koha/koha-edulution-sync.py --dry-run

Der Trockenlauf schreibt nichts. Er zeigt jeden geplanten Schritt (NEU, UPDATE, SKIP, ABLAUF), die Klassenliste und eine Zusammenfassung. Darauf achten:

• Klassenliste: Stehen dort Test- oder Pseudoklassen (testklasse, extern, none, …)? Dann CLASS_PATTERN setzen, z. B. \d{1,2}[a-z]?|vkl, und erneut prüfen.
• SKIP-Zeilen: Diese Benutzer gibt es in Koha schon in einer anderen Kategorie, meist als Personal. Das ist so gewollt.
• Bereits vorhandene Leser: Wer schon in einer der beiden Kategorien steht und denselben Benutzernamen hat, wird übernommen und ab dann vom Sync gepflegt. Name, E-Mail, Klasse und Kategorie überschreibt der Sync dann.

5. Echter Lauf und täglicher Timer

Vor dem ersten echten Lauf eine Datensicherung der Koha-Datenbank ziehen, zum Beispiel koha-dump <instanz> bei der Paketinstallation.

python3 /opt/linuxmuster-koha/koha-edulution-sync.py

cp /opt/linuxmuster-koha/systemd/koha-edulution-sync.{service,timer} /etc/systemd/system/
systemctl daemon-reload
systemctl enable --now koha-edulution-sync.timer
systemctl list-timers koha-edulution-sync.timer    # nächster Lauf
journalctl -u koha-edulution-sync.service          # Ausgabe der Läufe

Der Timer läuft täglich um 06:45 Uhr. Nach Änderungen in der Schulkonsole greift der Sync also am nächsten Morgen, bei Bedarf sofort per systemctl start koha-edulution-sync.service.

Optional: Anmeldung am OPAC mit dem Schul-Login

Weil der Koha-Benutzername gleich dem Schul-Login ist, können sich Schüler und Lehrkräfte im OPAC über edulution anmelden. Dafür in Keycloak einen zweiten Client koha anlegen, diesmal mit Standard flow und den Redirect-URIs https://<opac>/* und https://<staff>/*. In Koha unter Administration → Identitätsanbieter einen OIDC-Anbieter mit der Discovery-URL https://<edulution-server>/auth/realms/edulution/.well-known/openid-configuration anlegen. Mapping: userid → preferred_username, email → email, firstname → given_name, surname → family_name. Automatische Registrierung abschalten, weil der Sync die Konten anlegt. Außerdem in den Systemeinstellungen OPACBaseURL und staffClientBaseURL setzen, sonst schickt Koha falsche Redirect-URIs.

Stand und Grenzen

• Entwickelt für Koha 26.05, Felder gegen dessen API-Spezifikation geprüft. Ältere Versionen ab etwa 23.11 sollten gehen, sind aber nicht getestet.
• Der Keycloak-Teil wurde lesend gegen eine echte edulution-Instanz getestet. Der Koha-Schreibteil wurde gegen einen nachgebauten API-Server getestet. Den ersten echten Lauf deshalb immer mit --dry-run beginnen.
• Ausweisnummern (cardnumber) setzt das Skript nicht. Je nach Koha- Einstellung autoMemberNum vergibt Koha sie selbst, oder man trägt sie nach. An der Theke findet man Leser auch über den Namen.
• Eltern (role-parent) werden nicht übernommen. Verwaltungspersonal ohne Lehrerrolle nur dann, wenn linuxmuster es in einer …-students-Gruppe führt; mit CLASS_PATTERN steuerbar.