The cloud-bridge JSON object

The configuration file for the cloud-bridge JSON object uses the following attributes and definitions.

Option entries and, if optional, the default values

"ldap-search-filter"

Used to select which user and group entries in Active Directory are to be replicated to the Verify-SCIM directory. This parameter must be provided. This value must not be changed between two runs of IcbLdapSync.exe such that the matching entry result set changes. The filter cannot reference attributes that change during the lifetime of each entry in the result set that includes the referenced attribute. The referenced attributes must exist when the entry to be synchronized is created, thus for user entries do not use group membership attributes such as memberOf for Active Directory, or ibm-allGroups for IBM® Security Directory Server as these are not set when user entries are initially created.

"user-sync-filter"

This option allows users to be created or deleted dynamically in Verify Cloud Directory if their corresponding AD or LDAP user entry does or does not match the filter logic. Set this option for the first synchronization only. Do not change it afterward because it does not automatically correct the existing user set to the new matching set of users. If this option must be changed after the first synchronization, the Directory Sync service must be stopped. Then, run the program one time manually as an administrator. Use IcbLdapSync -rebuild in the installation directory to readjust the matching set of users that are actively synchronized.

If this option is not used, then after the first setup pass a user is created or deleted in Verify Cloud Directory only when the corresponding AD or LDAP user is created or deleted. It occurs only when the created user in AD or LDAP matched the ldap-search-filter. If the user is not created in Verify Cloud Directory, then Directory Sync always ignores the user. Even if later the existing AD or LDAP user were modified to match the ldap-search-filter, Directory Sync still ignores it. This behavior is significant to administrators, who want to synchronize users based on group membership. When users in AD or LDAP are created, they are not a member of any groups. Therefore, they never match the ldap-search-filter at creation, and are not created and synchronized.

With this user-sync-filter option, if an AD or LDAP user is modified to match the user-sync-filter, Directory Sync fetches the user's current details from AD or LDAP. If the user doesn't exist, it creates the corresponding user in Verify Cloud Directory. The user is kept synchronized with AD or LDAP. When an AD or LDAP user is modified so that it no longer matches the user-sync-filter, if the user exists, Directory Sync deletes the user from the Verify Cloud Directory.

User creation and deletion based on the user-sync-filter match occurs dynamically. Directory Sync monitors the changes to attributes and groups that are referenced in the filter and reevaluates the filter for the associated users.

The ldap-search-filter, ldap-base-dn, and ignore-suffixes options are still in effect. So they must be set sufficiently broad enough to cover all users that are monitored by the user-sync-filter.

The option do-not-sync-delete does not apply to user-sync-filter deletions. However, it does apply to any user deletions that are reported by AD or LDAP.

The format of user-sync-filter is a subset of the LDAP search filter specification. This filter is never passed on to LDAP or AD. Directory Sync evaluates the filter internally as it notices changes to attributes and groups that are referenced in the filter. This filter does not support the LDAP filter operations >=, <=, most extensible matching rules, and substring. Attribute names cannot use OIDs.

Only the following extensible matching rules are supported for user-sync-filter.

Capability name	OID
LDAP_MATCHING_RULE_BIT_AND	1.2.840.113556.1.4.803
LDAP_MATCHING_RULE_BIT_OR	1.2.840.113556.1.4.804

ABNF notation:

        filter     = "(" filtercomp ")"
        filtercomp = and / or / not / item
        and        = "&" filterlist
        or         = "|" filterlist
        not        = "!" filter
        filterlist = 1*filter
        item       = simple / present
        simple     = attr equal value
        equal      = "="
        present    = attr "=*"
        attr       = [ "memberOf" | "ibm-allGroups" ] / attributename
        value      = escapedText
        
The evaluation of "equal" is a case insensitive string match.

If a value should contain any of the following characters

           Character       ASCII value
           ---------------------------
           *               0x2a
           (               0x28
           )               0x29
           \               0x5c
           NUL             0x00

the character must be encoded as the backslash '\' character (ASCII
0x5c) followed by the two hexadecimal digits representing the ASCII
value of the encoded character. The case of the two hexadecimal
digits is not significant.

Other characters besides the ones listed above may be escaped using
this mechanism, for example, non-printing characters.

Note:

Pay particular attention to the use of \ inside the JSON value, it needs to be doubled, \\, because it is an escape character that is used by JSON.
The NUL (0x00) character is not supported and only the characters in the value before the NUL are used.
Nested group matching on AD is not supported.
Only use memberOf for group membership checking on AD and AD-LDS.
Only use ibm-allGroups for group membership checking on IBM Verify Directory.

In the following user-sync-filter example, the administrator chose that a user must have the attribute department with the value abcd123 and (&) be a member of the group "testgroupX". The group is specified by using its Distinguished Name (DN):

"user-sync-filter": "(&(department=abcd123)(memberOf=CN=testgroupX,CN=Users,DC=mydom,DC=com))",

"ldap-base-dn"

All replicated users and groups must have this DN as their parent, otherwise they are ignored. For AD, this value defaults to the defaultNamingContext value. For ISDS LDAP, this value defaults to the first non-system namingContexts value. This value cannot be changed between two runs of IcbLdapSync.exe such that the matching entry result set changes.

"ignore-suffixes"

This attributes identifies an array of Distinguished Names (DNs) in the source LDAP. The child entries, including self, under each of these DNs is ignored and not synchronized. The default value is []. Another example is

[ “cn=branch1,o=ibm,c=us”, “cn=branch3,o=ibm,c=us” ]

"ldap-external-id-attr"

This attribute is used to uniquely identify an Active Directory entry. The attribute is stored in the Verify-SCIM directory to maintain a connection between the two registries for the particular entry. This attribute must not be modified from the value that is provided in the sample files for each specific Active Directory server.

"ldap-dn-to-ascii-lower":false

If set to true, then all Active Directory DN values have the characters ‘A’→‘Z’ converted to ‘a’→‘z’ per English lowercase folding. No other UTF-8 characters are modified. This attribute is primarily used with ISDS synchronization as DN values are used to connect Active Directory entities to Verify-SCIM entities. This conversion might cause issues in other locales such as Turkish with its "I"-to-"i" folding. It also might not be sufficient, if multiple DN attributes that refer to the same Active Directory entry, have character case differences with characters outside ‘A’→’Z’.

“trace-file”

If set, this attribute enables tracing of the IBM Auth API operations (SCIM JSON operations) and Active Directory operations into a file. The file does not roll over and is not limited in size by the IcbLdapSync.exe application. Ensure that it does not use too much of the file system resources.

“ldap-poll-time”:4

This attribute determines how frequently IcbLdapSync.exe runs a directory search operation on the LDAP server to find new changes that are made to the directory users and groups. The value is set in seconds. The default setting is 4 seconds.

"enable-op-log":false

If set to true, this attribute enables the logging of each POST, PUT, PATCH, and DELETE operation that is made to Verify-SCIM directory users and groups. POST == create, PUT == update full object,

PATCH
== modify attribute[s] of object

, DELETE = delete entry. The file format consists of lines of operations, each line contains comma-separated values of:

{utc-date},{operation},{ldap-dn},{Verify-scim-id},{status}

For example:

"Mon Jun 24 20:33:24 2019","POST","cn=testuser,o=ibm","600000GF7B","201" 
"Mon Jun 24 20:33:55 2019","PATCH","cn=testuser,o=ibm","600000GF7B","204"

The {utc-date} is the time when the operation is started. The completion time is not recorded.

"op-log-file": “{install-directory} [/{instance}]/op_log/op_log.csv”

The name of the file to log Verify-SCIM operations into.

Note: “{install-directory}”, and “{instance}” are variables. These variables represent the installation directory path and optional instance name of the application for this description.

"op-log-rollover":2097152

The approximate maximum size of the op_log file before it is rolled over. When rollover occurs, the op_log file is renamed by appending the current UTCtimestamp in decimal seconds to its name. Subsequent operations are then logged in to a new op_log file.

Note: Due to multi-threading, the date order might not be preserved for entries in this file.

"cookie-file": “{install-directory} [/{instance}]/cookie.bin

The file to store the replication state cookie into. This attribute allows the application to be restarted and still maintain where it is up to with replication. A “.bkp” of the cookie is made each time that a new state is reached.

Note: “{install-directory}”, and “{instance}” are variables. They are not valid values to use. These values represent the installation directory path and optional instance name of the application for this description.

"ldap-conn-idle-timeout": 30

If the directory connection is left unused for longer than this amount of time, then it is closed the next time that it is requested. A new directory connection is created. This attribute is used to avoid timeouts with firewalls.

"ldap-conn-max-timeout": 300

The maximum time that a directory connection is used for before it is closed and a fresh connection is made. This attribute is used to avoid configured limits for connections with the directory server.

"nested-groups" : false

Disables or enables support for groups as members of groups. If set to true, group members that are groups are recognized and replicated to Cloud directory. If set to false, they are ignored.

"status-port" : 1234

If set in the configuration file, this entry enables the IcbLdapSync.exe process to listen on the specified port for connections on the loopback interface (EG 127.0.0.1). After a connection is made, any event log entries are sent out on the connection.

"ldap-use-paging" : false

Disables or enables the use of LDAP paging control. The use of the LDAP paging control allows for larger search return sets. However, it might be a limited resource and require special permissions by the LDAP directory. A large search return set it typical for the first pass if the directory is large.

"do-not-sync-delete" : false

If set to true, the delete operations are not synchronized from the LDAP directory to the Cloud directory.

"scim-threads": 1

This attribute is optional. If not specified, the default is set to 1. This performance option allows multiple LDAP changes to be applied to the Cloud Directory in parallel, but only if the operations are to unrelated entries. A few parallel operations allow greater throughput of changes to Cloud Directory. Do not use this option with earlier versions of the product.

"do-not-sync-groups": false

This attribute is optional. If not specified, the default is set to false. If set to true, then Directory Sync does not synchronize group objects.

"changelog-size-limit": 300

This attribute is optional. If not specified, the default is set to 300. For IBM Security Directory Server only. When Directory Sync is searching for changelog entries, it limits the number of entries that are fetched in each pass.

"ci-retries": 12

This attribute is optional. If not specified, the default is set to 12. When Directory Sync applies the changes to the Cloud Directory, it uses the Cloud Directory SCIM REST interface. If a failure occurs when starting a SCIM REST call, then Directory Sync retries the operation up to "ci-retries" times in an attempt to overcome temporary failures. Setting this value to 0 disable retries. Retries occur for all HTTP 5xx errors and select HTTP 4xx errors, but only if the response body does not have content-type of "application/scim+json", and when the connection to the SCIM REST endpoint cannot be created or completed.

"ci-retry-pause": 5

This attribute is optional. If not specified, the default is set to 5. This attribute specifies the number of seconds that Directory Sync waits between retries on failed SCIM REST calls. Valid values are in the range 1 - 100. Values outside this range are automatically be clipped to this range.

"end-on-ci-retry-failure": false

This attribute is optional. If not specified, the default is set to false. If this option is set to true, then the Directory Sync process ends after the first unrecoverable error.

"end-on-seq-failures": 0

This attribute is optional. If not specified, the default is set to 0. If this option is set to a value greater than 0, it causes the Directory Sync process to end after the execution of the specified number of unrecoverable errors without intervening successful operations.

"changelog-ignore-suffixes": [ "ou=other1,o=ibm,c=us", "ou=other2,o=ibm,c=us" ]

This attribute is optional. If not specified, the default is set to an empty array. For IBM Security Directory Server only. This performance option allows Directory Sync to immediately ignore changelog entries that have a targetdn that is a child of subchild of any of the specified suffixes. Changelog entries typically do not have the objectClass attribute present. Directory Sync must search the Cloud Directory to determine whether a matching synchronized entry for the change exists. If the change is not for a Cloud Directory synchronized entry, the search reduces performance. If these searches are avoided for significant branches of the IBM Security Directory Server directory tree that have non-synchronized entries, performance can be improved.

"trace-rollover": 0

This attribute is optional. If not specified, the default is set to 0. If the value is set to 0 bytes, then the "trace-file" does not roll-over and continuously grows with Directory Sync activity. If set to a value greater than 0, when a block of trace causes the file to exceed the value, then the trace file is renamed and a new trace file is started. The current UNIX timestamp value is added to the renamed, rolled-over trace file.

"op-log-add-skipped": false

This attribute is optional. If not specified, the default is set to false. If Directory sync determines that an LDAP change is not relevant to the synchronization, then it skips it without record. If this option is set to true, it outputs an entry into the op_log with the relevant LDAP DN so that administrators can monitor operations that are skipped.

"log-stats-interval": 0

The default setting is 0 seconds. If set to an integer greater than 0, it enables a feature to periodically log Info level events in the Windows Event Log each interval with some operational statistics. The events are in the following form.

LE=%1 CE=%2 CU=%3 CG=%4 MU=%5 MG=%6 DU=%7 DG=%8

Where

LE=Number of AD/LDAP Errors
CE=Number of Verify API errors (communication to tenant)
CU=Number of User creates
CG=Number of Group creates
MU=Number of Modify user operations
MG=Number of Modify group operations
DU=Number of Delete user operations
DG=Number of Delete group operations