Kako pisati module za AOSI?

AOSI je akronim za Aplikaciju za Održavanje Sadržaja Imenika i jedna je od osnovnih komponenti sustava AAI@EduHr. AOSI je web servis koji dohvaća, ažurira, dodaje i briše podatke u LDAP imeniku matične ustanove.

Od verzije 2.0 AOSI donosi niz poboljšanja i novih mogućnosti - jedna od najvažnijih je i sustav modula, odnosno plugin-ova. Sustav je zamišljen na način da prije i poslije svake akcije kojom se mijenja stanje podataka u imeniku dozvoli pokretanje i izvršavanje još neke dodatne akcije i na taj način omogući lakšu integraciju s drugim aplikacijama korištenim za pohranu i manipulaciju podataka o korisnicima na matičnoj ustanovi. Sustav omogućuje okidanje 6 akcija:

• beforeAddUser - izvršava se prije pokušaja dodavanja elektroničkog identiteta u LDAP imenik;
   
• afterAddUser - izvršava se nakon pokušaja dodavanja elektroničkog identiteta u LDAP imenik;
   
• beforeDeleteUser - izvršava se prije pokušaja brisanja elektroničkog identiteta iz LDAP imenika;
   
• afterDeleteUser - izvršava se nakon pokušaja brisanja elektroničkog identiteta iz LDAP imenika;
   
• beforeChangeAttribute - izvršava se prije pokušaja promjene atributa određenog elektroničkog identiteta u LDAP imeniku;
   
• afterChangeAttribute - izvršava se nakon pokušaja promjene atributa određenog elektroničkog identiteta u LDAP imeniku;
   

Primjer za funkciju ldapAddUser bi se mogao ovako prikazati:

Funkcije before* bi trebale provjeriti smije li se upisati elektronički identitet u LDAP imenik, odnosno provjeriti postoji li već u drugim repozitorijima zapis koji bi se trebao upisati (npr. postoji li već takav account u Microsoft Active Directory bazi) te spriječiti upisivanje.

Funkcije after* bi trebale obaviti rukovanje podacima o elektroničkom identitetu, odnosno upisati/obrisati/osvježiti podatke u drugim repozitorijima (npr. dodati korisnika u Microsoft Active Directory).

Sustav modula se sastoji od:

• /usr/lib/aosi/Plugins.pm - datoteka koja sadrži logiku;
   
• /usr/lib/aosi/Plugins - direktorij koji sadrži same module;
   
• /usr/lib/aosi/Plugins/plugins.conf - datoteka koja sadrži popis aktivnih modula;

Da bi AOSI prepoznao dodatni modul potrebno je:

1. Napraviti Perl paket (npr. MojModul.pm) i smjestiti ga u direktorij Plugins;
    
2. Minimalni sadržaj takve datoteke (za MojModul.pm) bi trebao biti:
   

   package MojModul;
   	
   1;
   
   

3. Potrebno je "registrirati" modul u datoteci plugins.conf, odnosno potrebno je dopisati samo naziv modula (npr. MojModul);

Nakon restarta AOSI servisa (/etc/init.d/aosi restart), modul će se učitati. Gore opisani modul ne radi ništa, jer još nisu definirane funkcije za neku od 6 akcija. Nije potrebno definirati svih 6 funkcija, npr. mogu se definirati samo dvije: afterAddUser i afterDeleteUser.

before*  funkcije:

Funkcije beforeAddUser i beforeDeleteUser imaju oblik:

sub before*User{
my($status_hash, $ldap, $base_dn, $entry_in, $user, $pwd) = @_;

    # obrada

    return $code, $msg, $out_panic;
}	

gdje je:

$status_hash - hash u kojemu su popisani rezultati svih prethodno izvršenih modula. Hash je oblika:

$status_hash->{*NAZIV_MODULA*}->{*VRSTA_AKCIJE*}->{*VARIJABLA*} = *VRIJEDNOST*;		

gdje je:

• *NAZIV_MODULA* - naziv modula kako je registriran u plugins.conf datoteci (npr. MojModul);
   
• *VRSTA_AKCIJE* - Jedan od ova dva stringa: before ili after;
   
• *VARIJABLA* - Postavljaju se tri varijable: code, msg te panic pri čemu je:
  
  • code - brojčana oznaka uspješnosti operacije, ako je 0 (nula) operacija je uspjela;
     
  • msg - tekstualna poruka o uspješnosti operacije;
     
  • panic - brojčana vrijednost, ako nije 0 (nula) označava da modul traži prekid i sve daljnje operacije se trebaju zaustaviti!

$ldap - referenca na Net::LDAP objekt za povezivanje s LDAP imenikom.

$base_dn - base DN zapis u LDAP imeniku;

$entry_in - XML kojim se traži određena akcija. XML je oblika:

<entry dn="uid=user,dc=domena,dc=hr">
    <attribute ldapname="sn">
        <value>User</value>
        <value>User2</value>
    </attribute>
    <attribute ldapname="mail">
        <value>user@domain.hr</value>
        <value>user2@domain.hr</value>
        <value>user@gmail.com</value>
    </attribute>
</entry>		

$user - UID administratora imenika;

$pwd - zaporka administratora imenika;

Funkcija mora vratiti sve tri vrijednosti: code, msg te panic kako bi se mogao napuniti hash $status_hash.

Funkcija beforeChangeAttribute se razlikuje samo u jednom argumentu:

my($status_hash, $type, $ldap, $base_dn, $entry_in) = @_;

odnosno dodan je argument $type koji određuje koja vrsta promjene je zahtijevana:

• 1 - dodavanje atributa (Add);
   
• 2 - promjena atributa (Modify);
   
• 3 - brisanje atributa (Delete);

after*  funkcije:

Funkcije afterAddUser i afterDeleteUser imaju oblik:

sub after*User{
    my($status_hash, $entry_in, $out_xml, $user, $pwd) = @_;
    my($code, $msg, $before_code, $before_msg, $before_panic);
			
    ($code, $msg) = Plugins::parse_ldap_xml($out_xml);
			
    $before_code = $status_hash->{'MojPlugin'}->{'before'}->{'code'};
    $before_msg = $status_hash->{'MojPlugin'}->{'before'}->{'msg'};
    $before_panic = $status_hash->{'MojPlugin}->{'before'}->{'panic'};
    
    # obrada
			
    return $code, $msg, $out_panic;
}	

gdje je:

$status_hash - isto kao kod before* funkcija;

$entry_in - isto kao kod before* funkcija;

$out_xml - XML kojeg vraća AOSI, oblika:

<entry dn="uid=user,dc=domena,dc=hr">
    <status code="0">Success!</status>
</entry>

$user - isto kao kod before* funkcija;

$pwd - isto kao kod before* funkcija;

Datoteka Plugins.pm sadrži funkciju Plugins::parse_ldap_xml koja olakšava dohvat brojčane i tekstualne obavijesti o uspješnosti AOSI akcije.

U primjeru je prikazan dohvat vrijednosti iz hasha $status_hash.

Kao i kod *before funkcija, funkcija mora vratiti tri vrijednosti: code, msg te panic kako bi se mogao napuniti hash $status_hash.

Funkcija afterChangeAttribute razlikuje se samo u jednom argumentu:

my($status_hash, $type, $ldap, $base_dn, $entry_in) = @_;

odnosno dodan je argument $type koji određuje koja vrsta promjene je zahtijevana:

• 1 - dodavanje atributa (Add);
   
• 2 - promjena atributa (Modify);
   
• 3 - brisanje atributa (Delete);

Izlazni XML:

Izlazni XML AOSI web servisa je također dobio dodatak, odnosno ako nema registriranih modula izlazni XML je nepromijenjen:

<entry dn="uid=user,dc=domain,dc=hr">
    <status code="-81">User does not exist!</status>
</entry>	
		

Međutim ako postoje registrirani moduli (u ovom primjeru su registrirani MSAD, File i WebService) izlazni XML AOSI web servisa bit će oblika:

<entry dn="uid=user,dc=domain,dc=hr">
    <before_plugin_status name="MSAD" code="-10031">User user does not exists!</before_plugin_status>
    <before_plugin_status name="File" code="0">OK</before_plugin_status>
    <before_plugin_status name="WebService" code="0">OK</before_plugin_status>
    <status code="-81">User does not exist!</status>
    <after_plugin_status name="MSAD" code="-10040">Before action returned: panic=0; code=-10031; 
	message=User atest does not exists!</after_plugin_status>
    <after_plugin_status name="File" code="0">OK</after_plugin_status>
    <after_plugin_status name="WebService" code="-81">User does not exist!</after_plugin_status>
</entry>	

Brojčani kodovi:

Svi brojčani kodovi grešaka kod modula moraju imati oblik -10XYY, gdje je:

• X - jedinstveni broj modula kojeg dodjeljuje AAI@EduHr;
   
• YY - jedinstveni kod greške na razini modula;