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)

Važno! - Zamjena certifikata do 5. 3. 2016.


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 ručno, raspakiravanjem arhive koja sadrži simpleSAMLphp i pripadajuće konfiguracijske datoteke u odgovarajući direktorij.

Za primjenu u sustavu AAI@EduHr službeno je podržana verzija programskog alata simpleSAMLphp 1.13.2.

Ostale verzije programskog alata simpleSAMLphp (npr. verzija 1.6.3 instalirana iz paketa na Debian 'squeeze' distribuciji ili verzija 1.9.2 na Debian 'wheezy' distribuciji) više nisu podržane od strane AAI@EduHr tima. Također za sada ne preporučamo instalaciju verzije 1.14.x zbog potencijalnih problema s kompatibilnošću.


Instalacija programskog alata simpleSAMLphp

Programski alat simpleSAMLphp prilagođen za autentikaciju putem sustava AAI@EduHr možete raspakirati i instalirati iz arhive simpleSAMLphp-aai-1.13.2.tar.gz.

U nastavku uputa podrazumjevat ćemo da ste prethodno navedenu arhivu 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:

  • kreirajte alias:
     

    ln -s /var/www/simplesamlphp-aai-1.13.2 /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/simplesaml/

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 tri odjeljka 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;

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 odnose se na servis koji, osim autentikacije korisnika putem sustava AAI@EduHr, omogućuje 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.

Važno ! - Zamjena certifikata do 5. 3. 2016.

Osnovni SSO servis za validaciju SAML poruka do sada je koristio svojevrsni "samopotpisani" certifikat. Obzirom da je Srce za potrebe AAI@EduHr SSO servisa u međuvremenu dobilo certifikat od međunarodno prepoznate tvrtke DigiCert, radi povećanja sigurnosti sustava i usklađivanja s međunarodnim standardima stari, "samopotpisani" certifikat bit će izbačen iz uporabe 5. 3. 2016.

Stoga je do navedenog datuma u konfiguraciju svih aplikacija koje koriste simpleSAMLphp kao autentikacijski modul, a to su više-manje sve aplikacije koje su napisane u programskom jeziku PHP, potrebno unijeti nove metapodatke SSO servisa.

Nove metapodatke možete unijeti na način da na poslužitelju na kojem ste instalirali programski alat simpleSAMLphp raspakirate arhivu sa metapodacima i datoteke authsources.php i saml20-idp-remote.php koje se nalaze u arhivi stavite na odgovarajuća mjesta u konfiguraciji programskog alata simpleSAMLphp, odnosno postojeće konfiguracijske datoteke zamijenite datotekama iz prethodno spomenute arhive. Primjerice, ako je programski alat simpleSAMLphp instaliran u direktoriju /var/www/simplesamlphp/, datoteku authsources.php je potrebno staviti u direktorij:

   /var/www/simplesamlphp/config/

dok je datoteku saml20-idp-remote.php potrebno staviti u direktorij:

   /var/www/simplesamlphp/metadata/

Ako ste programski alat simpleSAMLphp instalirali iz Debian paketa simplesamlphp-aai, datoteku authsources.php je potrebno staviti u direktorij:

   /etc/simplesamlphp/

a datoteku saml20-idp-remote.php potrebno staviti u direktorij:

   /etc/simplesamlphp/metadata/

Pritom treba pripaziti da vlasništvo nad datotekama (vlasnik i grupa) i prava čitanja ostanu isti kao i na prethodnim.

Nakon zamjene konfiguracijskih datoteka nije potrebno restartati HTTP poslužitelj, ali je bitno da obje datoteke budu zamijenjene istodobno.