# NeptunLdapSyncImpl ## Áttekintés A Neptun - LDAP szinkronizáció egy lehetséges implementációja az NIIF Intézet által fejlesztett PHP szkript. Ezen szkript a - lehetőségekhez képest - kellően általánosan kezeli az intézményi szinkronizációs igényeket, ezért önmagában, intézményi testreszabás nélkül, nem használható. A szkript fejlesztés alatt levő verziója elérhető a [GIT Repositoryból](https://repo.niif.hu/gitweb/gitweb.cgi?p=neptun-ldap-script.git). A forráskód tartalmazza a keretrendszert, illetve intézményi példakódokat, melyek a BME által felvetett szinkronizációs igények alapján készültek el. !!! danger "Figyelem" Ez a szkript jelenleg is fejlesztés alatt áll, a felhasználása során előkerülő hibákért, esetleges adatvesztésért az NIIF Intézet semmilyen felelősséget nem vállal. ## Követelmények A szkript futtatásának követelményei: * GNU/Linux platform (esetleg UNIX), Windows platformon a futás nem garantálható * PHP (legalább 5.2-es verzió) * a következő PHP modulok engedélyezése: LDAP, XML, CURL ## Alapvető célok A fejlesztés során elsősorban a következő kritériumokat tartottuk szem előtt: * egyszerű feladatokra egyszerű testreszabhatóság (például új LDAP attribútum felvétele) * komolyabb feladatok, workflow-k API-szintű támogatása * általános szinkronizációs keretrendszer, ami nem csak az előre megszabott Neptun interfészekkel képes együttműködni, hanem tetszőleges webszolgáltatás eredményét képes feldolgozni * intézményi testreszabás lehetősége * hatékony, memóriakorlátozott futás (a felhasznált memória mérete ne függjön a webszolgáltatás által adott rekordok számától) Nem célunk az összes intézmény összes egyedi igényét figyelembe venni, viszont ezen intézményi fejlesztéseknek helyet biztosítunk a központi forrásfában, így az intézmények egymás implementációit - szükség esetén - átvehetik. ## Részletes(ebb) leírás A szinkronizáció művelete alapvetően két különböző szintre bomlik: * az egyes webszolgáltatás-művelet paraméterezett meghívása, az eredmény rekordokra bontása (*szinkronizációs metódus*) * a webszolgáltatás eredmény rekordjait (entry) LDAP bejegyzésekkel szinkronizálni (*bejegyzés leképezése*) A keretrendszer mindkét fenti réteghez biztosít ősosztályokat, azonban az implementáció az intézményi réteghez tartozik. Általános esetben minden webszolgáltatás operációhoz külön szinkronizációs metódus tartozik, azonban az implementáció nagy része közös, ezt a keretrendszer képes elfedni (a `SyncManager` ősosztályban). ## LDAP bejegyzések leképezése A szinkronizációs keretrendszer egy LDAP bejegyzéshez egy ún. Entry objektumot rendel, melynek mezői az LDAP attribútumokkal közeli rokonságot mutatnak. Minden szinkronizációs metódus eredménye egy (vagy jópár) XML struktúra, melyek általában egy LDAP bejegyzéshez tartoznak. Például a személyes adatokat szolgáltató operáció válaszában jól elkülöníthetőek az egyes felhasználókhoz tartozó adatok. A szinkronizációt nagyban egyszerűsíti ez a feltevés, így az egyes LDAP bejegyzéseket elég ezekkel az XML struktúrákkal szinkronizálni, egy leképezést kell tehát biztosítani az LDAP attribútumok és az XML struktúra között. Tegyük fel, hogy van egy XML struktúránk, amit szeretnénk egy LDAP bejegyzésre leképezni: ```xml XYZ123 Gipsz Natália gipsz@somewhere gipsz.nati@somewhere 0000 Pest-Buda Alma tér 2 +36-1 123-1234 ``` Az ehhez tartozó LDAP bejegyzés pedig legyen a következő: dn: niifPersonOrgId=XYZ123,ou=people,o=BME,c=hu objectClass: niifPerson objectClass: person niifPersonOrgId: XYZ123 givenName: Natália givenName;en: Natalia sn: Gipsz sn;en: Gipsz cn: Gipsz Natália cn;en: Natalia Gipsz mail: gipsz@somewhere mail: gipsz.nati@somewhere postalAddress: 0000 Pest-Buda, Alma tér 2 telephoneNumber: +3611231234 Az XML->LDAP leképezésnek tehát a következőket kell megoldania: * egy létező LDAP bejegyzés megtalálása (pl Neptun-kód alapján) * LDAP attribútum feltöltése egy XML elemben tárolt értékkel * többértékűség támogatása (például több e-mail cím) * attribútum érték konverzió (telefonszám, név angol változata) * egy attribútum értékének több XML elemből történő összeállítása (lakcím, teljes név) * LDAP bejegyzés módosítása * új LDAP bejegyzés létrehozása * objectClass-ok kezelése * DN kezelése ### A leképező objektum életciklusa ![LDAP leképező objektum életciklusa](https://s3.public.doc.einfra.hu/public-doc-einfra/uploads/images/gallery/2025-08/szinkron-plain.png) LDAP-ban létező bejegyzés esetén a következőképp alakul a leképező objektum életciklusa: 1. azon mezők betöltése, melyek az LDAP bejegyzés kereséséhez szükségesek 1. LDAP keresés végrehajtása 1. LDAP-ból az attribútumok betöltése az objektum megfelelő mezőibe 1. életciklus metódus meghívása (pl. generált mezők számítása) 1. az XML-ből a mezők frissítése 1. életciklus metódus meghívása (pl. generált mezők számítása) 1. megváltozott mezők keresése 1. életciklus metódus meghívása (mentés előtti teendők végrehajtása) 1. írás az LDAP-ba ### A leképező objektum *konfigurációja* A leképező objektum mezői tehát megfeleltethetőek mind az LDAP attribútumoknak, mind az XML struktúra egyes részeinek. Ezt a két megfeleltetést a mezőknél egy dokumentációs blokkban kell megtenni: ```php class SzemelyEntry extends BaseEntry { /** * @LDAP sn * @NEPTUN Szemely/VezetekNev */ public $sn; /** * @LDAP mail * @NEPTUN Szemely/Email */ public $mail; /** * @LDAP cn * @NEPTUN Szemely */ public $cn; /* eletciklus metodusok, kotelezoen implementalando metodusok */ } ``` A fenti rövid példában a vezetéknév illetve az email cím leképzése látható. ### XML kezelés A keretrendszer egy XPath-hoz hasonlító, egyszerűsített útvonal-kifejezés kiértékelését képes elvégezni. Ebben a kifejezésben csak XML elementek szerepehetnek, `/` karakterrel elválasztva. A bejegyzéshez tartozó XML-ben előfordulhatnak olyan elemek, melyek több értéket hordoznak (a fenti példában ilyen az `Email` elem, de például lehet több lakcímből, telefonszámból, ...). Az XML feldolgozása során ezeket a mezőket transzparensen kell kezelni, tehát a feldolgozás során minden egyes csomópontnál a többszörös illeszkedés összes ágának bejárása szükséges. Ezt a rekurzív bejárást a keretrendszer biztosítja. ### Szelektív felülírás Az LDAP attribútumok közül néhány esetén felmerülhet, hogy az adott attribútum ne kerüljön felülírásra a szinkronizáció során. Erre a keretrendszer kezdetleges lehetőséget biztosít, a következő három írási szemantika definiálásával: * egy attribútum mindig felülírásra kerül (ez az alapértelmezett, `always`) * egy attribútum csak akkor kerül felülírásra, ha az LDAP-ban az attribútum még nem szerepelt (`if-empty`) * egy attribútum csak akkor kerül írásra az XML-ből, ha a teljes bejegyzés létrehozása történik (`create-only`) A felülírási szemantikát az attribútumnál a `@WRITE` direktívával lehet jelezni. ## Részletes dokumentáció A részletes API dokumentáció a projekt forrásfából a [phpDocumentor](http://phpdoc.org) eszközzel generálható a `docs/` könyvtárba: phpdoc -c phpdoc x-www-browser docs/index.html ## Futtatás, tesztelés ### Parancssoros paraméterek A szinkronizáció a `test.php` szkript meghívásával indítható. Ez a parancssoros szkript a következő paramétereket fogadja: * `--help`: súgó megjelenítése * `--teljes`: figyelmen kívül hagyja az utolsó szinkronizálás időpontját * `--neptunlist`: soronként egy neptun kódot tartalmazó fájl * `--szinkron`: vesszővel (nem szóközzel) elválasztott lista a szinkronizálandó típusokról ### Inkrementális szinkronizáció A példaimplementáció alapértelmezetten (a `--teljes` kapcsoló hiánya esetén) az utolsó futtatás óta módosult rekordokat kérdezi le a Neptun webszolgáltatástól. Az egyes szinkronizációs modulok külön futtatásával elérhető, hogy bizonyos adatok (például a státuszok) gyakrabban frissüljenek, más adatok (például a hallgatott tárgyak) ritkábban. Az utolsó futtatás időpontja tehát szinkronizációs metódusonként kerül tárolásra. ### Szelektív feltöltés A `--neptulist` paraméter használatával a szinkronizáció korlátozható bizonyos neptun kódokra. Ez a futtatási mód akkor lehet előnyös, ha például egy (néhány) felhasználó adatait kell csak szinkronizálni. Például elképzelhető egy olyan webes felület, ahol a felhasználók ellenőrizhetik a címtárban tárolt adataikat, illetve bizonyos esetekben kérhetik adataik frissítését. Ez a megoldás nagyban csökkentheti az adminisztrációs költségeket, hiszen a Neptunban elvégzett módosítások áttöltését maga a felhasználó kérheti. ## Konfiguráció A szinkronizáció konfigurációt a `config.php` -ben lehet módosítani. Ebben a fájlban kell beállítani az LDAP szerver elérhetőségét és a jelszavakat, a logolás szintjét, a szinkronizációs metódusok nevét, illetve az ideiglenes fájlokat tároló könyvtárat.