IWDS - Graphical Interface guide

This document guides you to install and configure IWDS with the graphical interface (Windows application).

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

Other IWDS topics:

• Basics about Directory Sync (IWDS)

• IWDS - Command line guide

• IWDS - Tips and Advanced configuration

IWDS is a specific service option that is not included by default in the standard or trial offer. The IWDS application will be blocked if the option is not detected on your service when accessing the TrustBuilder platform. We suggest that you contact your TrustBuilder distributor or reseller to acquire this option for your service. Error message : “The IWDS option is not activated on your inWebo service account“

Where to start?

You first need to identify the right integration method for your infrastructure and environment.

1. Definition of the provisioning source
   IWDS transcribes and synchronizes a data source (LDAP groups, CSV file). You must define as precisely as possible the origin, the number of users and their object formats.

2. Installation and configuration of IWDS
   IWDS is supported on a Windows environment. It can be run in graphical interface (java application) as well as in command lines. To be able to perform a synchronization, it needs to be configured according to the TrustBuilder service and the provisioning sources.

3. Running IWDS
   Once the configuration is done, you can perform a synchronization with the graphical interface. An IWDS synchronization follows a 4 steps process.

4. (optional) Setting up the automation by script
   You can create a script that will automatically initiate IWDS synchronization at the desired time and frequency.
   This point will be covered in the following documentation IWDS - Command-line guide

Defining your provisioning source

IWDS is synchronizing users from the following source:

• Active Directory

• OpenLDAP

• User listing file in csv format

IWDS can run across multiple LDAP groups or servers, so more complex configuration is always possible to keep up with your security architecture and aggregate your users. There are no limit to the number of LDAP servers requested by IWDS when aggregating your users. As a basic LDAP configuration, it is recommended at first to create an "TrustBuilder" or "TrustBuilder_MFA" user group to aggregate the LDAP objects or user groups that will be provisioned on the TrustBuilder platform.

You must answer 3 questions with your LDAP Team:

• Who are the users who will have to pass MFA security?

• Where are these user objects or user groups located on LDAP servers?

• How to assemble them into “TrustBuilder access” group(s)?

IWDS is only able to read your LDAP directory. All creation/modification operations will only be done on your TrustBuilder online service via our API.

Requirements

We assume that you have already set your TrustBuilder service configuration using administration console, i.e. set user groups and roles if required.

• Java JRE version 8 (TLS 1.2 default version)- use a JDK that includes Java JRE 8 - e.g.: OpenJDK, Oracle JDK, …

• IWDS is only provided with a Windows installation package (for Linux you can extract Java executable files to be exported on Linux)

• Administrator access to your TrustBuilder service, with the IWDS service option included

• Download the last version of IWDS from Resources downloads. IWDS is shipped as an executable file for Windows

• Download an Certificate from the Administrator console (“Secure sites” > “Download a new certificate”). Choose the .p12 format.

  

Installation

1. Launch IWDS executable file and follow the instructions (see Requirements).

2. Select a working directory where IWDS will be installed. If you are not an administrator on your computer, please avoid protected folders such as « Program Files ». In this directory, 3 subfolders are created:

   • Configuration files are stored in the “conf” subfolder

   • Output files are stored in the “out” subfolder

   • Log files are stored in the “log” subfolder

3. Click on Install to perform the IWDS installation.

4. Launch IWDS application.

5. You will be automatically prompted to select the certificate file (see Requirements). If not, go to “inWebo” > “inWebo Parameters” and enter the certificate file path.

Interface overview

The IWDS interface provides a left menu with 4 main items, each containing a set of tabs for access to various configurations settings. The main items on the left menu are:

• inWebo → to manage TrustBuilder parameters (requests settings, TrustBuilder servers, TrustBuilder objects)

• LDAP sources → to manage the LDAP sources parameters (connection settings, LDAP attributes, CSV importation, LDAP objects)

• Synchronization → to manage synchronization (make a diff between LDAP objects and TrustBuilder objects, set synchronization rules)

• Options → to manage others options (proxy parameters, log files)

Network configuration

You have to connect two or more environments to use IWDS:

• IWDS have to connect to the TrustBuilder API to retrieve TrustBuilder users and groups and send operations to synchronize to your TrustBuilder service.

• IWDS has to reach your different LDAP sources to read (only) the selected group of users you have defined.
  You can test each LDAP connections with “the test connection” button in the “LDAP data sources” / “LDAP connection” tab.

IWDS is connected to the TrustBuilder platform through our API URI in HTTPS.

Using proxies

If you are using proxies, in IWDS go to the Settings section > Proxy settings tab.

This panel allows you to add proxy parameters if your connection requires such parameters:

• Direct connection: no proxy (this is the default configuration).

• Use browser parameters: use proxy settings of your default browser.

• Use proxy server:

  • Address: host name or IP address of the proxy

  • Port: port of the proxy

  • Use Authentication: you can turn on or off user authentication

    • User: user name used for proxy authentication

    • Password: password for proxy authentication

When you are done, click on “Save Changes”.

TrustBuilder service configuration

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.

TrustBuilder Parameters

To set up TrustBuilder parameters, go to “inWebo” in the left menu > “inWebo Parameters” tab.

Setting	Description
Certificate file	Indicates the path to TrustBuilder Certificate (see Prerequisites above)
Delay between 2 queries	Defines the delay (in milliseconds) between two requests to TrustBuilder Servers.
Maximum query size	Defines the maximum number of users retrieved per request. This parameter should be between 0 and 100.
Activate group synchronization	Turns on group synchronization between LDAP and TrustBuilder Any operation related to group synchronization in IWDS requires this parameter to be turned on.

When you are done, click on “Save inWebo Settings”.

TrustBuilder connection

You should set the connection to TrustBuilder servers to be able to retrieve TrustBuilder objects.

1. Go to “inWebo” in the left menu > “inWebo Connection” tabs.

2. Click on Connection.

3. You will be prompted for the certificate Password. Enter the password you have defined when you created the certificate in Administration Console (see Prerequisites).

4. Click on OK.

LDAP configurations

LDAP server connection

You should set the connection(s) to your LDAP server(s) to be able to retrieve LDAP objects.

1. Go to “LDAP Sources” in the left menu > “LDAP Connection” tab.

2. Select the LDAP source “New…”

3. Set the required connection parameters:

   • Name: the name you give to your LDAP source. Spaces are not allowed

   • Host: IP address or Domain name of your LDAP server

   • Port: LDAP port. Usually 389 (sometimes 3389) or 636 for LDAPS

   • Base DN: Base DN to use for the LDAP connection

   • Use SSL: Whether to use LDAPS or not. The “port” parameter will move to 636 if you use LDAPS

   • Connection Type: LDAP authentication mode (Simple or anonymous)

   • User: LDAP user for connection purposes

   • Password: LDAP password for the user mentioned above

4. When you are done, click on “Save Changes”. You can test the connection using the “Test Connection” button.

Multiple LDAP sources

You can add as many LDAP connections as you need. If you have configured several connections, you can set one of these as the “default” connection.
Create a LDAP connection for each LDAP server you have to connect.

LDAP Search Parameters

You should configure the way IWDS will retrieve your users in your LDAP directory.

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.

1. Go to “LDAP Sources” in the left menu > “LDAP Search Parameters” tab

2. Select the LDAP source “New…”

3. Configure the attributes to use to retrieve your LDAP users:

   • LDAP Attribute for login. E.g.: samaccountname for Active Directory

   • LDAP Attribute for firstname. E.g.: givenname

   • LDAP Attribute for name. E.g.: sn

   • LDAP Attribute for email : E.g.: mail

   • LDAP Attribute for alternative login. E.g. userPrincipalName for Active Directory

4. Configure the base DN of the 3 LDAP user groups mapped with the 3 user roles defined in each and every TrustBuilder service (TrustBuilder user, TrustBuilder manager and TrustBuilder administrator). Please make sure you enter fully qualified LDAP DNs.

   • User group base DN. ex: CN=inwebo-users,DC=example,DC=com

   • Manager group base DN. ex: CN=inwebo-managers,DC=example,DC=com

   • Admin group base DN. ex: CN=inwebo-admins,DC=example,DC=com

5. When you are done, click on “Save Changes”.

LDAP Advanced Parameters

You may set advanced parameters according to your needs:

• Search by attribute: tells IWDS to retrieve LDAP users in the groups you defined via a specific user attribute (typically the “memberOf” attribute on Active Directory)

• Attribute: sets the “Search by attribute” user attribute (by default it is set to “memberOf”)

• Search by group membership: tells IWDS to directly retrieve the users that are members of the groups you defined

• Group membership attribute: sets the LDAP attribute defining the group membership (by default it is set to “member”)

• Recurse sub-groups: tells IWDS to recurse sub-groups during the search

• Maximum recurse depth: sets the maximum number of sub-groups/groups to parse recursively during the search

The name of the source LDAP parameter “Maximum recurse depth” is misleading. It is not the depth in the LDAP tree but the number of group elements that are associated with it.

For consistency with the API reasons the name of the parameter cannot be modified.

• Person Request Filter: sets the filter to apply on LDAP members to identify persons (by default it is set to “objectClass=Person”)

• Group Request Filter: sets the filter to apply on LDAP members to identify groups (by default it is set to “objectClass=Group”)

• Use Active Directory “UserAccountControl”: allows to use the UAC properties retrieved from an AD user (password expired, account disabled) to determine the user TrustBuilder account activation status

• Enable paging of LDAP queries

• Maximum query size: if paging is enabled sets how many users IWDS will request per page

• Delay between 2 queries: delay (in ms) between 2 LDAP page requests

Critical information

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 error, 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.

• In graphical mode, to avoid mass deletion, the synchronization operation is blocked if it is about to delete more than 25 users. (version 2.4.x and above)

LDAP Group Mapping

Go to “LDAP Sources” > “LDAP Group Mapping”.

This panel allows you to configure the mapping between your LDAP groups and the TrustBuilder groups you created for your service in the administration console. This mapping will be used during the “Diff” and the “Sync” operations.

To add a group, simply enter its LDAP name, e.g. “test” (no need to enter its fully qualified DN). Then map this group to an TrustBuilder group with a role. This role can be either the TrustBuilder basic user role (roleid 0) or any of the custom user role configured in the service.

The TrustBuilder basic user role is selected by default. You may add as many LDAP groups as required.

When you are done, click on “Save Changes”.

Best practices

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

Synchronization Rules

You can parameter the way the synchronization is performed by defining synchronization rule sets.

Go to “Synchronization” > “Synchronization Rules”.

The following parameters can be set within a given rule set:

• Rule Name → define a name of the rule set

• Send activation code to new users by email: choose one of the three options

  • Sent by email → an email with an activation link is sent to users - Note that an email attribute must be filled out in the LDAP directory

  • Long code → generation of a long code valid for 3 weeks

  • Activation code → generation of a code for immediate use valid for 15 minutes

If you have chosen to send Activation mails using IWDS (see Activation Rules), make sure you have created the user's email address beforehand.

• Facing an unknown or fake address, this mail address will be blacklisted for 30 days by our SMTP/mail service provider

• In your onboarding process be sure to delay the TrustBuilder access activation of your users until they have a verified mail address

• Language: choose the language used to send emails (English or French)

• Resend activation code for “Pending” users → if checked, IWDS will send again an activation email for users with “Pending activation” status.

• Delete “Expired” users → if checked, 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.

• Keep TrustBuilder users' status → 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.

• Synchronize “Managers” → if checked TrustBuilder users with “Manager” role will be included at each synchronization operation.

• Synchronize “Administrators” → if checked TrustBuilder users with “Administrators” 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

• Synchronize Groups → if checked TrustBuilder Groups will be included at each synchronization operation.

Enabling the “Synchronize Groups” parameter does not activate the group synchronization in IWDS. It has no effect if you don’t activate the Group synchronization (see TrustBuilder Parameters).

When you are done, click on “Save Changes”.

Using IWDS graphical interface

Once the configuration is done, you can perform a synchronization. There are 4 steps to follow in the synchronization process.

1. Retrieve TrustBuilder Objects

2. Retrieve LDAP Objects

3. Make the difference

4. Synchronize the results

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.

1. Retrieve TrustBuilder objects

This is the 1st step (out of 4) of the synchronization process.

A connection to TrustBuilder servers is required before retrieving objects (See Configuration section)

• Go to inWebo in the left-menu > inWebo Objects tab

• Click on “Retrieve objects”

  

After a successful retrieval on TrustBuilder servers, the result is saved to files and displayed in a new panel.

The two first tabs of this new panel display the list of TrustBuilder users and expired TrustBuilder users (objects are read from two result files: inwebo.xml and expired.xml, located in the “out” subfolder of the configuration directory).

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

2. Retrieve LDAP Objects

This is the 2^nd step (out of 4) of the synchronization process.

• Go to “LDAP Sources” > “LDAP Objects”.

• Click on “Retrieve objects”.

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

login;name;firstname;email;role;status[;lang]
loginuser1;name1;firstname1;user1@test.com;0;0
loginuser2;name2;firstname2;user2@test.com;0;0
loginuser3;name3;firstname3;user3@test.com;0;0
....

3. Make the difference

This is the 3^rd step (out of 4) of the synchronization process.

• Go to “Synchronization” > “Synchronize”.

• Click on the “Make Diff” button to compute the differences.

At this step, IWDS computes the differences between existing TrustBuilder objects and LDAP objects. Then it outputs the list of the changes to apply in order to have your TrustBuilder service synchronized with your LDAP directory.

This calculation is performed according to a chosen synchronization rule set. This operation is done locally, without any modification done to your TrustBuilder service.

The correlation between LDAP users and TrustBuilder users is done on the login field (case insensitive).

Multiple LDAP sources

If you have configured several LDAP sources, please make sure every sources are selected as input at this "diff" calculation step. 
In the GUI, multi-selection can be done either with CTRL key + clicks or SHIFT key + clicks.

After a successful computing, the result is written to “Diff” files and is displayed in a new panel. This 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)

The first tab of this new panel shows the user related transactions (transactions are read from file diff.xml located in the “out” subfolder of the configuration directory).

If group synchronization is activated, the second tab of the panel shows the group membership related transactions (transactions are read from file diff_grp.xml located in the “out” subfolder of the configuration directory).

4. Synchronize

This is the last step (out of 4) of the synchronization process.

• Go to “Synchronization” > “Synchronize”.

• Click on the “Synchronize” button to launch the synchronization.

The “Sync” task takes the output of the “Diff”, and applies the transactions one by one. The result of these operations is fetched and written to result files.

If synchronization is successful, the result is displayed in a new panel. The first tab of this new panel shows the result of user related transactions (read from result.xml file located in the “out” subfolder of the configuration directory).

If group synchronization is activated, the second tab of the panel shows the result of group membership related transactions (read from result_grp.xml file located in the “out” subfolder of the configuration directory).

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.

Please, refer to IWDS - Command-line guide to know more.