Identity Domain Connector

The service layer requires an object description name for creating an entry, so the request needs to contain attributes that allow the connector to select an object description. The best way to satisfy this requirement is to pass the object description name in the virtual attribute odName. For example, to create a functional user, take the odName dxrFunctionalUser. You’ll find the object descriptions with their names in the domain configuration tree.

As an alternative, you can provide the LDAP attributes that are sufficient to identify an object description. Normally, these attributes are objectclass and optionally dxrType. Check the <mapping> section of the object descriptions to determine the attributes that are evaluated by the service layer. For a functional user, you only need to provide the objectclass value dxrFunctionalUser.

If the given values are not sufficient to identify an object description, the connector checks whether the new entry should become a container. If an object class value contains the string container, the connector uses the object description name dxrContainer.

Only the object classes that are necessary to identify an object description need to be provided. If the request already contains an object description name, no object classes need to be provided; the service layer takes the missing object classes from the object description.

An entry must be created under another existing entry, the parent. The easiest way to satisfy this requirement is to provide the DN of the parent in the virtual attribute parentDN. If the add request contains an identifier DN, the Identity Domain connector extracts the parent DN from this attribute.

If a parent cannot be identified this way, the connector inspects the found object description and its parent descriptions. If the new entry is a user, role or permission, the connector takes the corresponding root entry.

If a parent still cannot be identified, the connector places the new entry under the business objects container.

If the creation of a new entry requires approval, the service layer starts the approval workflow. If the workflow is still in progress, the Identity Domain connector returns the result code PENDING and takes the entry identifier from the workflow’s subject identifier. Note that the entry DN may be changed in the remainder of the workflow.

The Identity Domain connector expects the password in the userPassword attribute. If the user or account is not in approval, it sets the password for the entry using the normal password support. Otherwise, it’s the workflow’s responsibility to define and set a password for a new user or account. With password support, the passwords are handled in the same way as, for example, with Web Center. Password support sends a password change event with the encrypted password. The workflow UserPasswordEventManager will process them in the standard way and update also corresponding accounts.

The connector does not use password support only if the suppressPwdEvent option is set to true; it simply stores the password in the entry’s user password attribute. In this case, in the object description the property type must be declared as “[B” (binary array).

A modify request should contain the DN of the entry in its ID and the old DN in the dxrprimarykeyold attribute; this configuration should be standard for all Provisioning workflows. This configuration allows the connector to detect a requested move of the entry. In this case, it asks the service layer to perform the rename and then applies other modifications.

Before the Identity Domain connector deletes an entry, it asks the service layer to delete all of its children. Typically, an entry will not be physically deleted, but set to state TBDEL (to be deleted).

The Identity Domain connector follows the standard rules for search requests:

References to other LDAP entries in attributes such as owner or dxrLocationLink must be given as LDAP DNs. Typically, the source databases will not recognize these DNs. Instead, they have a unique value, often something like a primary key. A mapping function needs to search the entry based on this unique value. An example of how to do this is given in the source for the role mapping function.

The Identity Domain connector provides special handling for privilege assignments.

For simple assignments, which do not have an end date or role parameters, it is sufficient to put the DN of the assigned role, permission or group into the respective attribute dxrRoleLink, dxrPermissionLink or dxrGroupLink.

For attributed assignments, the virtual attributes rolesassigned, permissionsassigned and groupsassigned must be used; they can also be used for simple assignments. The content of these attributes is a structured JSON object. Here is an example:

The example above contains new lines, tabs and blanks for better reading. Note that before you pass this value to the join engine of a Provisioning workflow, you should trim it; that is, remove all white spaces (blanks and tabs). This would matter if you provided the value in an LDIF or CSV file. Otherwise, the value would not exactly match the value that is returned from the connector and the join engine would always request the connector to modify the entry in LDAP. So, the better way is to have some channel filter component between the source connector and the join engine as in the sample workflow. This filter component should use the provided class PrivilegeAssignedDTO to generate the attribute value. For an example of how to do this, see the sources of the method addAssignmentAttribute(…​) in the filter class JdbcRoleAsgFilter; you’ll find it in the Additions folder of the product media.

In the request to the connector, the JSON object needs to contain the privilegeLink property with the DN of the privilege to assign. This is the minimum content and represents a simple assignment. An end date is expected in the dxrEndDate property; no start date is evaluated.

Role parameters are represented in the params array. They can have the DN of the parameter, its dxrUid and the key and value for the parameter value. A request must contain either the parameter UID or its DN in addition to the parameter value and value key.

The Identity Domain connector supports only one value per role parameter because the sequence of values cannot be determined in JSON. As a result, comparing mapped and actual existing values in the workflow might easily return the wrong result even when logically they are the same.

The Identity Domain connector returns only direct assignments in a search response; it does not return inherited and rule-based assignments. The result also contains assignments in approval. This helps to prevent duplicate request workflows, where an assignment is still in approval and the Provisioning workflow runs again.

The DN values of the privilege, a role parameter or even role parameter values are not usually present in a source database; instead, the source database contains only unique IDs. It’s the responsibility of filter and/or mapping functions in the Provisioning workflow to supply these DNs. For more information, see the section "Relational Database User Import Workflow" in the chapter "Using the Source Workflows" in the DirX Identity Application Development Guide.

The following add request contains the minimum set of attributes that are necessary for creating a user: