Installing and configuring on the Windows server

Before you begin

Time
The first synchronization might take a long time. For example, an Active Directory server with 500,000 users and groups can take 2 days. During that time, any changes that are made to the directory server are accumulated by the Active Directory server and are applied after the initial synchronization. Eventually, the Verify directory is updated at near real-time.
Process memory
The initial pass caches the mapping from Active Directory user and group IDs to the corresponding Verify-SCIM user and group IDs. This mapping requires 512 bytes per user, thus 500,000 users increases the memory usage by 244 MB.
Temporary file system storage
For IBM® Security Directory Server, the IcbLdapSync.exe application extracts a full copy of the directory (only relevant attributes are copied) into a local file. As an example, a directory with 500,000 users and groups might require 275 MB of temporary local disk space. This local file is encrypted.
Note: To run this program, you must have administrator privileges.

About this task

  • After the first synchronization is completed, a Windows event log is generated so that the administrator knows that all users and groups were created in the Verify-SCIM directory.
  • The replication state is stored in the file cookie.bin. This file must not be deleted. Deleting this file triggers a full replication to occur again.
  • The default configuration file adds all the users with:
    "realm":"cloudBridgeRealm"
"userCategory":"federated”
    This configuration can be changed as required. Ensure that all references to “cloudBridgeRealm” in the configuration file are updated if a change is made.
  • Use the -clean option to remove all synchronized users and groups from the Verify-SCIM directory, while it leaves the other entries untouched. This option removes cookie.bin and reads all the users and groups that would normally be synchronized and deletes them from the Verify directory.

Procedure

  1. Locate and Download the latest IBM Security Verify Bridge for Directory Sync application from the App Exchange.
    This application consists of a .zip file that contains the installer executable and a README.txt file that lists the changes to IBM Security Verify Bridge for Directory Sync.
    1. Go to https://exchange.xforce.ibmcloud.com/hub.
    2. Log in to the App Exchange.
    3. Search for IBM Security Bridge.
    4. Select IBM Security Verify Bridge for Directory Sync.
    5. Download the application.
  2. Extract the IBMSecurityVerifybridgeforDirectorySync_version.zip file on the target Windows system.
    Windows Visual Studio 2017 64-bit redistributable package must be installed before you install this product. This product cannot operate without it. If it is not already installed, it is installed when you run the setup_dirsync.exe file.
  3. Run setup_dirsync.exe.
    1. Double click setup_dirsync.exe.
    2. Select a language.
    3. Click Install.
      If Windows Visual Studio 2017 64-bit redistributable is installed by the wizard, you might need to restart your computer and rerun setup_dirsync.exe.
    4. On the InstallShield Wizard, click Next.
    5. Accept the terms and click Next.
    6. Select the installation directory and click Next.
    7. Click Install.
    8. Click Finish.
  4. Set up IcbLdapSync.json in the installation directory.
    • If you are synchronizing from ISDS LDAP, copy IcbLdapSync.json.isds-sample over the current IcbLdapSync.json file to provide a starting point.
    • For Active Directory, copy the IcbLdapSync.json.ad-sample file to the IcbLdapSync.json file to provide a suitable starting point for synchronization.
    Note: Before you make any changes to the IcbLdapSync.json file and run a directory synchronization, ensure that you are familiar with and review the attributes and values that are going to be synched to Verify.
    1. Set your ISDS or AD server LDAP connection settings under “cloud-bridge” -”ldap”.
      If you are using a TLS connection to the LDAP server, ensure that the signer certificates for the LDAP server are present in the Windows Certificate Store under Trusted RootCertification Authorities > Computer Account > Local computer. If your LDAP server is using a certificate that is not signed by a well-known CA, use the mmc command with the “certificate” snap-in.
    2. Set your Verify server connection settings under ibm-auth-api.
    3. Tweak other values like ldap-search-filter as required.
      The example AD filter skips all users and groups that have the isCriticalSystemObject attribute set. These users and groups are usually the computer accounts, system groups, guest accounts, and administrator accounts. The example ISDS filter looks for users with the person object class and for groups with the groupOfUniqueNames object class.
      Note:
      • The IcbLdapSync.exe process uses the Active Directory LDAP DirSync control. To have permission to use the DirSync control, the user account that runs IcbLdapSync.exe must have the directory get changes right assigned on the root of the partition that is being monitored. By default, this right is assigned to the administrator and LocalSystem accounts on domain controllers. The caller must also have the DS-Replication-Get-Changes extended control access right. For more information, see https://docs.microsoft.com/en-us/windows/win32/ad/polling-for-changes-using-the-dirsync-control.

      • For ISDS, the account that is used to access it must have permission to use the Paging control and permission to read the changelog entries.

      • The following permissions are required by the configured API client.
        • Manage users and standard groups
        • Synchronize users and groups
      • After synchronization begins, you cannot add or remove attributes from the configured attributes that are being synchronized. The product cannot retroactively adjust synchronized users and groups to match the attribute configuration change. Ensure that all the attributes that you need are configured before the first invocation.
  5. Add obfuscation to the IcbLdapSync.json configuration file secrets and password.
    As a general security practice, do not place clear text passwords and client secrets in the configuration file. Use the IBM obfuscation tool to obscure passwords and secrets.
    For example,
    C:\Program Files\IBM\DirectorySync>IcbLdapSync.exe -obf myadminpassword
OfFE5gNch3u5cJbeTj10Mm2Mbd1yS4eQjzqihj0lz7jGIG9fK7vNqTS90EmebtaU

    C:\Program Files\IBM\DirectorySync>IcbLdapSync.exe -obf myclientsecret
tiWLbtgcT1k+PP0IwWyXlKsdGnTE3dDJ15ZCvHzj9YY=
    Add the generated value to the IcbLdapSync.json file.
  6. Manually start the Windows Service.
    The IBM Security Verify Bridge for Directory Sync service runs the IcbLdapSync.exe process. After the service is operating correctly, you can change the service to start automatically. The first run can take a long time based on how many users and groups are being synchronized.