NeptunLdapSyncImpl

Innen: KIFÜ Wiki
A lap korábbi változatát látod, amilyen Hege(AT)niif.hu (vitalap | szerkesztései) 2010. február 25., 15:55-kor történt szerkesztése után volt. (Áttekintés)

Á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. 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.


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:

 <Szemely>
  <Kod>XYZ123</Kod> <!-- pl. NEPTUN-kód -->
  <Vezeteknev>Gipsz</Vezeteknev>
  <Keresztnev>Natália</Keresztnev>
  <Email>gipsz@somewhere</Email>
  <Email>gipsz.nati@somewhere</Email>
  <Lakcim>
   <Irsz>0000</Irsz>
   <Varos>Pest-Buda</Varos>
   <Cim>Alma tér 2</Cim>
  </Lakcim>
  <Telefon>+36-1 123-1234</Telefon>
  <!-- tovabbi elemek -->
 </Szemely>

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-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
  2. LDAP keresés végrehajtása
  3. LDAP-ból az attribútumok betöltése az objektum megfelelő mezőibe
  4. betöltés vége, életciklus metódus meghívása
  5. az XML-ből a mezők frissítése
  6. életciklus metódus meghívása (generált mezők számítása)
  7. megváltozott mezők keresése
  8. í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:

class SzemelyEntry extends BaseEntry {
 /**
  * @LDAP sn
  * @NEPTUN Szemely/VezetekNev
  */
 public $sn;
 /**
  * @LDAP mail
  * @NEPTUN Szemely/Email
  */
 public $mail;
 /**
  * @LDAP c
  * @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 eszközzel generálható a docs/ könyvtárba:

phpdoc -c phpdoc
x-www-browser docs/index.html