Autentikacijska i autorizacijska infrastruktura sustava znanosti i visokog obrazovanja u Republici Hrvatskoj
  • Hrvatski
  • English

Kako implementirati autentikaciju putem sustava AAI@EduHr u PHP aplikacijama?

Autentikacijski modul

Instalacija programskog alata SimpleSAMLphp

Napredno konfiguriranje SimpleSAMLphp autentikacijskog modula

Registracija novog resursa u sustavu AAI@EduHr

Primjer korištenja

Važna napomena (samo za Debian Linux)


Autentikacijski modul

U sustavu AAI@EduHr za implementaciju SSO autentikacijskog modula u PHP aplikacijama koristi se programski alat SimpleSAMLphp.
Navedeni programski alat može se instalirati iz Debian paketa ili ručno, raspakiravanjem arhive koja sadrži programski alat SimpleSAMLphp prilagođen sustavu AAI@EduHr u odgovarajući direktorij dostupan web poslužitelju.

Za primjenu u sustavu AAI@EduHr dostupne su verzije: SimpleSAMLphp 1.15.4. i  SimpleSAMLphp 1.18.0 Ako to produkcijska okolina dopušta, uvijek je poželjno instalirati najnoviju verziju.

Starije verzije programskog alata SimpleSAMLphp više nisu podržane od strane AAI@EduHr tima.


Instalacija programskog alata SimpleSAMLphp

Programski alat SimpleSAMLphp prilagođen za autentikaciju putem sustava AAI@EduHr možete raspakirati i instalirati iz jedne od sljedećih arhiva: simplesamlphp-aai-1.15..4.tar.gz, simplesamlphp-aai-1.18.0.tar.gz ili iz odgovarajućeg simplesamlphp-aai Debian paketa (prilikom instalacije iz paketa obratite pozornost da nije dovoljno instalirati paket simplesamlphp, već je potrebno instalirati i paket simplesamlphp-aai).

U nastavku uputa podrazumjevat ćemo da ste neku od gore navedenih arhiva raspakirali u direktorij /var/www/. Ako ste SimpleSAMLphp instalirali u neki drugi direktorij, u daljnim uputama jednostavno zamijenite direktorij /var/www/ direktorijem u kojem ste instalirali SimpleSAMLphp. Nakon raspakiravanja arhive potrebno je napraviti sljedeće:

  • ovisno o verziji SimpleSAMLphp-a, kreirajte alias:

    ln -s /var/www/simplesamlphp-aai-1.15.4 /var/www/simplesamlphp

    ln -s /var/www/simplesamlphp-aai-1.18.0 /var/www/simplesamlphp

  • u datoteci:
     

    /var/www/simplesamlphp/config/config.php


    postavite odgovarajuće vrijednosti parametara 'auth.adminpassword', 'technicalcontact_name' i 'technicalcontact_email';
     

  • U odgovarajućoj konfiguracijskoj datoteci Apache poslužitelja (standardno httpd.conf) za vaš web dodajte liniju:
     

    Alias /simplesaml /var/www/simplesamlphp/www


    i nakon toga učitajte novu konfiguraciju Apache poslužitelja ili jednostavno restartajte poslužitelj.


Napredno konfiguriranje SimpleSAMLphp autentikacijskog modula

U većini slučajeva SimpleSAMLphp autentikacijski modul instaliran prema gore navedenim uputama trebao bi funkcionirati ispravno. Međutim, u određenim uvjetima dobro je podesiti još neke parametre.

Standardno, SimpleSAMLphp je iskonfiguriran da dnevničke zapise piše u syslog. Ako radi bolje preglednosti želite da se dnevnički zapisi zapisuju u datoteku simplesamlphp.log, trebate podesiti da Apache ima dozvolu pisanja u navedenu datoteku:

   chown root:apache /var/www/simplesamlphp/log/simplesamlphp.log

   chmod 620 /var/www/simplesamlphp/log/simplesamlphp.log

Također, SimpleSAMLphp standardno koristi PHP session za pohranu session varijabli. Da bi se izbjegao potencijalni konflikt prilikom pohrane varijabli između PHP aplikacije i programskog alata SimpleSAMLphp, SimpleSAMLphp se može iskonfigurirati tako da varijable pohranjuje u SQLite bazu. Da bi se ostvarila navedena funkcionalnost potrebno je omogućiti Apache poslužitelju da čita i piše u direktorij ../data/ unutar programskog alata SimpleSAMLphp:

   chown root:apache /var/www/simplesamlphp/data/

   chmod 770 /var/www/simplesamlphp/data/

i nakon toga u konfiguracijskoj datoteci /var/www/simplesamlphp/config/config.php podesiti sljedeće parametre:   

   'store.type' => 'sql',

   'store.sql.dsn' => 'sqlite:/var/www/simplesamlphp/data/sqlitedatabase.sq3',

Na taj način, SimpleSAMLphp će svoje varijable pohranjivati u SQLite datoteku /var/www/simplesamlphp/data/sqlitedatabase.sq3 i PHP aplikacija ih neće 'pregaziti'.


Registracija novog resursa u sustavu AAI@EduHr

Da bi autentikacija kroz sustav AAI@EduHr bila omogućena, potrebno je zatražiti registraciju novog resursa u sustavu AAI@EduHr prema uputama na stranici Sustav jedinstvene autentikacije korisnika.

Parametre koje je prilikom registracije resursa potrebno upisati u odjeljku SAML metapodaci možete saznati na način da se web preglednikom prijavite u sučelje za administratore programskog alata SimpleSAMLphp koje bi se, ovisno o nazivu poslužitelja, trebalo nalaziti na adresi:

http(s)://fqdn_naziv_posluzitelja/simplesamlphp/

Ako ste SimpleSAMLphp instalirali iz paketa, zaporku za prijavu u administratorsko sučelje možete pronaći u datoteci:

/var/lib/simplesamlphp/secrets.inc.php

Ako ste SimpleSAMLphp instalirali ručno, zaporka za prijavu u administratorsko sučelje zapisana je kao vrijednost parametra 'auth.adminpassword' u datoteci /var/www/simplesamlphp/config/config.php

Nakon što se prijavite u administratorsko sučelje, kliknite na karticu Federacija (engl. Federation). Otvorit će vam se sučelje kao na sljedećoj slici:


 

 

s nekoliko odjeljaka u kojima su definirani metapodaci ovisno o tome koji autentikacijski servis vaša aplikacija treba koristiti:

  • default-sp - metapodaci koji opisuju vašu aplikaciju u slučaju da za autentikaciju koristite produkcijski AAI@EduHr SSO servis;
     
  • proxy-sp - metapodaci koji opisuju vašu aplikaciju u slučaju da za autentikaciju želite koristiti društvene mreže;
     
  • fedlab-sp - metapodaci koji opisuju vašu aplikaciju u slučaju da za autentikaciju koristite testni SSO servis;
     
  • fedlab-proxy-sp - metapodaci koji opisuju vašu aplikaciju u slučaju da za autentikaciju koristite testni SSO servis s dodatnom funkcionalnošću prijave preko društvenih mreža;

Za svaku grupu metapodataka navedena je vrijednost parametra Entity ID kojeg treba unijeti u polje Jedinstveni identifikator resursa prilikom postavljanja zahtjeva za registracijom novog resursa.

Klikom na opciju Prikaži metapodatke (engl. Show Metadata) otvorit će vam se stranica s prikazom metapodataka u XML i SimpleSAMLphp formatu na kojoj možete pronaći vrijednosti preostalih dvaju parametara (AssertionConsumerService URL i SingleLogoutService URL) koje je potrebno unijeti prilikom popunjavanja zahtjeva za registracijom novog resursa:

 

Obzirom da većina novoregistriranih resursa najprije treba proći kroz fazu razvoja i testiranja, prilikom registracije novog resursa najprije je u registru potrebno unijeti metapodatke za testni SSO servis, odnosno fedlab-sp metapodatke.

Kada servis bude spreman za produkciju, u registru resursa je potrebno ažurirati SAML metapodatke na način da se podaci za testni SSO servis zamijene podacima koji odgovaraju produkcijskom SSO servisu, odnosno default-sp metapodacima.

Metapodaci za proxy-sp i fedlab-proxy-sp odnose se na servise koji, osim autentikacije korisnika putem sustava AAI@EduHr, omogućuju i autentikaciju korisnika putem pojedinih društvenih mreža. Za više informacija o tom servisu kontaktirajte nas elektroničkom poštom na aai@srce.hr


Primjer korištenja

Primjere PHP skripti index.php i logout.php koje demonstriraju uporabu programskog alata SimpleSAMLphp za prijavu i odjavu korisnika možete pronaći u authdemo arhivi.

Ovisno o tome gdje je na vašem poslužitelju instaliran SimpleSAMLphp, na početku obje skripte unutar naredbe require_once() trebate postaviti odgovarajuću putanju do skripte _autoload.php. Primjerice, ako ste SimpleSAMLphp instalirali iz paketa, ispravna putanja trebala bi biti:

require_once('/usr/share/simplesamlphp/lib/_autoload.php');

Analogno, ako ste SimpleSAMLphp instalirali ručno (npr. u direktorij /var/www/), trebate navesti putanju sukladno direktoriju u kojem ste instalirali SimpleSAMLphp:

require_once('/var/www/simplesamlphp/lib/_autoload.php');

Bitno je naglasiti da je u skriptama standardno postavljeno da se autentikacija vrši putem testnog autentikacijskog servisa namijenjenog aplikacijama koje se nalaze u fazi razvoja i testiranja jer se podrazumijeva da sve nove aplikacije koje žele koristiti sustav AAI@EduHr za autentikaciju korisnika najprije trebaju proći kroz fazu testiranja.

Obzirom da se u testnom okruženju iz sigurnosnih razloga ne mogu koristiti produkcijski AAI@EduHr elektronički identiteti, kreiranje testnih elektroničkih identiteta možete zatražiti putem web forme na adresi:

https://fed-lab.aaiedu.hr/zahtjev.php?show=zahtjev_identitet

Nakon što aplikacija prođe kroz fazu razvoja i testiranja, u produkcijsko AAI@EduHr okruženje ju možete uključiti na način da u skriptama za prijavu i odjavu korisnika liniju

$as = new SimpleSAML_Auth_Simple('fedlab-sp');

zamijenite linijom

$as = new SimpleSAML_Auth_Simple('default-sp');

te putem Registra resursa zatražite promjenu statusa resursa iz test u produkcija.

Za sve dodatne informacije, rješavanje problema i bilo kakvih eventualnih nejasnoća kontaktirajte nas elektroničkom poštom na aai@srce.hr

Važna napomena (samo za Debian Linux)

Da bi autentikacija i razmjena podataka ispravno funkcionirala na poslužiteljima s Debian Linux operacijskim sustavom, nakon instalacije SimpleSAMLphp-a potrebno je postaviti vrijednost Suhosin parametra:


suhosin.get.max_value_length = 16382


Ako se instalacija vrši iz paketa simplesamlphp-aai, ova vrijednost će biti automatski postavljena. U suprotnom je odgovarajuću vrijednost navedenog Suhosin parametra potrebno postaviti ručno.