SW ATTIS Synchronizace s LDAP serverem

SW ATTIS Synchronizace s LDAP serverem Verze manuálu: 0.9 Datum: 6. 10. 2016 ATTN Consulting s.r.o. Strana: 1 / 9

Obsah 1. Základní popis funkce... 3 2. Nutná znalost a předpoklady pro provedení synchronizace... 3 3. Definice úlohy... 3 Příklad konfigurace:... 4 Zdroj dat <Source> obsahuje atribut:... 4 Transformace <Lookup>... 5 Transformace <Part>... 6 Transformace <UserDomainName>... 6 4. Datové typy, konverze... 7 5. Seznam cílových objektů ATTISu... 8 6. Postup synchronizace... 9 ATTN Consulting s.r.o. Strana: 2 / 9

1. Základní popis funkce LDAP (Lightweight Directory Access Protocol) je odlehčený protokol vycházející ze standardu X.500 pro ukládání a přístup k adresářovým datům. Synchronizace s LDAP je v ATTISu implementována jako plánovaná úloha. Je možné synchronizovat údaje ve směru z LDAP serveru směrem do ATTISu. Synchronizovat lze osoby, uživatelské účty a uživatelské role včetně vazeb: osoba uživatelský účet uživatelský účet uživatelská role 2. Nutná znalost a předpoklady pro provedení synchronizace Jako zdroj dat pro synchronizaci může být jakýkoliv server odpovídající definici LDAP. Například Active Directory, OpenLDAP apod. Synchronizační úloha není vázána na přesnou adresářovou strukturu je parametrizovatelná pomocí konfigurace datových transformací. Tato konfigurace definuje, co se na straně LDAP vybírá a kam se to na straně ATTISu ukládá. Pro každou transformaci je pak určen synchronizační klíč na straně LDAP, jenž může být stanoven libovolně při definici transformace za předpokladu, že je zaručena jeho unikátnost a jednoznačnost. Na straně ATTISu se používají jeho interní unikátní OId. Synchronizační klíč je vždy typu String. Ke každému synchronizačnímu klíči je přiřazeno příslušné Oid (GUID) odpovídajícího ATTISovského objektu. Do klíče (Id) je možné uložit textovou reprezentaci v podstatě čehokoliv (GUID, SID, DN apod.) a je vždy na úvaze implementátora, jaký konkrétní atribut použije. Mělo by se však jednak o položku, která unikátně objekt identifikuje a která se v čase nemění. Jakmile je ovšem proces synchronizace spuštěn, není doporučeno měnit mapování klíče (v případě, že by došlo ke změně klíče, proběhne plná synchronizace všech objektů, protože stávající vazba bude ztracena). Konfigurace určuje typ dat: osoba (Person), uživatel (User) nebo role (Role). Zdroj pak má stanoveno kritérium pro výběr a mapování atributů objektů. Synchronizační úloha provede dotaz na LDAP server a jednotlivé objekty se pak převedou do mezivýsledků. V rámci převodu může docházet ke konverzi datových typů jednotlivých atributů (např. SID na řetězec). Datové mezistruktury se pak nahrávají do konkrétních interních objektů ATTISu, což je krok, který už je od uživatele odstíněn a dán interní implementací. V aplikaci ATTIS, objekty typu uživatel a role, obsahují atribut Nesynchronizovat s LDAP. Tento atribut umožní danému objektu býti netečným vůči synchronizaci s LDAP a je určen pro systémové uživatele a role ATTISu. 3. Definice úlohy Definici provedeme v menu ATTIS: Systémové nastavení / Nastavení plánovaných úloh / Definice úkolu kde založíme nový úkol typu LDAP synchronizace. Podstatnými parametry úlohy synchronizace je adresa LDAP serveru, číslo portu, jméno, heslo a volitelně lze užít komunikaci šifrovanou pomocí SSL. Transformace dat je definována ve formátu XML dle níže uvedené specifikace. XML parser se snaží poskytovat co nejpřesnější informace o případné chybě (resp. chybách), které umožňují snadnou lokalizaci a opravu problémů. ATTN Consulting s.r.o. Strana: 3 / 9

Chyby a průběh synchronizace se logují v logu aplikace ATTIS. Příklad konfigurace: <Configuration> <Options UserDefaultPassword = "aa" ChangePasswordOnFirstLogon="true" /> <Sources> <Source TargetEntity="User"> Filter="(&(objectClass=user)(!objectClass=computer)(!UserAccountControl:1.2.840.113556.1.4.803:=2))" Scope="SubTree" /> <Mappings> <Mapping Source="objectSid" Target="Id" Type="Sid" ConvertTo="String" /> <Mapping Source="userPrincipalName" Target="Username" Type="String" > <UserDomainName> <Upn2DownLevelLogon UpnSuffix="@attn.local" NetBiosDomainName="ATTN"/> </UserDomainName> <Mapping Source="memberOf" Target="Roles" Type="String" Optional="true" /> </Mappings> </Source> <Source TargetEntity="Role"> Filter="(&(objectClass=group)(cn=ATTN))" Scope="SubTree" /> <Mappings> <Mapping Source="objectSid" Target="Id" Type="Sid" ConvertTo="String" /> <Mapping Source="sAMAccountName" Target="Name" Type="String" /> <Mapping Source="member" Target="Users" Type="String" Optional="true"> <Lookup Field="objectSid" Type="Sid" ConvertTo="String"> Filter="(&(objectClass=user)(distinguishedName=@@))" Scope="SubTree" /> </Lookup> </Mappings> </Source> <Source TargetEntity="Person"> Filter="(objectClass=user)" Scope="SubTree" /> <Mappings> <Mapping Source="objectGUID" Target="Id" Type="Guid" ConvertTo="String" /> <Mapping Source="userPrincipalName" Target="CN" Type="String" Optional="true" > <UserDomainName> <Upn2DownLevelLogon UpnSuffix="@attn.local" NetBiosDomainName="ATTN"/> </UserDomainName> <Mapping Source="name" Target="FirstName" Type="String"> <Part Separator=" " Index="0" /> <Mapping Source="name" Target="LastName" Type="String"> <Part Separator=" " Index="1" /> </Mappings> </Source> </Sources> </Configuration> Konfigurace je uzavřena mezi kořenové elementy <Configuration></Configuration>. Options definují volitelnou možnost výchozího hesla a nutnosti změny. Options nemusí být uvedeny. Definice zdrojů dat je omezena elementy <Source></Source>. Je možné definovat více zdrojů, které se vyhodnocují postupně jeden po druhém, odshora dolů. Na pořadí tedy záleží (!), je vhodné, aby data, která na sebe logicky navazují, byla definována ve vhodném pořadí. Zdroj dat <Source> obsahuje atribut: - TargetEntity povinný druh dat, která jsou tímto zdrojem poskytována: Person, User nebo Role. Uvnitře elementu <Source> existuje právě jedna povinná definice kritéria <SearchCriteria>, na základě kterého jsou hledány objektu v LDAP a kolekce mapování <Mappings>, které určují, jaký atribut originálního objektu v LDAP struktuře se přenáší na cílový atribut v ATTISu. ATTN Consulting s.r.o. Strana: 4 / 9

Element <SearchCriteria> definuje vyhledávací filtr: - SearchBase povinný je kořen hledání dle definice LDAP, - Filter povinný je filtr v zápisu dle definice LDAP a - Scope povinný určuje rozsah hledání vzhledem ke koření: Object (pouze daný objekt dle filtru), OneLevel (pouze jedna úroveň dle filtru) nebo SubTree (celý podstrom dle filtru). U definice filtru je nutno mít na paměti, že některé speciální znaky je nutno v XML uvádět jako entity (např. & = & apod.). Element <Mapping> slouží pro definici mapování právě jednoho atributu ze zdroje do cíle: - Source povinný název pole ve zdroji, - Target povinný název pole v cíli, - Typ povinný typ datového pole ve zdroji, - ConvertTo nepovinný volitelná konverze hodnoty do zvoleného typu a - Optional nepovinný vyjadřuje, že atribut nemusí být ve zdroji přítomen a je ignorován. Není-li atribut definován jako nepovinný a zdrojový objekt jej neobsahuje, je signalizována chyba a synchronizace je přerušena. Mapování může volitelně obsahovat kolekci transformací získané hodnoty před tím, než je výsledek přiřazen do cílového pole. V aktuální implementaci jsou k dispozici transformace <Lookup>, <Part>. a <UserDomainName>. Transformace <Lookup> Transformace <Lookup> umožňuje: - vyhledání a záměnu hodnoty za hodnotu v jiném objektu (hodnotu nelze modifikovat!!!) - získaná hodnota může být převedena na typově jinou a ta se následně použije v importu Dle uvedeného příkladu importu rolí: <Source TargetEntity="Role"> Filter="(&(objectClass=group)(cn=test_role))" Scope="SubTree" /> <Mappings>.. <Mapping Source="member" Target="Users" Type="String" Optional="true"> <Lookup Field="objectSid" Type="Sid" ConvertTo="String"> Filter="(&(objectClass=user)(distinguishedName=@@))" Scope="SubTree" /> </Lookup> </Mappings> </Source> Provádí: 1) Skupina v LDAP test_role Na její členy ( member ) se uplatní definice Lookup Filter="(&(objectClass=group)(cn=test_role))" 2) Atribut member se mapuje na cílový atribut Users. Zdrojová hodnota je typu String a je nepovinná. <Mapping Source="member" Target="Users" Type="String" Optional="true"> 3) Hodnota member není SID na základě kterého chceme objekty párovat, ale jedná se o jednoznačné jméno (distinguishedname typu string). Aby byl ATTIS schopen objekty přiřadit, musíme definovat záměnu hodnoty distinguishedname za objectsid. <Lookup Field="objectSid" Type="Sid" ConvertTo="String"> Filter="(&(objectClass=user)(distinguishedName=@@))" Scope="SubTree" /> </Lookup> Na základě definice <Lookup> je vyhledán dle <SearchCriteria> objekt, jehož distinguishedname (DN) odpovídá hledané hodnotě. Důležitý je řetězec @@ ve filtru kritéria, který je vždy v daném kroku nahrazen ATTN Consulting s.r.o. Strana: 5 / 9

jménem objektu DN. Pokud by kritérium vracelo více objektů, bere se první z nich. Nicméně v návrhu konfigurace je nanejvýš vhodné volit takový postup, aby identifikace objektu byla jednoznačná. Atribut member skupiny test_role ve tvaru distinguishedname typu string je vyhledán a nahrazen atributem objectsid objektu user. Atributy elementu <Lookup> pak definují, jakým způsobem bude nalezený objekt zpracován: - Field povinný název pole v objektu, který bude vracen - Type povinný typ pole v objektu - ConvertTo nepovinný volitelná konverze hodnoty do zvoleného typu. V našem případě se tedy vezme z objektu objectclass=user jeho objectsid typu SID a konvertuje se na řetězec. Teprve tento se pak uloží do cílového pole Users. Mějte na paměti, že celý výpočet musí být typově v pořádku, tj. je nutno správně specifikovat typ hodnoty a dle potřeby definovat konverzi před jejím překladem a též před přiřazením do cílového pole. V opačném případě převod selže a proces synchronizace je zastaven. Transformace <Part> Tato transformace umožňuje získat část řetězce. Vstupní hodnota je rozdělena pomocí oddělovače a jako výsledek se vrací příslušná část dle požadovaného indexu. Typickým příkladem je získání příjmení z plného jména. Např. <Mapping Source="name" Target="LastName" Type="String"> <Part Separator=" " Index="1" /> Atributy jsou následující: - Separator povinný určuje separační řetězec, který odděluje jednotlivé části a - Index povinný je pořadí části, která bude vrácena. Pokud je index mimo rozsah, vrací se prázdný řetězec. Transformace <UserDomainName> Transformace <UserDomainName> se používá pro převod hodnoty ve tvaru username@domain.domain na tvar domain\username. Př.: <Mapping Source="userPrincipalName" Target="Username" Type="String" > <UserDomainName> <Upn2DownLevelLogon UpnSuffix="@attn.local" NetBiosDomainName="ATTN"/> </UserDomainName> V našem případě, userprincipalname vrací hodnotu ve tvaru username@attn.local a požadovaný tvar je attn\username. UpnSuffix obsahuje řetězec, který bude zaměněn řetězcem NetBiosDomainName a následně doplněn na začátek řetězce. Konec řetězce, až po znak @ (od konce řetězce) včetně, je odmazán. Znaky @ a \ mohou, ale nemusí být uvedeny, jsou doplněny automaticky. UpnSuffix a NetBiosDomainName musí být upraven dle konkrétní situace. ATTN Consulting s.r.o. Strana: 6 / 9

4. Datové typy, konverze V definici mapování je nutné explicitně uvést, v jakém formátu je zdrojová hodnota a na jakou cílovou hodnotu bude (pokud nemá zůstat v originále) konvertována. Jestliže nelze konverzi provést z důvodu nekompatibility typů, synchronizace selže. V současné implementaci jsou podporovány následující datové typy: - String řetězec ve formátu unicode, volitelně konvertovatelný na Guid nebo Sid - Boolean binární hodnota true / false nebo 0 / 1 - Integer celé číslo 32-bitů - Guid unikátní identifikátor, volitelně konvertovatelný na String - Sid Active Directory identifikátor, volitelně konvertovatelný na String - Universal univerzální typ, v podstatě hexadecimální řetězec (všechny LDAP atributy jsou fyzicky uloženy jako sekvence bajtů a tímto způsobem je lze reprezentovat). ATTN Consulting s.r.o. Strana: 7 / 9

5. Seznam cílových objektů ATTISu Person User Role Položky, které lze synchronizovat. - Id (String) povinný klíč - CN (String) uživatelské jméno - DegreeAfterName (String) - DegreeBeforeName (String) - Description (String) - Email (String) - FirstName (String) - LastName (String) - Name (String) - Phone (String) - TimeContract (String, hodnota musí být ve tvaru celého čísla) - UrlIdentificator (String) - ValidFrom (String, hodnota musí být ve tvaru data) - ValidTo (String, hodnota musí být ve tvaru data) - Number - Id (String) povinný klíč - Username (String) - DefaultPassword (String) - ChangePasswordOnFirstLogin (Boolean) - Description (String) - Roles (String[]) přiřazení rolí - Id (String) povinný klíč - Name (String) - Description (String) - IsDefault (Boolean) - IsAdministrative (Boolean) - CanEditModel (Boolean) - Users (String[]) přiřazení uživatelů.pole Id je povinné a musí na něj být mapován synchronizační klíč. Každý datový zdroj tedy musí povinně obsahovat mapování alespoň pro cílové pole Id, jinak je situace vyhodnocena jako chybná a import je přerušen. Ostatní pole jsou využitelná volitelně a vždy je synchronizováno jenom to, co je mapováno. Pole, pro které není definováno mapování, je ponecháno beze změny (u nově založených objektů obsahuje výchozí hodnotu). ATTN Consulting s.r.o. Strana: 8 / 9

Asociace - vazby: Person CN je uživatelské jméno (nikoliv Id uživatele), na základě kterého je vytvořena asociace na příslušného uživatele; definuje tedy mapování mezi osobou a uživatelem; uživatel musí v době importu existovat, User Roles je seznam rolí (jejich Id) daného uživatele; definuje tedy mapování mezi uživatelem a rolemi. Role Users je seznam uživatelů (jejich Id) dané role; definuje mapování mezi rolí a uživateli. 6. Postup synchronizace 1. Provede se zpracování konfigurace a připraví algoritmus pro synchronizaci. 2. Úloha kontaktuje LDAP server a zvolí první zdroj dat. 3. Pomocí vyhledávacího kritéria právě zpracovávaného zdroje požádá LDAP o vrácení kolekce odpovídajících objektů. 4. Úloha projde vstupní kolekci, zkontroluje povinné atributy jednotlivých objektů, provede konverzi hodnot z originálního na cílový datový typ a předpřipraví kolekci objektů vhodných pro import do ATTISu (meziobjektů). 5. Dojde k importu dat do databáze ATTISu, přičemž pro přiřazení objektů z importu k objektům ATTISu se využije klíč. 6. Postup se opakuje pro další zdroj dat. ATTN Consulting s.r.o. Strana: 9 / 9