Skip to main content
Skip table of contents

IWDS- Tips and Advanced configuration

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

How to use IWDS graphical interface in Linux environment

To execute IWDS application in Linux you can create a starting .sh script with the following commands:

CODE
#!/bin/bash
JAR="/APP/path/IWDS/Iwds.jar"
java -cp ${JAR} com.inwebo.gui.IwdsGuiStart

How to force IWDS to use TLS 1.2 in scripts

IWDS uses Java version 1.8 which natively supports TLS 1.2 and uses it by default, but in some environments cypher must be forced in Java to use TLS 1.2 at startup.

Scripts must include the additional option -Djdk.tls.client.protocols=TLSv1.2 -Dhttps.protocols=TLSv1.2 to be added in each java command line.

  • Example for Windows / PowerShell

POWERSHELL
$javaPath = "C:\java\openlogic-openjdk-jre-8u262-b10-win-64\bin\Java.exe"
Set-Alias java $javaPath
java -Djdk.tls.client.protocols=TLSv1.2 -Dhttps.protocols=TLSv1.2 -cp "C:\inWebo\Iwds.jar" com.inwebo.Iwds -b "C:\inWebo" -w "C:\IWDSsync\ConsoleAdmin.wsdl" -C "C:\inWebo\Certificate.p12" -p PASSWORD -v getinwebo
  • Example for Linux

CODE
java  -Djdk.tls.client.protocols=TLSv1.2 -Dhttps.protocols=TLSv1.2 -cp /product/inWebo/Iwds.jar com.inwebo.Iwds --ldap LDAP.PATH -v -b /product/inWebo getldap

How to use multiple IWDS app operating on a same service

This parameter is available in IWDS version 2.4 and higher.

The provisioning_id parameter specifies the user provisioning source. It is useful if you have multiple IWDS instances.

You can specify the provisioning source ID in the IWDS configuration file conf/inwebo.properties. The default value is 1.

When creating an account with API SOAP, the provisioning_id value can be specified in the loginCreateBySource API SOAP (see User Management with SOAP API - loginCreateBySource ). It will update the “Created By” value in IWDS.

To see the users provisioning sources from IWDS graphical interface, go to inWebo > InWebo Objects > inWebo Users tab. Look at the "Created by" column values:

  • Console → Created by the administration console (provisioning_id=0)

  • Source #1 → Created by IWDS (default value) (provisioning_id=1)

  • Source #{provisioning_idvalue} → Created by another provisioning source. (provisioning_id={value})

When you specify the provisioning_id, make sure that the value does not conflict with any other any other IWDS instance.

How to use service accounts or other users with IWDS on Windows

When switching between user accounts on Windows, the scripts or the IWDS application may experience difficulties. This situation occurs from time to time because the installation of IWDS is performed for a specific Windows user.

As part of a user change or for adapting to a Windows service account:

  • It is necessary to review the rights of the IWDS working directory as well as the “/out” and “/log” subdirectories (to make them accessible to this new account)

  • You must also delete (or copy in .OLD) the contents of these two directories which must have been created by launching IWDS from different Windows accounts

  • Do not place the IWDS directory in a Windows UAC managed directories like /program /program files and /Windows (which will add additional Adm controls)

Since this new account did not proceed with the installation in itself, it lacks the information of the location of the default directory present in the registry and which now must be specified for each Java command line of the script.

  • It is necessary to add on each of the IWDS command lines, the -B "working folder" option to specify the root of the IWDS working directory (or --basedir) IWDS - Command-line guide

The default IWDS directory is listed in the user profile registry with this line in the registry HKEY_CURRENT_USER\Software\JavaSoft\Prefs\com\inwebo\gui\utils\base_dir must be modified for the selected user (look for modify a other user registry loads HKU<username> C:\Users<username>\ntuser.dat)

How to upgrade IWDS

Here is the standard upgrade procedure for IWDS:

  1. Stop any IWDS synchronizations that may be running as Windows scheduled tasks or as cron jobs.

  2. Save your IWDS working folder and configuration items:

    1. First of all you must save your working directory → this is the parent directory that contains the configuration, log and synchronization files located themselves in the following 3 directories: ./conf; ./log; ./out. To locate your working directory, go to the top left hand side of the IWDS application ("File" menu > "Change working directory")

    2. Retrieve the certificate and its passphrase / for security (if necessary also take screenshots of LDAP accesses and group mapping) in case there is an incident during the update.

    3. If using a Virtual Machine with snapshots, take a snapshot thereby allowing you to rollback to a working configuration if necessary

  3. Uninstall and reinstall:

    1. Uninstall the previous version of IWDS, without removing your old folders (they should have been copied somewhere for safety)

    2. Reinstall the new version in the same location

  4. Check the configuration:

    1. IWDS should find the previous information from the "working directory" and automatically retrieve the configuration items. If however IWDS doesn't locate the working directory then indicate it via the "file" menu.

    2. Verify that all LDAP connections and group mappings are present.

    3. If everything is OK, perform a diff/sync operation to make sure IWDS is working correct

  5. Perform a diff/sync operation and make sure IWDS is correctly working.

  6. You can delete the back-up.

XML incompatibilities

Some version changes show XML incompatibilities with previous XML file formats located in the /out directory. If you encounter Character errors while parsing the XML files, rename your /out directory to /old and perform a new retrieve/diff/sync cycle.MaxValRange value for Microsoft 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).

  • 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.

Configuration and output file details

All configuration and output files are available in the IWDS working folder for scripting or debugging purposes.

Configuration Files

All these files are located in the “conf” subfolder of your IWDS configuration folder. Click to see the files settings description.

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.

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 “no”, managers configured in your TrustBuilder service will not be modified or deleted.

adminsynchro

Possible value: “yes” or “no”
If set to “no”, administrators configured in your TrustBuilder service will not be modified or deleted.

groupsynchro

Possible value: “yes” or “no”
If set to “no”, group memberships will not be handled during the “Sync”

resendactivationlink

Possible value: “yes” or “no”
If set to “yes”, pending users will be receive a new activation email.

sendcodebymail

Possible value: “yes”, “no” or “link”
If set to “yes”, newly created users will receive an email with an activation link. The email is sent by TrustBuilder servers.
If set to “link”, a long code with a three weeks lifetime is returned 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”, a 15 minutes lifetime activation code is returned 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”

deleteexpired

Possible value: “yes” or “no”

keepinwebostatus

Possible value: “yes” or “no”.
If a user was blocked by a Manager using the Admin Console, IWDS can let this status unchanged (“yes”), or set it back to the value taken from LDAP (“no”). Default is “yes”.

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>

Output Files

All these files are located in the “out” subfolder of your IWDS configuration folder.

inWebo user file

File name: inwebo.xml

Sample file

CODE
<?xml version="1.0"?>
<inwebo-users>
	<user>
		<id>148083</id>
		<login>john</login>
		<login2></login2>
		<status>0</status>
		<role>0</role>
		<firstname>John</firstname>
		<name>Doe</name>
		<mail></mail>
		<extrafields></extrafields>
		<code>ok</code>
		<createdby>1</createdby>
	</user>
	...
</inwebo-users>

The “status” field indicates whether authentication requests for this user are accepted or not. If status is set to 1, user is blocked. If set to 0, user is not blocked.

The “role” field indicates the role of the user in the service:

  • 0: User (basic TrustBuilder user)

  • 1: Manager of the service

  • 2: Administrator of the service

The “code” tells if the user is active, pending or expired.

Important: Logins having “code” field set to “expired” are not listed in this file. They appear in a separate file namely expired.xml. This file has the same structure as inwebo.xml file.

The “createdby” field tells if the user was last created or modified by the Admin Console or the API (e.g. IWDS). By default, IWDS does not delete users created by the Admin Console. Nevertheless, if a user is found both in TrustBuilder users and LDAP users, IWDS will update it. This means that, after next synchronization, the user will be seen as “created by the API”.

inWebo groupmembership file

File name: iwgroupmemberships.xml

Sample file

CODE
<?xml version="1.0"?>
<inwebo-group-memberships>
	<membership>
		<groupid>1</groupid>
		<groupname>HelpDesk</groupname>
		<loginid>148083</loginid>
		<login>john</login>
		<roleid>131</roleid>
		<rolename>operator<rolename>
	</membership>
	...
</inwebo-group-memberships>
inWebo group file

File name: iwgroups.xml

This file lists the user groups configured in your TrustBuilder service.

Sample file

CODE
<?xml version="1.0"?>
<inwebo-groups>
	<group>
		<groupid>1</groupid>
		<name>HelpDesk</name>
	</group>
	...
</inwebo-groups>
inWebo role file

File name: iwroles.xml

This file lists the custom user roles configured in your TrustBuilder service.

Sample file

CODE
<?xml version="1.0"?>
<inwebo-roles>
	<role>
		<roleid>131</roleid>
		<name>operator</name>
	</role>
	...
</inwebo-roles>
LDAP user file

If generated by the GUI, it is named <LDAP source name>_ldap.xml.

This file lists the LDAP users retrieved on a given LDAP server (source).

Sample file

CODE
<?xml version="1.0"?>
<ldap-users>
	<user>
		<login>john</login>
		<login2></login2>
		<status>0</status>
		<role>0</role>
		<firstname>John</firstname>
		<name>Doe</name>
		<mail>jdoe@client.com</mail>
		<extrafields></extrafields>
	</user>
	<user>
		<login>alice</login>
		<login2></login2>
		<status>0</status>
		<role>0</role>
		<firstname>Alice</firstname>
		<name>Nine</name>
		<mail>anine@client.com</mail>
		<extrafields></extrafields>
	</user>
	...
</ldap-users>
LDAP group membership file

If generated by the GUI, it is named <LDAP source name> _ldapgrpmb.xml.

This file lists the LDAP group memberships retrieved on a given LDAP server (source).

Sample file

CODE
<?xml version="1.0" encoding="iso-8859-1"?>
<ldap-group-memberships>
	<ldap-group-membership>
		<login>john</login>
		<ldap-groupname>HelpDesk</ldap-groupname>
	</ldap-group-membership>
	<ldap-group-membership>
		<login>alice</login>
		<ldap-groupname>HelpDesk</ldap-groupname>
	</ldap-group-membership>
	...
</ldap-group-memberships>
User Diff file

If generated by the GUI, it is named diff.xml.

This file lists the user transactions to be executed by the “Sync” action.

Sample file

CODE
<?xml version="1.0" encoding="iso-8859-1"?>
<transactions>
	<loginCreate>
	<transactionid>1</transactionid>
	<input>
		<login>alice</login>
		<login2></login2>
		<status>0</status>
		<role>0</role>
		<firstname>Alice</firstname>
		<name>Nine</name>
		<mail>anine@client.com</mail>
		<lang>en</lang>
		<extrafields></extrafields>
		<codetype>1</codetype>
	</input>
	</loginCreate>
	...
</transactions>

The “codetype” field indicates the chose method to send the activation code to the newly created TrustBuilder user (do not send code, send an activation code per email, send an activation link via email).

Group Diff file

If generated by the GUI, it is named diff_grp.xml.

This file lists the group membership transactions to be executed by the “Sync” action.

Sample file

CODE
<?xml version="1.0" encoding="iso-8859-1"?>
<transactions>
	<groupMembershipCreate>
		<transactionid>1</transactionid>
		<input>
			<loginid>0</loginid>
			<login>alice</login>
			<groupid>131</groupid>
			<groupname>HelpDesk</groupname>
			<roleid>131</roleid>
			<rolename>operator</rolename>
			<login-is-new>1</login-is-new>
		</input>
	</groupMembershipCreate>
	...
</transactions>
User Synchronization result file

Name of the file: result.xml.

This file lists the user transactions executed by the “Sync” action.

Sample file

CODE
<?xml version="1.0" encoding="iso-8859-1"?>
<transactions>
	<transaction>
		<transactionid>1</transactionid>
		<type>loginCreate</type>
		<input>
			<login>alice</login>
			<login2></login2>
			<status>0</status>
			<role>0</role>
			<firstname>Alice</firstname>
			<name>Nine</name>
			<mail>anine@client.com</mail>
			<extrafields></extrafields>
		</input>
		<output>
			<err>OK</err>
			<loginid>152993</loginid>
			<code>306664750</code>
		</output>
		<done>1</done>
		<timestamp>1415281897431</timestamp>
	</transaction>
	...
</transactions>
Group Membership synchronization result file

Name of the file: result_grp.xml.

This file lists the user transactions executed by the “Sync” action.

Sample file

CODE
<?xml version="1.0" encoding="iso-8859-1"?>
<transactions>
	<transaction>
		<transactionid>1</transactionid>
		<type>groupMembershipCreate</type>
		<input>
			<login>alice</login>
			<login2></login2>
			<loginid>152993</loginid>
			<login-is-new>1</login-is-new>
			<groupname>HelpDesk</groupname>
			<groupid>1</groupid>
			<rolename>operator</rolename>
			<roleid>131</roleid>
		</input>
		<output>
			<err>OK</err>
		</output>
		<done>1</done>
		<timestamp>1415281900133</timestamp>
	</transaction>
	...
</transactions>

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.