{{tag> tutorial system synchronization database connector identity sync}}

====== Systems - DB: Source of identities ======

===== Basic configuration =====

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 <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 ====

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.

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.

Leave the other connector attributes empty or with their default pre-filled values.

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.

==== System schema ====

{{:Pictures/10000000000002F2000001899DDDD0CCFE8E5409.png?604x314}}

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.

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.

By clicking on the magnifier icon next to the attribute name, you can display the configuration details of the particular attribute.

{{:Pictures/100000000000017D0000023659372405B77FE7FF.png?380x565|Figure 22: Attribute detail in the system schema}}

In our case, all the attributes have the same configuration except for the `id` and <nowiki>__NAME__</nowiki> attributes, which are marked as required.

==== Synchronization mapping for the DB ====

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.

On the //Attribute mapping// tab, click on the <label type="success">Add</label> button and fill in:

  * 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.

{{:Pictures/10000000000002DA000000DD52F875E7D80B2EDD.png?580x175}}

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`.

{{:Pictures/10000000000001E30000019BC2AB56CA61594463.png?482x410}}

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:

  * //Is identifier// - checked only for `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 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`.

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.

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}}

==== 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}}

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.

Then proceed in the form to the settings of operations for the individual account and entity states and set them as follows:

  * 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.

Leave the Workflow items empty - they are used for advanced scripting of the individual actions.

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.

==== Starting the synchronization and the 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.

{{:Pictures/10000201000002C7000001BCD31C6120982EF7E6.png?604x376}}

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.