Systems - How to connect generic system

System connection configuration is initiated in the menu tab Systems. Above the list of current systems there is a button Add.

Click on it to connect new system. On the new system page one must provide some basic information:

• System name - naming of your choice
• Use remote connector server - Connectors are means of interface between CzechIdM and other systems. Connectors run in a connector server. A local server provided by CzechIdM directly is usually used. So this checkbox will be usually unticked. There are some exceptions for specific connectors that must run remotely. For example connectors which call commands locally on the connected system server and therefore must be placed there. Exchange connector, for instance, uses calling of PowerShell commands directly on a domain controller server in an AD domain.
• Password policy for validation and generation - see the chapter about password policies.
• Lower criticality of password policy for validation by role - If this checkbox is selected, the password validation will use the criticality level defined for the role instead of the system policy.
• Lower criticality of password policy for generating by role - If this checkbox is selected, the password generation will use the criticality level defined for the role instead of the system policy.
• Description – an optional description of the system. It is customary to describe the purpose of the connected system, for example: “HR system – loading of job positions and departments”.
• State – system states other than active:
  • Readonly - with provisioning queue – Systems marked in this way allow data reading only and are either source systems in CzechIdM or systems which are controlled but provisioning of data to them is intentionally prohibited for some time. In the latter case, all provisioned data is sent to the provisioning queue. The provisioning queue and history is displayed by: Systems → system detail (magnifying glass) → Provisioning. See the chapter Audit.
  • Readonly - without provisioning queue – Systems marked in this way allow data reading only. Provisioning operations are not saved into queue, cannot be executed again. IdM account is created only (uid attribute only).
  • Inactive - with provisioning queue - Inactive systems do not allow even reading operations. If provisioning to such a system is to take place, then the operations end up in a queue as in the case of Readonly systems.
  • Inactive - without provisioning queue - Inactive systems do not allow even reading operations. Provisioning operations are not saved into queue, cannot be executed again. IdM account is created only (uid attribute only).
• Asynchronous provisioning - if the provisioning is asynchronous for the system, all the data is stored in the queue and managed by appropriate scheduled task. Long running task ProvisioningQueueTaskExecutor operates above the queue periodically and starts CREATED provisioning operation processing. Make sure you have ProvisioningQueueTaskExecutor configured, if you have some target system switched to use asynchronous provisioning. This is recommended option, since it significantly improves responsiveness of the application.
• Block operations - Block (create, edit or delete) operation will block checked operation.

Subsequently, a connector, which will connect the selected system, needs to be chosen in the tab Configuration. The configuration setting of the system connection always differs according to the selected connector.

When the connector is configured, the green button Test Connector can be used to test to connection to real system.

The system of connectors provides connection to a system without the need to edit the administered system itself since their standardly provided interfaces are utilized.

The basic provided connectors are:

• Database Table Connector – connects a table in the database
• Scripted SQL Connector – connects any DB supporting JDBC.
• LDAP Connector – connects LDAP, even MS AD for some basic usage.
• CSVDirConnector – input/output from a CSV format text file

Other connectors can be added arbitrarily from publicly accessible sources (AD and Exchange connector), via own implementation or by inquiring of CzechIdM developers. Connectors use widely extended framework ConnId, formerly OpenICF, connector framework.

A scheme represents a list of attributes of some object (e.g. Account) in the connected system. By defining a scheme, CzechIdM is enabled to control management of object's attributes. The system scheme can be found in the tab Systems → System detail → Scheme .

The easiest and preferred way of how to create attributes scheme is to click the Generate scheme. Thus the attribute scheme is generated by the system's connector - all available attributes of the object are returned from the connector and can be modified by clicking on the object name in the table e.g. __ACCOUNT__.

The other option of defining scheme is clicking on the green Add button, define the object e.g. __ACCOUNT__ and then add attributes into the scheme manually one by one.

If editing (magnifying glass by the attribute name), or creating (green Add button) attributes in scheme, their names on the system and their data types need to be filled in.

Usual data types are

• java.lang.String
• java.lang.Integer

All allowed types based on connid FrameworkUtil

• String.class
• Long.class
• Character.class
• Double.class
• Float.class
• Integer.class
• Boolean.class
• Byte.class
• byte[].class
• BigDecimal.class
• BigInteger.class
• Map.class

Then, some of the following settings can be enabled for each attribute:

• Required - attributes marked in this way are always sent to the end system (provisioning) regardless of whether the value in CzechIdM has changed compared to the value on the end system. In some cases, the connector specifically requires marking of some attributes as required. If it is not required, however, it is not recommended to use this option due to network load.
• able to read - It is recommended to leave this option allowed. Uncheck this option to ensure compatibility with connectors which do not allow reading some attributes.
• multivalued - CzechIdM allows loading and provisioning of attributes containing more values at the same time. For example, the attribute Titles can be set to be filled in from 2 attributes from CzechIdM – TitleBefore, TitleAfter. The attribute Titles must be then marked as multivalued in the scheme of the connected system.
• able to create - this option is used mainly when the connected system is both a source and end system. If your system is only source or only end, it is recommended to leave this option allowed. In this case reading and writing of the attribute can be controlled by the system configuration itself (ReadOnly or Inactive systems).
• able to edit - dtto
• returned by default - TODO Vítek

When the attributes scheme for the object are ready, connected system attributes available in the scheme can be mapped onto CzechIdM entity attributes e.g. attributes of identity.

Attributes mapping is available at Systems → Mapping. If there is none use green Add button to create a new one.

• Operation type - Firstly, the purpose of mapping needs to be selected. There are two options:
  • synchronization (upload data to CzechIdM)
  • provisioning (propagation of data from CzechIdM)
• Mapping name - Next the name for the mapping must be provided. The name is consequently displayed in synchronization and provisioning configuration
• Object name - sets which object type on the connected system will be mapped to CzechIdM
• Entity type - defines the entity in CzechIdM to which the object from connected system is mapped. Usual values are: Identity, Role, Role Catalogue, Contracted position, Tree

When the attribute mapping is created and it is clear what object in the connected system is mapped to what entity in CzechIdM, the procedure gets to the object/entity attributes configuration.

Click on the Add button to create a new attribute in current mapping.

These options can be filled:

• Disabled - If the attribute is disabled in mapping, it is not provisioned or synchronized.
• Attribute in schema - attributes from the connected system available in the current scheme.
• Identifier - Attribute is unique identifier of this object.
• Entity attribute - Attribute is part of entity.
• Extended attribute - Attribute isn't part of entity and his value and name is stored in EAV attributes.
• Name - Unique system identifier, this value is used in select boxes and in entities info
• Strategy - defines the strategy for the provisioning or synchronization. Available values:
  • Set value as it is - no standard transformation takes place
  • Merge - for multivalued attributes. Provision current idm attribute values + values returned from the connected system. This strategy is often used when connecting e.g. MS AD and CzechIdM manages placing the users into groups, but not all groups are loaded in CzechIdM itself.
  • Authoritative merge - preferred strategy to fill multivalued attributes. Only CzechIdM values are sent to connected system. If the attribute originally contained other values, they are replaced by the sent one.
  • Write only on create of the entity - If checked, the attribute value is sent to end system only together with CREATE operation. If UPDATE is sent to connected system, this attribute is not sent again. The same states for the synchronization.
  • Write only if target value is null - If checked, only non existent attributes are filled in CzechIdM or connected system.

Other options of the mapped attribute are:

• Send always - Send this attribute to system always even if value isn't change (transformation rules is applied).
• Send IdM value only if its not null - Send this attribute only if value after transformation will not be null.
• Confidential attribute - Attribute value will be stored in confidential storage.
• Authentication attribute - With this attribute will be do authentication to end system (for example: username)
• Include on password change - Include this attribute when is provisioning password (reset, cahnge, create new)
• Include only when criticality is changed to stronger - The value of the attribute will only be sent to the target system when the aggregated password policy criticality is changed to stronger one. It will not be used in standard provisioning.
• Include only when criticality is changed to weaker - The value of the attribute will only be sent to the target system when the aggregated password policy criticality is changed to weaker one. It will not be used in standard provisioning.
• Attribute with password - Attribute will contain value of password. The attribute can't be override by role mapping. Into transformation will be add password in object GuardedString. Script must return null, or GuardedString.

It is now clear what attribute is managed on the connected system and how the changes are propagated from/to the attribute. Obviously it is necessary to define what attribute in CzechIdM we want to connect the end system attribute to.

• Entity field - attributes from CzechIdM entity can be selected. This selection is available only if Entity attr. is enabled.
• IdM key - name of attribute in IdM, if administrator choose Entity attribute is this field read only and his value is set by entity field select box. If administrator choose Extended attribute is this field available for write and is neccessary to enter name of extended attribute.

Now almost everything is set to synchronize or provision the attribute. If the range of standard options for attributes mapping is not wide enough, administrators can use transformation scripts to do advanced magic.

This is a way of how to manage systems via user tasks, not directly via direct (e.g. network) communication. This feature is mainly implemented as CzechIdM module.