Configuring and Customizing DirX Audit History Synchronization Jobs

You can perform basic configuration operations like jobs scheduling and setting up DirX Audit History Database and DirX Identity domain connections in the DirX Audit Tenant Configuration Wizard. Each job can synchronize one or more entry types. See the section “Scheduled History Synchronization Jobs Configuration” in the DirX Audit Installation Guide for details.

This chapter describes how to perform advanced History Synchronization configuration and customization such as custom entry type configuration, entry type-specific attribute mapping, and advanced processing configuration by modifying the tenant-specific configuration.cfg file. See the next sections for details.

Navigating in the Tenant Properties File

There are two basic types of tenant configuration.cfg file:

The tenant default configuration.cfg file, which contains the default tenant configuration.
The default configuration may be changed by a DirX Audit Server update. You should never change this file, but you can check it to see the default DirX Audit History Synchronization configuration:
install_path/conf/defaults/tenant/configuration.cfg
The tenant-specific configuration.cfg file, which contains only modifications from the tenant default file and is never affected by a DirX Audit Server update. Each tenant has its own tenant-specific file, located at:
install_path/conf/tenants/tenant_id/configuration.cfg

If you have not modified any history synchronization settings either manually or via the configurator, you will not find a [historysync.*] section in your tenant-specific file. In this case, you should copy the relevant section from the default file and then modify it in your tenant-specific configuration – that is, if you want to customize your history synchronization settings for the specific tenant.

Both configuration.cfg files have the same structure. They are divided into sections. Each section starts with the section name enclosed in square brackets. Configuration under the section name belongs to the section. Some sections are divided into subsections. Section names are hierarchical with the following name conventions:

[<section_name>.<subsection_name>]

For example, the section dedicated to entry types has the following name:

[historysync.objects]

The file sections contain key-value pairs. Some keys or values are multi-value and separated by @. Some values can be lists. All lists of values are separated by commas and without spaces. If you define a list with no items, an empty list is passed as a parameter. Some values are optional and can be omitted.

You can use # at the beginning of the line to write a comment. For example:

#your comment

The tenant file contains two types of DirX Audit History entry attribute names for History Synchronization:

A DirX Identity attribute name, which is an existing DirX Identity domain attribute name (LDAP attribute). Use this attribute name only within the common attribute configuration section [historysync.attributes] for setting up the source attribute name and in lists of synchronized attributes within the entry type configuration [historysync.objects].
A DirX Audit History Database attribute name, which is used in the DirX Audit History Database. By default, it is the same name as the DirX Identity domain attribute name. You can customize it and use your own attribute name in the DirX Audit History Database that is unique within the tenant file. A DirX Identity attribute name is mapped to this name, and you must use this name in the configuration.cfg file for the rest of the History Synchronization configuration tasks.
For more details, see the section “Attribute-Specific Configuration” in this chapter.

The next sections describe the structure of the tenant-specific configuration.cfg file sections related to DirX Audit History Synchronization and how to modify them. If you want to modify a section, first check the tenant-specific file. If the section is already there, you can just change it to your desired configuration. If the section is missing, add it to the tenant-specific file together with all configuration key-value pairs from the tenant default file and then change them to your desired configuration.

Entry Type Configuration

The common entry type configuration is located in the subsection [historysync.objects]:

    [historysync.objects]
    attributes = *
    excluded_attributes =
     dxmVersion,dxrAssignmentDetails,dxrTBA,dxrVersion
    attr_values_ignore_case =

Configuration keys are:

attributes – The default list of synchronized DirX Identity domain attribute names. You can use the asterisk character (*) as a wildcard for all attributes available in the DirX Identity domain. Operational attributes are not automatically obtained from the DirX Identity domain. If you want to synchronize them, you must explicitly write them to this list. Normally, you do not need to change the default value. This value is used only for entry types without synchronized attributes definitions.
excluded_attributes – The default list of DirX Audit History Database attribute names excluded from the synchronization. This value is used only for entry types without excluded attribute names definitions. The excluded attributes take precedence over attributes.
attr_values_ignore_case – The default list of DirX Audit History Database attribute names of the common attributes whose values are case insensitive-compared during the attribute joining process. By default, attribute values are case sensitive-compared.

Subsections that define specific entry type configurations are named as follows:

[historysync.objects.<object_type_name>]

Specific History Synchronization entry type configuration sections are predefined for all standard DirX Identity domain entry types. You can add your own custom entry type if needed. All entry types share a similar configuration structure, as shown in the following example for the account entry type:

    [historysync.objects.account]
    name = Account
    hdb_name = Account
    ldap_search_base_prefix = cn=TargetSystems
    ldap_search_filter = (objectClass=dxrTargetSystemAccount)
    excluded_attributes =
    attributes =

Configuration keys are:

name – The name of the entry type that is shown in DirX Audit Tenant Configuration Wizard for the tenant.
hdb_name – The name of the entry type that is stored in DirX Audit History Database. Usually, it is the same value as name.
ldap_search_base_prefix – The LDAP search base RDN that defines the synchronized subtree of the DirX Identity domain. The RDN is automatically extended with the DirX Identity domain root entry; for example, cn=My-Company. The value is optional.
ldap_search_filter – The LDAP filter to restrict for the requested DirX Identity entries only. Usually, the objectClass attribute value is considered here. The value is optional.

excluded_attributes – The specific list of DirX Audit History Database attribute names excluded from the synchronization for the entry type. The value is optional. The excluded attributes take precedence over attributes.
attributes – The list of synchronized DirX Identity domain attribute names. You can use the asterisk character (*) as a wildcard for all attributes available in the DirX Identity domain. You can explicitly define only those attributes for the entry type that you want the History Synchronization job to process. The value is optional.

Attribute-Specific Configuration

Entry attributes are divided into three basic categories in the DirX Audit History Database:

Small attributes – attributes with attribute value lengths up to 850 characters.
Large attributes – attributes with attribute value lengths larger than 850 characters. Large attributes are not currently displayed in DirX Audit Manager and are therefore excluded from synchronization by default. You can change this behavior by changing the large attributes mapping. See the section “Customizing Attribute Mapping”.
Link attributes – links to other entries, represented as DN or RDN. The link length can also be up to 850 characters.

If you try to store attribute values greater than 850 characters to the small attributes database table, the value is automatically truncated to 850 characters and only the prefix of the value is stored. You can detect this situation in the DirX Audit Server log file and adjust the attribute mapping accordingly.

Common attribute-specific configuration is in the subsection [historysync.attributes].
The following example shows how a common attribute-specific configuration might look and illustrates which attribute name is an existing name of the attribute in DirX Identity and which attribute name is used in the DirX Audit History Database.

    [historysync.attributes]
    <large_attribute_database_name>@large =
    <large_attribute_identity_name>
    <small_attribute_database_name> = <small_attribute_identity_name>
    dxtTargetSystemLink@link = @virtual=exclusive@class=
    solutions.dirx.audit.historysync.modifydelimpl.configuration.
    attributeprocessors.MapToTs@categcat=DN@visibility=1

You can see that the configuration key consists of the DirX Audit History Database attribute name (for example, large_attribute_database_name) and an optional attribute mapping category (for example, @large). If there is no mapping category, the attribute is automatically mapped to the DirX Audit History Database small attributes table. The DirX Audit History Database attribute name is normally identical to the attribute name in the DirX Identity domain, but you can customize it according to your needs. It must be unique within the tenant configuration.cfg file.

The configuration value may consist of multiple parameters such as the attribute name from DirX Identity, attribute processing, and others. There are no special requirements on the order of the parameters; you must only put the attribute DirX Identity name first. If you are configuring a virtual attribute, which is created during the synchronization process and has no corresponding DirX Identity domain attribute name, your configuration value must start with the at sign (@). The structure of the configuration value with multiple parameters is:

<attribute_identity_name>@<optional_parameter_1>@<optional_parameter_n>

You can use the following parameter names (a vertical bar indicates the option choices):

virtual = common | exclusive – This parameter defines whether the virtual attribute is common or exclusive. If you are configuring a virtual attribute, you must omit the DirX Identity domain attribute name. Common virtual attributes are automatically created for all entry types. Exclusive virtual attributes are created only for selected entry types.
class = <fully_qualified_class_name> – This parameter specifies the fully qualified class name of the class processing attribute values. It is optional for non-virtual attributes and mandatory for virtual attributes.
category = DN | STRING | INTEGER | BINARY – This parameter defines the attribute’s category. This configuration is used by DirX Audit Manager to display the attribute correctly.
valueci – This parameter indicates that a case-insensitive compare of attribute values should be performed during the attribute joining process.
visibility = 1 | 0 – This parameter indicates to DirX Audit Manager whether the attribute value should be presented. 1 (visible) is the default value.

The tenant configuration.cfg file also contains entry type-specific attribute configurations. You can set up attribute mapping specifically for a selected entry type in the section that contains the entry type name in the configuration section name. For example, the entry type-specific attribute configuration for accounts looks like this:

    [historysync.attributes.account]
    dxtTargetSystemLink =
    dxtOrphaned =

The section defines mapping for two attributes. The dxtTargetSystemLink and dxtOrphaned are DirX Audit History Database virtual attribute names. These attributes are in the entry type-specific attribute configuration and therefore their values are calculated for all accounts during account entry type synchronization. The mapping is not defined here because the common mapping configuration is used. You can override it here if needed.

Configuring LDAP Schema Custom Data Types

If your DirX Identity domain uses custom attributes with a custom data type, you must configure this data type for DirX Audit. If it is not configured properly, you can find the following message in the DirX Audit Server log file: "There is no mapping for specified syntax id: …"

This message indicates a missing LDAP data type in the DirX Audit configuration.
You can fix it by modifying the file:

install_path/conf/historysync/ldapSyntaxTypes.properties

Add a new line to the end of the file and insert your custom data type in the following way:

1.3.12.2.1107.1.3.5.8=STRING

where:

1.3.12.2.1107.1.3.5.8 is the LDAP schema object identifier (OID) as available in DirX Directory.
STRING | DATE | BINARY | BOOLEAN is the data type name. Use BINARY for binary data.

Customizing DirX Audit History Synchronization

This section describes four methods for customizing DirX Audit History Synchronization:

Modifying, adding, and removing entry types from History Synchronization
Customizing attribute mapping
Excluding attributes from synchronization
Explicitly specifying attributes for synchronization

Modifying, Adding, and Removing an Entry Type from the Synchronization

To modify an existing entry type configuration, search the tenant configuration.cfg file for the corresponding section. For example, to modify the account entry type, search for the historysync.objects.account section.

    [historysync.objects.account]
    name = Account
    hdb_name = Account
    ldap_search_base_prefix = cn=TargetSystems
    ldap_search_filter = (objectClass=dxrTargetSystemAccount)

You can change values both for the ldap_search_base_prefix key and the ldap_search_filter key to restrict account entries to be synchronized from the DirX Identity domain. You can also extend the list of excluded attributes by adding the excluded_attributes key and a list of attribute names. Please consider that there are already several attribute names listed in the common configuration section historysync.objects.

Your DirX Identity domain may include one or more custom entry types that you need to synchronize into the DirX Audit History Database. To add your custom entry type, add the following section under the last entry type configuration section in your tenant configuration.cfg file:

[historysync.objects.<entrytypename>]
name = <EntryTypeName>
hdb_name = <HistoryDatabaseEntryTypeName>
ldap_search_base_prefix = <ldap-search-base-prefix>
ldap_search_filter = <ldap-search-filter>
excluded_attributes = <a-list-of-excluded-attributes>
attributes = <a-list-of-included-attributes>

You must define a tenant-unique entrytypename, a name, and an hdb_name. Specify the ldap_search_base_prefix as a relative distinguished name, not including the root DirX Identity domain object. Specify the ldap_search_filter to define a set of synchronized DirX Identity domain entries. You can also add lists of attributes to be excluded from and included in the synchronization.

To remove the existing entry type configuration, search the tenant configuration.cfg file and remove the corresponding configuration section.

Customizing Attribute Mapping

DirX Audit History Synchronization jobs synchronize DirX Identity entry attributes to three different tables in the DirX Audit History Database. Binary data and attributes with values longer than 850 characters should be stored in the large attributes table. Links to other DirX Identity entries should be stored in the link attributes table. The rest of the attributes are automatically mapped to the small attributes table.

If you want to set up attribute mapping, you can do it globally for all entry types within the tenant, or you can adjust mapping only for the specified entry type.

To change the attribute mapping globally, for all entry types, go to the tenant-specific configuration.cfg file and find the section:

[historysync.attributes]

Search for the attribute name within this section. If mapping for your attribute is already defined, you can just modify it. For example, to change mapping from the small attributes table to the large attributes table, change the original definition:

<attribute_database_name>@small = <attribute_identity_name>

to:

<attribute_database_name>@large = <attribute_identity_name>

If you cannot find the configured attribute within this section, add the following line to the end of the attributes section:

<attribute_database_name>@small = <attribute_identity_name>

where:

attribute_database_name is the attribute name in the DirX Audit History Database. You can use the same name as in DirX Identity or define your own attribute name.
attribute_identity_name is the attribute name as it appears in the DirX Identity LDAP schema.
small | link | large is the attribute mapping specifying the target database table.

To change the attribute mapping only for a specific entry type, search the tenant configuration file for the section:

[historysync.attributes.<specific_entry_type>]

where:

specific_entry_type – Name of the specific entry type.

If there is no such section, you must add it. Best practice is to include this section under the other sections for the entry type-specific attribute mapping.

The entry type-specific attribute configuration section must contain an attribute mapping configuration for your attribute. If there is no attribute mapping configuration within this section, add it. In this example, the attribute is mapped to the large attributes table:

<attribute_database_name> = large

If you are configuring virtual attributes, you must add the virtual attribute to the entry-specific attribute mapping even if you do not want to override the common attribute mapping. History Synchronization uses this information to generate virtual attributes for all entries related to the entry type. If you do not want to override the default virtual attribute mapping, you can leave the value empty. In this case, the common attribute mapping is used to map the virtual attribute:

<virtual_attribute_name> =

Excluding Attributes from the Synchronization

You can exclude an attribute from synchronization to the DirX Audit History Database. Excluded attributes are defined for entry types. You can also use the attribute mapping to exclude attributes.

To exclude an attribute by modifying the entry type, find the entry type section in the tenant configuration.cfg file. You can also define it in the default excluded attributes list, for example:

    [historysync.objects]
    excluded_attributes =
     dxmVersion,dxrAssignmentDetails,dxrTBA,dxrVersion

This list is overridden by the entry type-specific configuration. For example, for the following account entry type configuration:

    [historysync.objects.account]
    excluded_attributes = dxrTBA,dxrVersion

the default excluded attributes list is overridden because the account entry type has its own list of excluded attributes. To exclude the dxmVersion attribute, for example, from the account synchronization, modify the configuration as follows:

    [historysync.objects.account]
    excluded_attributes = dxmVersion,dxrTBA,dxrVersion

To exclude an attribute from the synchronization by modifying the attribute mapping, set the mapping value to excluded:

<attribute_database_name> = excluded

You can learn more about attribute mapping customization in the section “Customizing Attribute Mapping”.

Explicitly Specifying Attributes for the Synchronization

By default, DirX Audit History Synchronization jobs synchronize all available DirX Identity entry attributes for most of the predefined entry types. However, some attributes are excluded by default, which means that they are not stored in the DirX Audit History Database. There are two options to control which attribute is synchronized into the DirX Audit History Database:

Exclude the attribute from the synchronization – The attribute can be obtained from the DirX Identity domain by the DirX Audit History Synchronization job, but it is not stored in the DirX Audit History Database.
Define the entry type-specific list of synchronized attributes – Only attributes explicitly written to this list are obtained from DirX Identity domain by the DirX Audit History Synchronization job. These attributes can still be excluded and not stored in the DirX Audit History Database if they are set up as excluded attributes.

There are some entry types like User for which you want to synchronize only the explicitly-defined set of DirX Identity entry attributes; for example, to restrict the amount of audited personal data to the necessary minimum. You can extend the entry type configuration to define the synchronized DirX Identity entry attributes list as shown below:

    [historysync.objects.user]
    name = User
    hdb_name = User
    ldap_search_base_prefix =
    ldap_search_filter = (objectClass=dxrUser)
    # synchronized user attributes
    attributes = employeeNumber,sn,mail
    excluded_attributes =

In this example, only the DirX Identity employeeNumber, sn, mail attributes are read from the DirX Identity domain by the History Synchronization jobs and synchronized into the DirX Audit History Database.

Transferring Customizations from Old History Synchronization Workflows

The DirX Audit History Synchronization jobs use a similar default configuration as the legacy DirX Audit History synchronization workflows in DirX Audit 7.1. You can check the default tenant configuration.cfg file to see the default DirX Audit History Synchronization configuration:

install_path/DirX Audit/conf/defaults/tenant/configuration.cfg

If you used the legacy DirX Audit History synchronization workflows with a customization such as customer-specific entry types or customer-specific schema extensions, you must document the difference between your customization and the DirX Audit History synchronization workflows' default configuration and then apply it to the tenant-specific configuration.cfg file to add it as a customization of the new DirX Audit History Synchronization jobs. For details on how to apply your customizations to the DirX Audit History Synchronization jobs, see the section “Customizing DirX Audit History Synchronization” in this guide.

During the migration from DirX Audit version 7.1, the Configuration Wizard attempts to migrate all configuration automatically, so ideally, no further customer actions are required. However, it is recommended to check the new DirX Audit History Synchronization setting and compare it with the previous setting to ensure the same behavior.