IWDS - Command-line guide

This document guides you to install and configure IWDS in command-line mode.

inWebo becomes TrustBuilder

We are currently rebranding all assets to the new TrustBuilder branding. Please bear with us while we change the branding of the inWebo interfaces and documentation to TrustBuilder. Functionality remains the same.

More details, planning and screenshots

Others IWDS topics:

Requirements

Operating System: Windows or Linux
Java JRE version 8 (TLS 1.2 default version)- use a JDK that includes Java JRE 8 - e.g.: OpenJDK, Oracle JDK, …
An TrustBuilder service configured
Download the last version of IWDS from Resources downloads. IWDS is shipped as an executable file.
Download Certificate from the Admin console (“Secure sites” > “Download a new certificate”). Choose the .p12 format.
For a standalone version of IWDS for scripting → to run script only you need the following files and folders in a specific IWDS “working directory”:
- The application files:
  - ConsoleAdmin.wsdl (WSDL file with TrustBuilder API call details)
  - IWDS.jar (Java binary of IWDS)
  - your TrustBuilder service .P12 certificate
  - your future IWDS script (*.bat, *.ps1, *.sh….)
- You need to create the following subfolder in your IWDS “working directory”
  - A /conf subfolder (where all configuration files are located)
    To create theses files (.properties) it is advised to run the application in graphical mode as it is easier to follow configuration steps.
  - Working directory /out subfolder (where output files will be located)
  - Working directory /logs subfolder (where log files will be located)

Configuration folders

Before performing a synchronization with IWDS, you must ensure that the connection between TrustBuilder and the LDAP source is properly configured. You have to set up the TrustBuilder parameters and the LDAP source parameters. You can also configure synchronization rules.

You can either perform configuration from the graphical interface or in command line.

The files to configure are located in the “conf” subfolder of your IWDS configuration folder. Click to see the files settings descriptions.

File “inwebo.properties”

Parameter name	Description
user_id	Must be equal to 0. Do not change
certificate_file	Path to the certificate file. You can get this file from Admin Console.
delay	Delay (in milliseconds) between 2 requests to TrustBuilder Servers. Do not change this parameter (delay=500)
max_size	Maximum number of users downloaded in one request. This parameter should be between 0 and 100. If you have more than 100 users, IWDS makes several requests sequentially.
provisioning_id	Define the provisioning source ID. It may be useful if you have multiple provisioning sources or several IWDS instances. The value must be greater than or equal to 1. If not specified, the default value is 1.

File “ldap.properties”

If generated by the GUI, this file is named ldap_<LDAP source name>.properties.

OpenLDAP specific settings

If using IWDS with OpenLDAP, you may encounter an exception when retrieving LDAP objects. To avoid this situation, uncheck the "Enable paging of LDAP queries" parameter in the "LDAP Search Parameters > Advanced parameters" panel, or manually set enableldappaging to no in the LDAP properties file.

Parameter name	Description
name	The name you give to your LDAP directory. Spaces are not allowed
authtype	LDAP authentication mode (Simple or anonymous)
host	IP address or Domain name of your LDAP directory
port	LDAP port. Usually 389
secure	yes / no. Whether to use LDAPS or not. The ‘port’ parameter is moved to 483 if you use LDAPS
ldapuser	LDAP user for connection purposes
ldappassword	LDAP password for the user mentioned above
basedn	Base DN to use for the LDAP connection
loginattr	LDAP attribute IWDS looks for to retrieve user login
login2attr	LDAP attribute IWDS looks for to retrieve user alternate login
firstnameattr	LDAP attribute IWDS looks for to retrieve user First Name
lastnameattr	LDAP attribute IWDS looks for to retrieve user Name
emailattr	LDAP attribute IWDS looks for to retrieve user Email
usergroupdn	LDAP DN of the group containing TrustBuilder Users
managergroupdn	LDAP DN of the group containing TrustBuilder Managers
admingroupdn	LDAP DN of the group containing TrustBuilder Administrators
searchbyattr	Tells IWDS to retrieve LDAP users in the groups your defined via a specific user attribute (typically the “memberOf” attribute on Active Directory)
searchattr	Sets attribute for user attribute based search
searchbygrpmb	Tells IWDS to directly retrieve the users that are members of the groups your defined
grpmbattr	Sets attribute for group membership based search
maxdepth	The number of sub-groups levels to parse recursively
filter_group	Sets the filter to apply on LDAP members to identify groups
filter_person	Sets the filter to apply on LDAP members to identify persons
useaduac	allows to use the UAC properties retrieved from an AD user to determine the user TrustBuilder account activation status
enableldappaging	Activation / Deactivation of LDAP paging
querypagesize	IWDS can use LDAP paging. This parameter sets how many users IWDS proceeds per page.
querydelay	Delay (in ms) between 2 LDAP page requests
filter	LDAP filter for your requests. Example : « objectClass\=Person », to filter out Computers (deprecated – replace by filter_person and filter_group)
recursegroups	Set to ‘False’ if you have Active Directory. ‘True’ otherwise (deprecated)
supportmemberof	Set to ‘True’ if you have Active Directory. ‘False’ otherwise (deprecated – replaced by searchbyattr)
grpattr	(deprecated – replace by grpmbattr)

Sample file

CODE

name=My LDAP
host=xxxx
port=3389
ldapuser=xxxx
ldappassword=xxxx
authtype=simple
secure=no
basedn=DC=adfs,DC=inwebo,DC=com
usergroupdn=cn=inwebo-users,CN=Users,DC=adfs,DC=inwebo,DC=com
managergroupdn=CN=inwebo-managers,CN=Users,DC=adfs,DC=inwebo,DC=com
admingroupdn=CN=inwebo-admins,CN=Users,DC=adfs,DC=inwebo,DC=com
firstnameattr=givenName
lastnameattr=sn
loginattr=samaccountname
login2attr=UPN
emailattr=mail
searchbygrpmb=true
grpmbattr=member
searchbyattr=false
searchattr=memberOf
maxdepth=10
filter_person=objectClass=Person
filter_group=objectClass=Group
useaduac=yes
enableldappaging=yes
querypagesize=100
querydelay=1000

“\\” are used to escape special chars. They are automatically added by IWDS GUI.

If a user belongs to the “User” group or "Manager" group, his “status” is set to “not blocked” during the synchronization. If not, it is set to “blocked”.
If a user belongs to “Administrator” group, his “role” is accordingly set during the synchronization and his “status” is set to “blocked”.

File “rules.properties”

If generated by the GUI, it is named rules_<rule set name>.properties.

Parameter name	Description
managersynchro	Possible value: “yes” or “no” If set to “yes”, TrustBuilder users with “Manager” role will be included at each synchronization operation.
adminsynchro	Possible value: “yes” or “no” If set to “yes”, TrustBuilder users with “Manager” role will be included at each synchronization operation. We suggest that you let the “Synchronize administrators” option unchecked to avoid any trouble accessing the administration console. See “Important recommendations” below
groupsynchro	Possible value: “yes” or “no” If set to “yes”, TrustBuilder Groups will be included at each synchronization operation.
resendactivationlink	Possible value: “yes” or “no” If set to “yes”, IWDS will send again an activation email for users with “Pending activation” status
sendcodebymail	Possible value: “yes”, “no” or “link” If set to “yes”, an email with an activation link is sent to users - Note that an email attribute must be filled out in the LDAP directory If set to “link”, generates a long code valid for 3 weeks by TrustBuilder servers per created user. These long codes can be used to create activation links. They are available in the XML output. If set to “no”, generates a 15 minutes lifetime activation code by TrustBuilder servers per user created. These codes can be directly used to activate any TrustBuilder authentication tool. They are available in the XML output.
lang	Possible value: “EN” or “FR” The language used to send emails
deleteexpired	Possible value: “yes” or “no” If set to “Yes”, IWDS will delete the users whose activation code has expired. Note that IWDS will recreate them if these users are still in the LDAP directory.
keepinwebostatus	Possible value: “yes” or “no”. Default is “yes”. If set to “yes”, if checked, any change of users status on the LDAP side (whatever their status, activated or not activated) will be reflected on the TrustBuilder side.

Group Mapping Configuration File

This XML file is used to map LDAP user groups to TrustBuilder user groups. It can be either generated in GUI mode using IWDS console or by any other mean, as long as the following file structure is respected.

The filename must have the following form:

ldapgroups_mapping_<LDAP source name>.properties.

A mapping file only associates one LDAP source groups to TrustBuilder groups.

If you have several LDAP sources configured, one mapping for each source is required.

Parameter name	Description
ldap-groupname	Name of the LDAP group as it appears in your LDAP directory. Case sensitive.
inwebo-groupname	Name of the TrustBuilder group as it appears in the iwgroups.xml file generated after getting TrustBuilder objects with IWDS or in the administration console
inwebo-groupid	ID of the TrustBuilder group as it appears in the iwgroups.xml file generated after getting TrustBuilder objects with IWDS or in the administration console
inwebo-rolename	Name of the TrustBuilder role as it appears in the iwroles.xml file generated after getting TrustBuilder objects with IWDS or in the administration console
inwebo-roleid	ID of the TrustBuilder role as it appears in the iwroles.xml file generated after getting TrustBuilder objects with IWDS or in the administration console

Sample file

CODE

<?xml version="1.0" encoding="iso-8859-1"?>
<ldap-group-mappings>
	<ldap-group-mapping>
		<ldap-groupname>HelpDesk</ldap-groupname>
		<inwebo-groupname>HelpDesk</inwebo-groupname>
		<inwebo-groupid>1</inwebo-groupid>
		<inwebo-rolename>operator</inwebo-rolename>
		<inwebo-roleid>131</inwebo-roleid>
	</ldap-group-mapping>
	...
</ldap-group-mappings>

About IWDS queries and batch script

Once the configuration is done, you can create the script that will perform automated synchronizations.

IWDS command line format

As IWDS is a .JAR java application, each IWDS command line is a Java query formatted as follows:

CODE

java -cp Iwds.jar com.inwebo.Iwds [[options]] [[action]]

The available actions are: getinwebo, getldap, diff, sync. The options for each of theses action are listed below.

Batch script composition

The batch script should follow the 4-step operation process of IWDS and will be composed with the following command line

Retrieve TrustBuilder Objects with the getinwebo action
Retrieve LDAP Objects with the getldap action
You will need a getldap command line for each server you are querying.
Make the difference with the diff action
Synchronize with the sync action, to send the list of operations to the TrustBuilder platform

As soon as you operate a complete synchronization, you should always start the 4 steps from the beginning, to take into account the last modifications of the previous synchronization.

If group synchronization is activated, it is mandatory to set the mapping between LDAP groups and TrustBuilder groups before computing the diff and synchronizing. If not set, IWDS is not able to determine which TrustBuilder group LDAP users should be added to. This mapping can be set either using IWDS GUI or by adding the appropriate file in the configuration directory (see Configuration File Format section below).

Command-line details

Retrieve TrustBuilder Objects → GETINWBEO
Retrieve LDAP Objects → GETLDAP
Make the difference → DIFF
Synchronize → SYNC

GETINWEBO

This is the 1st step (out of 4) of the synchronization process. This retrieves current TrustBuilder users from your service.

Action

CODE

getinwebo

After a successful retrieval on TrustBuilder servers, the result is saved to files located in the “out” subfolder of the configuration directory: the list of TrustBuilder users (inwebo.xml) and expired TrustBuilder users (expired.xml).

If group synchronization is activated, TrustBuilder group memberships, groups and custom roles are listed in 3 additional result files: iwgroupmemberships.xml, iwgroups.xml and iwroles.xml (located in the “out” subfolder of the configuration directory).

Options

CODE

-w, --wsdl                              WSDL file (full path to inWebo WSDL file)
-C, --cert                              inWebo API certificate (full path to certificate file - PKS12 format)
-p, --pass                              Certificate password
-b, --basedir                           Path of a directory containing out and conf subfolders- option
-c, --config                            inWebo Properties file name - option
-f, --find <logins|groups|roles|all>    Scope of inWebo search - option (if not specified set to "all")
-v, --verbose                           Print logs on system output - option

Command samples

With required arguments only:

CODE

java -cp Iwds.jar com.inwebo.Iwds --cert <path to your cert>/<your cert>.p12 --pass <your cert password> --wsdl ConsoleAdmin.wsdl getinwebo

With more arguments:

CODE

java -cp Iwds.jar com.inwebo.Iwds --config inwebo.properties --cert <path to your cert>/<your cert>.p12 --pass < your cert password > --wsdl ConsoleAdmin.wsdl –-find logins getinwebo

GETLDAP

This is the 2^nd step (out of 4) of the synchronization process. This retrieves target LDAP objects (users).
You will need a getldap command line for each LDAP server you are querying.

Action

CODE

Getldap

After a successful retrieval on your LDAP server, the result is saved to files.

A new panel is displayed. The first tab of this new panel displays the list of your LDAP users (objects are read from result files <LDAP source name>_ldap.xml located in the “out” subfolder of the configuration directory).

If group synchronization is activated, the LDAP group memberships are listed in a second panel (objects are read from result files <LDAP source name>_.xml located in the “out” subfolder of the configuration directory).

At this step, no modification is applied to your TrustBuilder service.

Options

CODE

-b, --basedir                     Path of a directory containing out and conf subfolders - option
-L, --ldap                        Name of an LDAP source - option
-c, --config                      LDAP Properties file name - option
-o, --out                         Destination file name - option (e.g. ldap.xml)
-f, --find <users|groups|all>     Scope of LDAP search - option (if not specified set to "all")
-v, --verbose                     Print logs on system output - option

The --ldap and --config (or -L and -c) options both allow to specify an LDAP source. The use of either option depends on the source format. Thus, you should not use the --ldap and --config options simultaneously to avoid any trouble.

Command samples

Without arguments. In this case IWDS uses the default LDAP source name and the current configuration directory:

CODE

java -cp Iwds.jar com.inwebo.Iwds getldap

With arguments, using the –ldap option:

CODE

java -cp Iwds.jar com.inwebo.Iwds --ldap <LDAP source name> getldap

With arguments, using the –config option:

CODE

java -cp Iwds.jar com.inwebo.Iwds --config ldap_<LDAP source name>.properties --out <LDAP source name>_ldap.xml --find users getldap

Multiple LDAP sources → In case of multiple LDAP sources, you should make one getldap request per LDAP source. For example, to read and retrieve users from LDAP source “A” and from LDAP source “B”:

CODE

java -cp $JAR com.inwebo.Iwds -b $WorkingDir -c ldap_A.properties getldap

CODE

java -cp $JAR com.inwebo.Iwds -b $WorkingDir -c ldap_B.properties getldap

Then, you should mention all the LDAP sources in the “diff” request (see “3. Make the difference” below).

DIFF

This is the 3^rd step (out of 4) of the synchronization process. This computes the difference between TrustBuilder objects and LDAP objects.

Action

CODE

diff

This command compares objects retrieved by getinwebo and getldap actions and computes a list of transactions to execute to synchronize your LDAP server(s) with TrustBuilder. This computation is based on a selected synchronization rule set and relies on the group mapping (if group synchronization is activated).

When executed, this command determines the list of TrustBuilder objects (users and user group memberships) to be created, updated and deleted. The “Diff” outputs the list of these transactions in XML files. These XML “Diff” files are later used by the “Sync” command that actually performs the synchronization. Note that you can change the name of the diff file.

The user related transaction are listed in the diff.xml file located in the “out” subfolder of the configuration directory.
If group synchronization is activated, the group membership related transactions are listed in the diff_grp.xml file, located in the “out” subfolder of the configuration directory.

The result consists in a list of transactions. A transaction can be of type:

TrustBuilder user create (loginCreate)
TrustBuilder user update (loginUpdate)
TrustBuilder user delete (loginDelete)
Add user to an TrustBuilder group (groupMembershipCreate)
Update user in an TrustBuilder group (groupMembershipUpdate)
Delete user from an TrustBuilder group (groupMembershipDelete)

Options

CODE

-r, --ruleset                       File containing diff rules
-L, --ldap                          Comma separated list of LDAP source names - option
-s, --source                        Comma separated list of LDAP user files - option
-b, --basedir                       Path of a directory containing out and conf subfolders - option
-I, --inwebo                        File containing inWebo users - option
-E, --inexpired                     File containing inWebo expired users - option
-o, --out                           Destination file - option (e.g. diff.xml)
-v, --verbose                       Print logs on system output - option

The --ldap and --source (or -L and -s) options allow to specify the source(s) from which LDAP objects are listed. The use of either option depends on the source format. Thus, you should not use the --ldap and --config options simultaneously to avoid any trouble.

Command samples

With required arguments only. In this case, only the rule set must be declared. The default LDAP source name is used as well as the latest LDAP and TrustBuilder object files found in the current “out” sub folder of IWDS directory:

CODE

java -cp Iwds.jar com.inwebo.Iwds -r rules_<rule name>.properties diff

With more arguments, using the –ldap option:

CODE

java -cp Iwds.jar com.inwebo.Iwds -r rules_<rule name>.properties --ldap <LDAP source name>[,<LDAP source name 2>,....] diff

With more arguments using the –source option:

CODE

java -cp Iwds.jar com.inwebo.Iwds -r rules_<rule name>.properties --source <LDAP source name>_ldap.xml[,<LDAP source name 2>_ldap.xml,....] --inwebo inwebo.xml --inexpired expired.xml --out diff.xml diff

Multiple LDAP sources → in case of multiple LDAP sources, you should enter all the LDAP sources in the diff request, separated by a comma. For example, to compare and generate the diff file for LDAP source "A" and from LDAP source "B":

CODE

java -cp $JAR com.inwebo.Iwds -b $WorkingDir -r rules_<rule name>.properties -s A_ldap.xml,B_ldap.xml diff

SYNC

This is the last step of the synchronization process. This sends the list of operations to your TrustBuilder service.

Action

CODE

sync

This action executes the transactions computed by the “Diff” command to synchronize your LDAP server(s) with your TrustBuilder service:

Loads “Diff” files
Connects to TrustBuilder servers
Executes transactions one by one
Captures the result

If synchronization is successful, the result of user related transactions is listed in result.xml file, located in the “out” subfolder of the configuration directory.
If group synchronization is activated, the result of group membership related transactions is listed in result_grp.xml file, located in the “out” subfolder of the configuration directory.

Options

CODE

-w, --wsdl                         WSDL file (full path to inWebo WSDL file)
-C, --cert                         inWebo API certificate (full path to certificate file - PKS12 format)
-p, --pass                         Certificate password
-b, --basedir                      Path of a directory containing out and conf subfolders - option
-c, --config                       Properties file - option (inWebo properties file name)
-i, --in                           Diff input file - option (file containing result of action diff)
-dl, --del-limit                   Max no. user delete operations allowed before stopping the sync - option (default 25 for IWDS 2.1.15 and above version)
-v, --verbose                      Print logs on system output - option

Delete operation

Be sure to follow our important recommendations to avoid future troubles during an LDAP incident or synchronization.

As of IWDS version 2.1.15, the -dl (or --del-limit) option is applied by default to 25. This means that the synchronization operation is blocked if it is about to delete more than 25 users. This option allows to avoid unwanted mass users deletion. To disable the limit, you should set the option to 0.

Command samples

With required arguments only:

CODE

java -cp Iwds.jar com.inwebo.Iwds --cert <path to your cert>/<your cert>.p12 --pass <your cert password> --wsdl ConsoleAdmin.wsdl sync

With more arguments:

CODE

java -cp Iwds.jar com.inwebo.Iwds --config inwebo.properties --cert <path to your cert>/<your cert>.p12 --pass <your cert password> --wsdl ConsoleAdmin.wsdl --in diff.xml --del-limit 30 sync

In batch mode, we recommend that you leave sync command line commented (REM) until you have verified that the synchronized data is correct. Commenting this line ensures that the script will query the TrustBuilder user database, read your LDAP and create the diff files but will not synchronize these changes to your TrustBuilder account.
Be sure to examine the diff.xml and diff_grp.xml files to ensure their content is correct before launching the synchronization operation.

CODE

REM java -cp% WKG_DIR% \ Iwds.jar com.inwebo.Iwds -b% WKG_DIR% \ -dl 10 -C <path to your cert> / <your cert> .p12 -p <yourcompetition> -w% WKG_DIR % \ ConsoleAdmin.wsdl sync

Batch script and schedule task

To automate the synchronization process, you should to create a batch file and configure a recurrent Scheduled task.
We are presenting you a way to create a batch file for Windows. Noten that the same Java command lines are also usable on Linux (.sh).

Create a batch file (.bat)

Open Notepad and save the file as ScheduledTask.bat.

Paste the following java commands. Make sure to customize the parameters according to your configuration.

CODE

java -cp "<Path to Iwds.jar including the file name>" com.inwebo.Iwds --cert "<Path to the .p12 certificate including the file name >" --pass <certificate password> --basedir "<Path of a directory containing out and conf subfolders>" --wsdl "<Path to ConsoleAdmin.wsdl including the file name> " --verbose getinwebo
java -cp "<Path to Iwds.jar including the file name>" com.inwebo.Iwds --basedir "<Path of a directory containing out and conf subfolders>" --config "<LDAP Properties file name>" --verbose getldap
java -cp "<Path to Iwds.jar including the file name>" com.inwebo.Iwds --ruleset "<File containing diff rules that is in the config folder – i.e. rules_Sync users only.properties>" –ldap "<Comma separated list of LDAP source names. Refer to the name value field in the ladp_Sync_XXX configuration file>" --basedir "<Path of a directory containing out and conf subfolders>" --out "<Destination file - e.g. diff.xml>" --verbose diff
java -cp "<Path to Iwds.jar including the file name>" com.inwebo.Iwds --cert "<Path to the .p12 certificate including the file name >" --pass <certificate password> --basedir "<Path of a directory containing out and conf subfolders>" --wsdl "<Path to ConsoleAdmin.wsdl including the file name>" --config "<set the Properties file name that is in the config folder e.g. ldap_Sync_XXX.properties>" --in "<Use the Destination file name define in the diff command above - e.g. diff.xml> --verbose sync

Please refer to the Synchronization section above for more information on the commands.
Note that the java and javaw tools start a Java™ application by starting a Java Runtime Environment and loading a specified class. The javaw command is identical to java, except that javaw has no associated console window. Use javaw when you do not want a command prompt window to be displayed. The javaw launcher displays a window with error information if it fails.

Save the file.

Test IWDS batch script

Test that everything works as expected:

Double-click on the ScheduledTask.bat file.
Open the log file that is located in the log subfolder

Check that you see the following lines (at the time of your test):

The connection to TrustBuilder database was successful, and the users/groups were uploaded.

CODE

2022-09-16T15:10:15,347 [INFO] com.inwebo.Iwds - Action getinwebo started.
2022-09-16T15:10:18,471 [INFO] com.inwebo.Iwds - Action getInWeboGroupMemberships completed
2022-09-16T15:10:18,471 [INFO] com.inwebo.Iwds - Action getinwebo end.

The connection to your LDAP database was successful, and the users/groups were uploaded.

CODE

2022-09-16T15:10:19,079 [INFO] com.inwebo.Iwds - Initializing LDAP Connection
2022-09-16T15:10:19,188 [INFO] com.inwebo.Iwds - Retrieving Manager group by blocks of -1
2022-09-16T15:10:19,235 [INFO] com.inwebo.Iwds - Retrieving User group by blocks of -1
2022-09-16T15:10:19,360 [INFO] com.inwebo.Iwds - Closing LDAP Connection
2022-09-16T15:10:19,376 [INFO] com.inwebo.Iwds - Action getldap end.

This shows that the TrustBuilder and LDAP users and groups were compared and the diff files for the synchronization were generated.

CODE

2022-09-16T15:10:19,942 [INFO] com.inwebo.Iwds - Action diff started...
2022-09-16T15:10:19,942 [INFO] com.inwebo.Iwds - Loading ruleset...
2022-09-16T15:10:19,942 [INFO] com.inwebo.Iwds - Loading LDAP users...
2022-09-16T15:10:20,005 [INFO] com.inwebo.Iwds - Loading InWebo users...
2022-09-16T15:10:20,005 [INFO] com.inwebo.Iwds - 5 inWebo users loaded.
2022-09-16T15:10:20,005 [INFO] com.inwebo.Iwds - 0 inWebo expired users loaded.
2022-09-16T15:10:20,005 [INFO] com.inwebo.Iwds - Loading inWebo group memberships...
2022-09-16T15:10:20,005 [INFO] com.inwebo.Iwds - 4 inWebo group memberships loaded.
2022-09-16T15:10:20,005 [INFO] com.inwebo.Iwds - --- Starting inWebo users DIFF ---
2022-09-16T15:10:20,051 [INFO] com.inwebo.Iwds - --- Ending inWebo users DIFF ---
2022-09-16T15:10:20,051 [INFO] com.inwebo.Iwds - --- Ending inWebo group memberships DIFF ---
2022-09-16T15:10:20,051 [INFO] com.inwebo.Iwds - Action diff finished successfully

This shows that the users and groups synchronization was successful.

CODE

2022-09-16T15:10:21,272 [INFO] com.inwebo.Iwds - Action sync started.
2022-09-16T15:10:22,225 [INFO] com.inwebo.Iwds - --- Starting inWebo users SYNC ---
2022-09-16T15:10:22,553 [INFO] com.inwebo.Iwds - --- Ending inWebo users SYNC ---
2022-09-16T15:10:22,553 [INFO] com.inwebo.Iwds - --- Starting inWebo group membership SYNC ---
2022-09-16T15:10:22,553 [INFO] com.inwebo.Iwds - --- Ending inWebo group membership SYNC ---
2022-09-16T15:10:22,553 [INFO] com.inwebo.Iwds - Action sync finished successfully

Configure a scheduled task

Go to the Control panel > System and Security >Scheduled Tasks
In the Task Scheduler, click on Create Basic Task.
The Create Basic Task Wizard appears. Enter a Name and a description for the task. Then Click Next.
Select the interval that you want to use for this task (for example, daily, weekly, monthly, or one time only). Click Next.
If you choose to schedule the task daily, weekly, monthly, or one time only, you receive a time or date option. Select the date (or dates) and the time (or times) that you want to schedule the task for, and then click Next.
Select Start a program, then click Next.
Select the .bat file corresponding to your batch and click Next. If you are using the bat files provided by TrustBuilder, make sur to select ScheduledTask.bat file.
Check the Summary page and Click Finish to schedule the task.
The task should now appear in the Task Scheduler Library.
Test via the scheduled task that everything works. You can force its execution on demand by right-clicking and "Run".

If you want to have more control on the scheduled task, we advise to schedule it via Create Task… option. This option enables more control such as running a task with a Service account, running it in background without having the user logged on, etc ...

Important recommendations

The recommendations are the same as the Graphical Interface documentation and we advise you to use it to create your configuration files first.

MaxValRange value for Microsoft AD

In Active Directory the MaxValRange value, limits the maximum number of values Active Directory can answer to a request, in our case, this refers to the number of logins. Default is set to 1500.

If you have to retrieve more than 1500 users Active directory will return no users but also no errors, as a result all theses users will disappears from IWDS and may be wiped from the TrustBuilder platform in the next synchronization.
It is recommended you verify this value when synchronizing above 1000 users, you can verify and change this value using NTDSUTIL.
It may be necessary to modify this value with the command NTDSUTIL and to increase it to 5000.
There is a known workaround using "MemberOf" and selecting a "search by user attribute", this allows IWDS to work and retrieve all Active Directory users without changing the "MaxValRange" value. Use with caution, as there is no clear indications why the search method only affects Active Directory results in this way.

Mail creation and blacklisting

Before creating a user, and sending the activation email, please be sure to have created the user mail address. Facing an unknown address, this email will be blacklisted for 30 days by our SMTP/mail service provider

Delete operation

In graphical mode, the synchronization operation is blocked if it is about to delete more than 25 users. You will be prompted to use command line mode to avoid unwanted mass users deletion.
In command line mode, if you want to force the “Sync” operation that is deleting more than 25 users, you should:

Check that the list of users to be deleted is correct and not the result of an error or an erroneous behavior of the directory.

To do this, after a "diff" operation, consult the file '<IWDS_installation_directory>\work\out\diff.xml ' , and check the list of the 'loginDelete' type transactions:

CODE

<loginDelete>&#xd;
		<transactionid>1</transactionid>&#xd;
		<input>&#xd;
				<loginid>xxxxx</loginid>&#xd;
				<login>xxxxx</login>&#xd;
				<login2>xxxxx</login2>&#xd;
				<name>xxxxx</name>&#xd;
				<firstname>xxxxx</firstname>&#xd;
				<mail>xxxxx@xxxxx.xxx</mail>&#xd;
		</input>&#xd;
</loginDelete>&#xd;

Execute the “Sync” action specifying the --del-limit parameter. This parameter defines the maximum number of users that can be deleted during the operation. ( See Action “sync” > “-dl, --del-limit" option). For example, if you set the limit to 50 users, this means that any sync operation deleting more than 50 users will be blocked. Here is the command line example for a sync action set with a 50 users delete limit:
CODE
```
cd <IWDS installation directory>
java -cp Iwds.jar com.inwebo.Iwds --del-limit 100 --cert <certificate file name>.p12 --pass <Certificate password> --wsdl ConsoleAdmin.wsdl sync
```

Please, note that the default value of the -dl, --del-limit option is 25.

In batch mode, we recommend that you leave sync command line commented (REM) until you have verified that the synchronized data is correct. Commenting this line ensures that the script will query the TrustBuilder user database, read your LDAP and create the diff files but will not synchronize these changes to your TrustBuilder account.

Be sure to examine the diff.xml and diff_grp.xml files to ensure their content is correct before launching the synchronization operation.

Best practices

Manage TrustBuilder administrators

To avoid any trouble accessing the administration console, we suggest you to manually manage the TrustBuilder administrators from the administration console instead of using IWDS.

LDAP migration or change

When changing the structure of your LDAP we recommend momentarily stopping IWDS synchronization. During the migration or change of your LDAP groups/UO/Forest it is preferable to use the TrustBuilder administration console for user provisioning. When restarting the synchronization be careful not to operate it immediately and verify that the users won't be deleted as a result of a faulty LDAP configuration.

If IWDS can't access your LDAP or if the synchronized security group has been moved or emptied, IWDS will consider theses users removed and will delete the corresponding accounts from the TrustBuilder platform.

IWDS Scripts samples

Samples of IWDS scripts for Windows (.bat, ps1) and for Linux (.sh) are available. Please contact TrustBuilder Support for more information.