Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
tutorial:adm:connect_a_db_system [2024/04/15 09:43] – [Systems - DB: Source of identities] cemtutorial:adm:connect_a_db_system [2026/06/05 06:46] (current) – translation to EN - TODO images not working still kopro
Line 1: Line 1:
-====== Systems - DB: Source of identities ======+{{tag> tutorial system synchronization database connector identity sync}}
  
 +====== Systems - DB: Source of identities ======
  
 ===== Basic configuration ===== ===== Basic configuration =====
Line 6: Line 7:
 This tutorial deals with how to connect an authoritative (primary) system as a source of identities. To this end, the basic Database Table Connector will come in handy. The source table we are going to use consists of 4 columns: id, username, first name, and last name. This tutorial deals with how to connect an authoritative (primary) system as a source of identities. To this end, the basic Database Table Connector will come in handy. The source table we are going to use consists of 4 columns: id, username, first name, and last name.
  
-First, click on the **Add** button on the //Systems// tab item. Pick a system name, say, //Some base//. Check the ReadOnly checkbox field – your database is to serve as a source of data only, you don't actually wish to be able to write to it. Keep other attributes of the system as they are by default. Then click on the **Save and continue** button. +First, click on the <label type="success">Add</label> button on the //Systems// tab item. Pick a system name, say, //Some base//. Check the ReadOnly checkbox field - your database is to serve as a source of data only, you don't actually wish to be able to write to it. Keep other attributes of the system as they are by default. Then click on the <label type="success">Save and continue</label> button.
  
 ==== Connector configuration ==== ==== Connector configuration ====
  
-Go to the //Configuration// tab and select the //Database Table Connector (connId)//. Next, enter the path to the DB and the user login that IdM will use to get access the DB. This user must be authorized to read the connected table, as a minimum. Specific settings in our example:+Go to the //Configuration// tab and select the //Database Table Connector (connId)//. Next, enter the path to the DB and the user login that IdM will use to get access to the DB. This user must be authorized to read the connected table, as a minimum. Specific settings in our example:
  
 +  * Host = `localhost` - the DB runs on the same server as IdM
 +  * Port = `5432` - the standard port for PostgreSQL
 +  * User = `idmadmin` - a previously created DB user with sufficient permissions to read the data
 +  * User Password = <nowiki>***</nowiki> - the password of the DB user entered in the previous step
 +  * Table = `users` - we have prepared a table named //users// in the DB, from which we are going to synchronize users into CzechIdM
 +  * Key Column = `id` - the //Database Table Connector (connId)// requires you to explicitly mark the column which is used as a unique identifier in the DB. Typically, this is the primary key of the table.
 +  * JDBC Connection URL = ''jdbc:postgresql:<nowiki>//</nowiki>localhost:5432/Somebase'' - specifies the path to the DB
 +  * JDBC Driver = ''org.postgresql.Driver'' - the connector supports several different types of relational databases. In our case, we are connecting a PostgreSQL DB. To connect it, you need to set a driver in CzechIdM which will handle the operations with the given database type.
  
-<note important>TODO translate to ENG</note>+At the time of writing this tutorial, the driver for PostgreSQL can be downloaded here: [[https://jdbc.postgresql.org/download.html|https://jdbc.postgresql.org/download.html]]
  
 +Apart from the settings in the system configuration in CzechIdM, the driver file must be placed into the library location of the application server. In our case, CzechIdM runs on the Tomcat application server, so we place the driver into the //lib// folder. Alternatively, the driver can be placed into WEB-INF/lib directly in the CzechIdM application location.
  
-  * Host = localhost – DB nám běží na stejném serveru jako IdM +Leave the other connector attributes empty or with their default pre-filled values.
-  * Port = 5432 – standardní port pro PostgreSQL +
-  * User = idmadmin – dříve vytvořený uživatel v DB s dostatečným oprávněním na čtení dat +
-  * User Password = %%**%%%%**%%* - zde je hodnota hesla pro DB uživatele zadaného v předchozím kroku +
-  * Table = users – v DB jsme si předpřipravili tabulku s názvem //users,//ze které budeme synchronizovat uživatele do CzechIdM +
-  * Key Column = id - //Database Table Connector (connId)//vyžaduje explicitní vyznačení sloupce, který je v DB použit jako unikátní identifikátor. Typicky se jedná o primární klíč tabulky. +
-  * JDBC Connection URL = //jdbc:postgresql:%%//%%localhost:5432/Somebase// – udává cestu k DB +
-  * JDBC Driver = org.postgresql.Driver – konektor podporuje více různých typů relačních databází. V našem případě napojujeme DB PostgreSql. Pro napojení je třeba v CzechIdM nastavit ovladač, který zajistí operace s daným typem databáze.+
  
-V době psaní tohoto návodu lze driver pro PostgreSql stáhnout zde https://jdbc.postgresql.org/download.html+If everything has been set correctly and CzechIdM can access our DB, we can verify the configuration by clicking on the green <label type="success">Test connector</label> button at the top of the page.
  
-Kromě nastavení v konfiguraci systému v CzechIdM je potřeba soubor s ovladačem umístit do umístění pro knihovny aplikačního serveru. V našem případě běží CzechIdM v AS Tomcat, tedy driver umístíme do složky //lib//. Případně můžeme umístit driver do WEB-INF/lib přímo v umístění aplikace CzechIdM.+==== System schema ====
  
-Ostatní atributy konektoru necháme nevyplněné nebo s výchozí předvyplněnou hodnotou.+{{:Pictures/10000000000002F2000001899DDDD0CCFE8E5409.png?604x314}}
  
-Pokud jsme vše správně nastavili a CzechIdM má přístup do naší DB, můžeme konfiguraci ověřit kliknutím na zelené tlačítko //Test konektoru// na začátku stránky.+Go to the //System schema// tab (described in chapter 2.3.2 FIXME) and click on the <label type="success">Generate schema</label> button. The connector automatically returns the list of attributes available on the connected system. The object returned by the connector is of the <nowiki>__ACCOUNT__</nowiki> type by default, which suits our purpose of connecting identities. As expected, the connector also returned 4 attributes corresponding to our columns in the DB. They can be displayed by clicking on the magnifier icon next to the object type.
  
-==== Schéma DB systému ====+In addition, the connector returned the <nowiki>__NAME__</nowiki> attribute, which is defined by the ConnId standard. The //Database Table Connector (connId)// implementation we use follows this specification, but it does not use this attribute for synchronization, so we will not need it for reading data from the source system.
  
-{{:Pictures/10000000000002F2000001899DDDD0CCFE8E5409.png?604x314}}//Přejdeme na záložku Schéma systému (popsáno v kapitole 2.3.2) a klikneme na tlačítko Generovat schema.// Konektor nám automaticky vrátí seznam dostupných atributů na napojovaném systému. Objekt vrácený z konektoru je ve výchozím stavu typu %%__%%ACCOUNT%%__%%, což nám pro napojení identit vyhovuje. Dále konektor vrátil podle očekávání 4 atributy dle našich sloupečků v DB. Ty zobrazíme kliknutím na obrázek lupy vedle typu objektu.+By clicking on the magnifier icon next to the attribute name, you can display the configuration details of the particular attribute.
  
-Navíc nám konektor ale vrátil atribut %%__%%NAME%%__%%, který je definován standardem ConnId. Námi použitá implementace //Database Table Connector (connId)// se této specifikace drží, avšak pro synchronizaci jej nepoužívá, proto pro naše načítání dat ze zdrojového systému jej nebudeme potřebovat.+{{:Pictures/100000000000017D0000023659372405B77FE7FF.png?380x565|Figure 22: Attribute detail in the system schema}}
  
-Kliknutím na lupu vedle názvu atributu je možné zobrazit detaily konfigurace pro konkrétní atribut.+In our case, all the attributes have the same configuration except for the `id` and <nowiki>__NAME__</nowiki> attributes, which are marked as required.
  
-{{:Pictures/100000000000017D0000023659372405B77FE7FF.png?380x565| \\ +==== Synchronization mapping for the DB ====
-Obrázek 22: Detail atributu ve schématu systému}}+
  
-V našem případě mají všechny atributy stejnou konfiguraci až na atribut id a %%__%%NAME%%__%%, které jsou označeny jako povinné.+Once the system schema is ready, we can proceed to the synchronization mapping. It allows us to define which attributes from the available schema will be synchronized into IdM, and also which Identity attributes will be filled with the attributes from the account.
  
-==== Mapování synchronizace pro DB ====+On the //Attribute mapping// tab, click on the <label type="success">Add</label> button and fill in:
  
-Máme-li připravené schéma systému, pak přikročíme k mapování synchronizace. To nám umožní určit, jaké atributy z dostupného schématu nasynchronizujeme do IdM a také do kterých atributů Identity se budou atributy z účtu plnit.+  * Operation type = Synchronization 
 +  * Mapping name = `users` - our label for this synchronization. A system can have several different synchronizations. 
 +  * Object name = <nowiki>__ACCOUNT__</nowiki> - the type of object we want to synchronize. 
 +  * IdM entity type = Identity - the entity type onto which the object type selected in the previous step will be mapped.
  
-Na záložce //mapování atributů// stiskneme tlačítko //Přidat.//Vyplníme+{{:Pictures/10000000000002DA000000DD52F875E7D80B2EDD.png?580x175}}
  
-  * Typ operace = Synchronizace +After creating the mapping, open its detail and set the particular bindings of the account attributes to the identity attributes. Set the mapping for all our attributes: `id`, `name`, `surname`, `username`.
-  * Název mapování = users – naše označení této sychronizace. Systém může mít více různých synchronizací. +
-  * Název objektu = %%__%%ACCOUNT%%__%% - typ objektu, který chceme synchronizovat. +
-  * {{:Pictures/10000000000002DA000000DD52F875E7D80B2EDD.png?580x175}}Typ IdM entity = Identita – typ entity, na kterou se bude mapovat typ objektu vybraný v předchozím bodu.+
  
-Po vytvoření mapování klikneme na detail tohoto mapování a nastavíme konkrétní vazby atributů účtu na atribut identity. Nastavíme mapování pro všechny naše atributy id, name, surname, username.+{{:Pictures/10000000000001E30000019BC2AB56CA61594463.png?482x410}}
  
-{{:Pictures/10000000000001E30000019BC2AB56CA61594463.png?482x410|fig:}}//Například atribut id// nastavíme dle následujícího obrázku. Ostatní atributy nastavím stejně až na položky+For example, the `id` attribute is set according to the picture above. The other attributes are set the same way, except for the following items:
  
-  * //Je identifikátorem//, která je zaškrtnuta pouze pro //id//. +  * //Is identifier// - checked only for `id`. 
-  * Atribut entity – říká, že atribut ze systému pošleme k základnímu atributu entity v CzechDIM. Vyplníme jej u všech položek kromě //id//. +  * Entity attribute - says that the attribute from the system will be mapped to a basic attribute of the entity in CzechIdM. Fill it in for all items except `id`. 
-  * IdM klíč – definuje který atribut entity v CzechIdM bude daný atribut ze systému plnit. Tato volba je dosupná pouze pokud jsme předtím zaškrtli volbu //Atribut entity//. Dle obrázku výše namapujeme atributy //name, surname// a //username// na atributy v CzechIdM //firstName, lastName// a //username//.+  * IdM key - defines which entity attribute in CzechIdM will be filled with the given attribute from the system. This option is available only if the //Entity attribute// option has been checked before. According to the picture above, we map the attributes `name`, `surname` and `username` to the CzechIdM attributes `firstName`, `lastName` and `username`.
  
-Jak je vidět, ne všechny atributy musíme mapovat na atribut v CzechIdM. Ty, které nenamapujeme, nebudou vyplněny k entitě v CzechIdM. V našem případě se k entitě nepřenese //id//, které nechceme dále využívat, ani jej neplánujeme posílat do spravovaných systémů.+As you can see, not all attributes have to be mapped to an attribute in CzechIdM. Those which are not mapped will not be filled in the entity in CzechIdM. In our case, the `id` attribute will not be transferred to the entity - we do not want to use it any further, nor do we plan to send it to managed systems.
  
-V našem příkladu jsme namapovali atributy účtu na systému na základní atributy Identity. Každá entita v CzechIdM má základní sadu atributů, které však lze rozšířit. Chceme-li v synchronizaci namapovat atributy na rozšířené atributy entit v CzechIdM musíme mít nejprve přichystán formulář EAV atributů pro danou entitu, viz kapitola 2.10.+In our example, we mapped the account attributes on the system to the basic Identity attributes. Every entity in CzechIdM has a basic set of attributes, which can however be extended. If you want to map attributes to extended attributes of CzechIdM entities in the synchronization, you must first prepare the EAV attribute form for the given entity, see chapter 2.10 FIXME.
  
 {{:Pictures/10000000000001E3000002B5C004B4BE134FD619.png?482x691}} {{:Pictures/10000000000001E3000002B5C004B4BE134FD619.png?482x691}}
  
-====  Nastavení synchronizace ====+==== Synchronization settings ==== 
 + 
 +In the previous chapter, we prepared the attribute mapping for the synchronization. Now we will set up the synchronization process itself, which will use this mapping. 
 + 
 +{{:Pictures/10000000000002C60000019CA3EF9A94F6898EE9.png?604x349}}
  
-V předchozí kapitole jsme si připravili mapování atributů pro synchronizaci. Nyní nastavíme samotný proces synchronizace, který toto mapování bude používat.+Go to the //Synchronization// tab and click on the <label type="success">Add</label> button. In the synchronization, fill in the //name// and //enable// it according to the picture. We can also check //Reconciliation// - we are going to read all accounts without any restriction. As the set of mapped attributes, select the `users` mapping which we created in the previous chapter.
  
-{{:Pictures/10000000000002C60000019CA3EF9A94F6898EE9.png?604x349}}//Přejdeme na záložku Synchronizace// a klikneme na tlačítko přidat. V synchronizaci vyplníme //název// a //povolíme// ji dle obrázku. //Rekoncilace// můžeme zaškrtnout také, budeme načítat všechny účty bez omezení. Do sady mapovacích atributů vybereme mapování //users//, které jsme si vytvořili v minulé kapitole.+Then proceed in the form to the settings of operations for the individual account and entity states and set them as follows:
  
-Dále přejdeme ve formuláři až k nastavení operací pro jednotlivé stavy účtu a entity a nastavíme následujícím způsobem:+  * Link exists, action = Update entity - This ensures that on repeated synchronization runs, when the //account (end system)// - //identity (CzechIdM)// links are already stored in CzechIdM, the changes of the accounts will be transferred to the entity in CzechIdM. 
 +  * Link does not exist, correlation attribute = `id`, action = Create link - This ensures that on repeated runs, all //accounts and entities// with the same `id` will be linked together. 
 +  * Entity does not exist, action = Create entity - This ensures that on every run, entities which did not exist in CzechIdM until then will be created according to the accounts on the system. 
 +  * Account does not exist, action = Ignore - We do not want to perform any action when an entity exists in IdM and the account does not. The system is only a source of data for us.
  
-  * Vazba existuje, akce = Aktualizovat entitu – Tím zajistíme, že při opakovaném běhu synchronizace, kdy jsou již v CzechIdM uloženy vazby //účet (koncový systém)// – //identita (CzechIdM),// budou přeneseny změny účtů do entity v CzechIdM +Leave the Workflow items empty - they are used for advanced scripting of the individual actions.
-  * Vazba neexistuje, korelační atribut = id, akce = Vytvořit vazbu – Tím zajistíme, že při opakovaných bězích se prolinkují všechny //účty a entity//, které mají stejné //id.// +
-  * Entita neexistuje, akce = vytvořit entitu - Tím zajistíme, že při všech bězích se nám v CzechIdM vytvoří entity, které tam do té doby neexistovaly, dle účtů na systému. +
-  * Účet neexistuje, akce = Ignorovat – Nechceme provádět žádnou akci, pokud existuje entita v IdM a účet neexistuje. Systém je pro nás pouze zdroj dat.+
  
-Položky Workflow necháme nevyplněny, ty slouží pro pokročilé skriptování u jednotlivých akcí.+On the Filter sub-tab, we do not set anything - we do not want to restrict the synchronization to only some accounts. The Logs tab is informative only and contains the audit log of the synchronization.
  
-Na podzáložce Filtr nenastavujeme nic, nechceme omezovat synchronizaci pouze na některé účty. A záložka Logy je pouze informativní a obsahuje auditní log synchronizace.+==== Starting the synchronization and the log ====
  
-==== Spuštění synchronizace a log ====+If we have successfully gone through the settings in the previous chapters, we can now proceed to starting the Synchronization itself. Go to the //Connected systems// tab, select our configured system and go to the Synchronization tab. Start the synchronization with the green triangle button at the end of the row with the synchronization configuration.
  
-Pokud jsme úspěšně prošli nastavením v předchozích kapitolách, můžeme nyní přistoupit ke spuštění samotné Synchronizace. Přejdeme na záložku //Napojené systémy//, vybereme náš nakonfigurovaný systém a přejdeme na záložku Synchronizace. Synchronizaci spustíme zeleným tlačítkem se znakem trojúhelníku na konci řádku s konfigurací synchronizace.+{{:Pictures/10000201000002C7000001BCD31C6120982EF7E6.png?604x376}}
  
-{{:Pictures/10000201000002C7000001BCD31C6120982EF7E6.png?604x376}}//Běžící synchronizace mají vyplněn sloupeček Běží//. Pokud přejdeme na detail běžící synchronizace (kliknutím na znak lupa) a poté přejdeme na záložku //Logy//, vidíme přehled všech synchronizací, včetně aktuálně běžících.+Running synchronizations have the //Running// column filled in. If you open the detail of a running synchronization (by clicking on the magnifier icon) and then go to the //Logs// tab, you can see an overview of all synchronizations, including the currently running ones.
  
  • by kopro