aaieduhr / aosi-module-msad
AOSI Module MSAD
Maintainers
Package info
gitlab.opencode.hr/srce/aai-eduhr/aosi/aosi-module-msad
Type:aosi-module
pkg:composer/aaieduhr/aosi-module-msad
Requires
- php: >=8.2
Requires (Dev)
- aaieduhr/aosi: ^5
- phpstan/phpstan: ^2.1
- phpstan/phpstan-deprecation-rules: ^2.0
- phpunit/phpunit: ^10 || ^11
- rector/rector: ^2.0
- slevomat/coding-standard: ^8
- squizlabs/php_codesniffer: ^3
README
Modul za AOSI aplikaciju koji omogućuje sinkronizaciju korisničkih podataka između LDAP imenika i Microsoft Active Directory-ja (MS AD).
Opis
Modul aosi-module-msad je dodatak (modul) za AOSI aplikaciju. Instalira se unutar AOSI okruženja kao composer paket.
Modul omogućuje automatsku sinkronizaciju korisničkih računa iz LDAP imenika matične ustanove prema Microsoft Active Directory poslužitelju. Izvršava se kao skup event listener-a unutar AOSI okvira, reagirajući na događaje koji se odnose na upravljanje korisnicima i njihovim atributima. Kada AOSI izvrši operaciju nad korisnikom u LDAP imeniku (dodavanje, brisanje, izmjena), modul automatski preslikava tu promjenu u konfigurirani MS AD.
Podržane operacije
Modul prati sljedeće AOSI evente i za svaki izvršava odgovarajuću akciju u MS AD-u:
| Događaj | Opis |
|---|---|
BeforeAddUser / AfterAddUser | Kreiranje korisničkog računa u AD-u prilikom dodavanja korisnika u LDAP |
BeforeDeleteUser / AfterDeleteUser | Brisanje korisničkog računa iz AD-a prilikom brisanja korisnika iz LDAP-a |
BeforeAddUserAttribute / AfterAddUserAttribute | Dodavanje atributa korisniku u AD-u |
BeforeModifyUserAttribute / AfterModifyUserAttribute | Izmjena atributa korisnika u AD-u (uključujući promjenu zaporke) |
BeforeDeleteUserAttribute / AfterDeleteUserAttribute | Brisanje atributa korisnika u AD-u |
Arhitektura
Modul koristi servisnu klasu MSADClient koja enkapsulira svu komunikaciju s Active Directory-jem putem LDAPS protokola. Komunikacija je zaštićena SSL-om (port 636), što je preduvjet za operacije poput promjene zaporke.
Konfiguracija podržava više AOSI base DN-ova, od kojih se svaki može mapirati na zasebnu AD konfiguraciju.
Preduvjeti
- PHP >= 8.2
- HeartPhrame framework
- AD poslužitelj s konfiguriranim LDAPS-om (SSL certifikat, port 636)
- Dva servisna korisnička računa na AD-u:
- AOSIRO – račun samo za čitanje (read-only)
- AOSIWRT – račun s pravima za pisanje (čitanje, kreiranje, brisanje i izmjena korisnika)
Konfiguracija
Lokacija konfiguracijske datoteke
Predložak konfiguracijske datoteke nalazi se u repozitoriju modula:
config/module_msad.php.dist
U produkcijskom okruženju ovu datoteku treba kopirati u AOSI konfiguracijsku mapu pod imenom module_msad.php:
cp config/module_msad.php.dist /path/to/aosi/config/module_msad.php
Napomena: Stvarna putanja AOSI konfiguracijske mape ovisi o instalaciji. Nakon kopiranja datoteku je potrebno prilagoditi stvarnim vrijednostima okoline.
Format konfiguracijske datoteke
Glavni ključ je base_dn, a ispod njega se za svaki AOSI base DN definira blok s AD konfiguracijom:
<?php
declare(strict_types=1);
return [
'base_dn' => [
'dc=ustanova,dc=hr' => [
// parametri za ovu AD konfiguraciju
],
// dodatni base_dn => AD blokovi po potrebi
],
];
Konfiguracijski parametri
U nastavku je opis svakog parametra unutar jednog base_dn bloka.
Parametri za spajanje na AD
| Parametar | Tip | Opis |
|---|---|---|
AD_base | string | Base DN Active Directory domene (npr. DC=MojaDomena,DC=local). |
AD_hostname | string | DNS naziv ili IP adresa AD kontrolera domene (npr. ad.ustanova.hr). |
AD_port | int | Port za LDAPS komunikaciju. Podrazumijevana vrijednost: 636. |
Servisni računi
| Parametar | Tip | Opis |
|---|---|---|
AD_aosiro_dn | string | Distinguished Name servisnog računa za čitanje iz AD-a (npr. CN=AOSIRO,CN=Users,DC=MojaDomena,DC=local). |
AD_aosiro_pwd | string | Zaporka servisnog računa za čitanje. |
AD_aosiwrt_dn | string | Distinguished Name servisnog računa za pisanje u AD (npr. CN=AOSIWRT,CN=Users,DC=MojaDomena,DC=local). |
AD_aosiwrt_pwd | string | Zaporka servisnog računa za pisanje. |
Kreiranje korisnika
| Parametar | Tip | Opis |
|---|---|---|
AD_new_dn | string | Organizacijska jedinica (OU) ili kontejner relativno prema AD_base u koji se inicijalno smještaju novi korisnički računi (npr. OU=NoviKorisnici). |
AD_new_users_disabled | int | Ako je 1, novostvoreni računi bit će onemogućeni (disabled). Podrazumijevano: 0. |
AD_new_users_pne | int | Ako je 1, na novostvorenim računima postavlja se zastavica Password Never Expires. Podrazumijevano: 0. |
AD_new_users_pwd_exp | int | Ako je 1, zaporka novostvorenog računa odmah se označava kao istekla, pa korisnik mora postaviti novu zaporku pri prvoj prijavi. Podrazumijevano: 0. |
UPN sufiks
| Parametar | Tip | Opis |
|---|---|---|
use_custom_suffix | int | Ako je 1, koristi se AD_custom_suffix umjesto podrazumijevane domene za userPrincipalName. Podrazumijevano: 0. |
AD_custom_suffix | string | Prilagođeni UPN sufiks (npr. ustanova.hr). Koristi se samo ako je use_custom_suffix = 1. Omogućuje korisnicima prijavu oblika korisnik@ustanova.hr. |
Filtriranje korisnika
| Parametar | Tip | Opis |
|---|---|---|
custom_filter | string | LDAP filtar za ograničavanje korisnika koji se sinkroniziraju (npr. hrEduPersonPrimaryAffiliation=djelatnik). Ako je prazan, sinkroniziraju se svi korisnici. |
custom_filter_operator | string | Logički operator kada je definirano više filtara: OR ili AND. Podrazumijevano: OR. |
Ponašanje pri pogreškama
| Parametar | Tip | Opis |
|---|---|---|
panic_on_errors | int | Ako je 1, modul prekida sve sljedeće operacije kada se pojavi pogreška. Podrazumijevano: 0. |
show_warnings_as_errors | int | Ako je 1, upozorenja koja AD vrati prosljeđuju se AOSI okviru kao pogreške (nenulti status). Podrazumijevano: 0. |
Kontrola pristupa
| Parametar | Tip | Opis |
|---|---|---|
direct_access | int | Ako je 1, dopušta izravan (neautentificirani) pristup s dopuštenih IP adresa. Podrazumijevano: 0. |
direct_access_ips | array | Lista IP adresa s kojih je dozvoljen izravan pristup (npr. ['127.0.0.1', '::1']). |
admin_users | array | Lista UID-ova korisnika s admin pravima za upravljanje u AD-u (npr. ['u100', 'u200']). |
exclude_users | array | Lista UID-ova korisnika koji se isključuju iz sinkronizacije (npr. ['Administrator']). |
Dopušteni atributi i raspodjela u OU-e
| Parametar | Tip | Opis |
|---|---|---|
m_attributes | array | Lista atributa čija se izmjena prosljeđuje u AD (npr. ['userPassword', 'sn', 'givenName']). Izmjena atributa koji nisu na popisu ne prosljeđuje se AD-u. |
AD_profile_path | string | Predložak putanje za Windows roaming profil. Ostaviti praznim ako se ne koristi. |
users_ou | array | Mapiranje vrijednosti atributa na organizacijske jedinice pri kreiranju korisnika. Ključ default služi kao podrazumijevani OU. |
Primjer users_ou
'users_ou' => [
'hrEduPersonPrimaryAffiliation' => [
'default' => 'OU=Ostali',
'student' => 'OU=Studenti',
'djelatnik' => 'OU=Djelatnici',
],
],
Ovaj primjer smješta studente u OU=Studenti, djelatnike u OU=Djelatnici, a sve ostale u OU=Ostali.
Primjer kompletne konfiguracije
<?php
declare(strict_types=1);
return [
'base_dn' => [
'dc=ustanova,dc=hr' => [
'AD_base' => 'DC=MojaDomena,DC=local',
'AD_hostname' => 'ad.ustanova.hr',
'AD_port' => 636,
'AD_aosiro_dn' => 'CN=AOSIRO,CN=Users,DC=MojaDomena,DC=local',
'AD_aosiro_pwd' => 'tajna-lozinka-ro',
'AD_aosiwrt_dn' => 'CN=AOSIWRT,CN=Users,DC=MojaDomena,DC=local',
'AD_aosiwrt_pwd' => 'tajna-lozinka-rw',
'AD_new_dn' => 'CN=Users',
'AD_new_users_disabled' => 0,
'AD_new_users_pne' => 1,
'AD_new_users_pwd_exp' => 0,
'use_custom_suffix' => 1,
'AD_custom_suffix' => 'ustanova.hr',
'custom_filter' => 'hrEduPersonPrimaryAffiliation=djelatnik',
'custom_filter_operator' => 'OR',
'AD_profile_path' => '',
'panic_on_errors' => 0,
'show_warnings_as_errors' => 0,
'direct_access' => 0,
'direct_access_ips' => [],
'm_attributes' => [
'userPassword',
],
'admin_users' => [
'u100',
'u200',
],
'exclude_users' => [],
'users_ou' => [
'hrEduPersonPrimaryAffiliation' => [
'default' => 'OU=Ostali',
'student' => 'OU=Studenti',
'djelatnik' => 'OU=Djelatnici',
],
],
],
],
];
Više AOSI base DN-ova
Konfiguracijska struktura podržava definiranje više base_dn blokova. Svaki ključ u nizu base_dn predstavlja zasebni AOSI base DN koji se mapira na vlastitu AD konfiguraciju. Modul za svaki korisnikov DN automatski određuje pripadajući base DN i odabire odgovarajuću konfiguraciju.
return [
'base_dn' => [
'dc=ustanova,dc=hr' => [
// AD konfiguracija za korisnike čiji DN završava s dc=ustanova,dc=hr
// ... parametri
],
'dc=druga-ustanova,dc=hr' => [
// AD konfiguracija za korisnike čiji DN završava s dc=druga-ustanova,dc=hr
// ... parametri
],
],
];
Napomena: Budući da su ključevi niza PHP asocijativnog niza, za isti AOSI base DN može postojati samo jedan blok konfiguracije. Korisnici pod istim LDAP base DN-om ne mogu se usmjeriti na različite AD poslužitelje.
Administratorsko sučelje
Modul pruža web stranicu dostupnu AOSI administratorima na putanji /index unutar modula. Stranica prikazuje trenutačnu konfiguraciju modula (prikaz svih base_dn blokova i pripadajućih parametara) u tabličnom obliku.
Korištenje repozitorija
git clone git@gitlab.srce.hr:aai-eduhr/aosi/aosi-module-msad.git
Instalacija ovisnosti
cp auth.json.example-gitlab-token auth.json
nano auth.json # zamijenite token sa svojim GitLab tokenom
composer install
Pokretanje testova
Svi testovi trebali bi proći:
composer pre
Izrada modula
Prilikom izrade modula korišteni su alati umjetne inteligencije
Licencija
Ovaj rad objavljen je pod European Union Public License (EUPL) v1.2.