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.
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.
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:
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
actionRetrieve LDAP Objects with the
getldap
action
You will need agetldap
command line for each server you are querying.Make the difference with the
diff
actionSynchronize 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
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
-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:
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:
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 2nd 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
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
-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:
java -cp Iwds.jar com.inwebo.Iwds getldap
With arguments, using the –ldap option:
java -cp Iwds.jar com.inwebo.Iwds --ldap <LDAP source name> getldap
With arguments, using the –config option:
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”:
java -cp $JAR com.inwebo.Iwds -b $WorkingDir -c ldap_A.properties getldap
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 3rd step (out of 4) of the synchronization process. This computes the difference between TrustBuilder objects and LDAP objects.
Action
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
-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:
java -cp Iwds.jar com.inwebo.Iwds -r rules_<rule name>.properties diff
With more arguments, using the –ldap option:
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:
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":
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
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
-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:
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:
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.
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.
CODEjava -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.
CODE2022-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.
CODE2022-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.
CODE2022-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.
CODE2022-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>
 <transactionid>1</transactionid>
 <input>
 <loginid>xxxxx</loginid>
 <login>xxxxx</login>
 <login2>xxxxx</login2>
 <name>xxxxx</name>
 <firstname>xxxxx</firstname>
 <mail>xxxxx@xxxxx.xxx</mail>
 </input>
 </loginDelete>
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:CODEcd <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.