Directory Synchronization

Overview

The Directory Synchronization module provides an efficient way to synchronize WorkflowGen users and groups with one or more existing enterprise directories.

The following are some key points about synchronization:

• The synchronization process can be manual or automatic.

• The built-in WORKFLOWGEN directory cannot be synchronized.

• A user’s username must be unique across all WorkflowGen directories.

• You can synchronize multiple directories or multiple portions of a directory with different connectors.

• In the case of an account deletion, the user will either be archived or deactivated, depending on parameters specified. If archived, the username will then be renamed and the account disabled.

Recommendation for per-user license mode

It is recommended that you synchronize a new user account with the New user default status option set to Inactive. These new accounts can later be activated manually by the administrator in the user/group lists, or automatically by using the self-activation feature.

General usage

Accessing the synchronization module

Only users with an Administrator profile can access the synchronization module.

Description of synchronization parameters

From the WorkflowGen Administration Module, you can list the directory synchronizations, consult synchronization parameters, or add new synchronizations.

When creating a new synchronization that is based on Active Directory, LDAP, or TEXT, the following fields will appear to define the method of synchronization.

Once saved, it is no longer possible to change the directory connector.

Separator

For the text connector, the column separation character in the text file can be a semicolon (;), a comma (,), or a Tab character.

File path

This field makes it possible to specify a path to access the files for the text connector. It takes as a value the path where the files are located, followed by the synchronization name.

The synchronization name is used to name the files.

LDAP path

For Active Directory, an LDAP path is required. Only a single LDAP path is supported per connector.

User synchronization query

For an LDAP query, an LDAP query must be specified to query user accounts.

Group synchronization query

For an LDAP query, an LDAP query must be specified to query groups.

Directory login and password

For Active Directory or LDAP connectors, a login and password may be required to provide access to the directory server.

Deep search mode

For the Active Directory connector, define if the synchronization should include only the container of the targeted OU or include all the children of the targeted OU.

Data to synchronize

With WorkflowGen, groups and users can be synchronized. User synchronization is required, but group synchronization can be activated or deactivated.

With LDAP synchronization, a group query must be defined even if the group is not set to synchronize.

Users synchronization field

In order to perform synchronization, the module uses a field to identify the users, and defines the additions, deletions, or updates. The default field is USERNAME, but you can choose any field from WorkflowGen (e.g. Ads_Path, EMPLOYEENUMBER, etc.) as long as it is processed by the connector.

Groups synchronization field

As with users, parameters can be set for the group synchronization field.

Prefix username by

To facilitate importing, and in certain cases to avoid double entries concerning user names, it is possible to prefix usernames with a character string. Example: Domain\

The username prefix cannot contain the : (colon) character.

Prefix groupname by

To facilitate importing and to avoid, in certain cases, double entries concerning group names, it is possible to prefix the group names with a character string. Example: Domain\

User synchronization type

There are three synchronization modes: Add only allows new users to be imported, Add and modify also allows data for existing users to be updated, and Add, modify and delete has an additional function that enables archiving of WorkflowGen users who are not included in the Imported Directory.

• Add only: During synchronization, any user that exists in the directory to be imported but does not exist in the WorkflowGen directory will be added to the latter. Data for existing users will not be modified. In order to be added, a user must at least have a user name (USERNAME) and a last name (LASTNAME). If this condition is not satisfied, an error occurs and the add is cancelled. In case of a defect with one of these values (USERNAME and LASTNAME), an alert (WARNING) is generated.

• Add and modify: This type of synchronization functions the same as the preceding one with regards to additions. It also allows you to update data for users who are already present in the directory and are to be synchronized. In this way, data for a user present in the WorkflowGen directory and in the directory to be imported will be updated.

• Add, modify and delete: You can delete users from a WorkflowGen directory through synchronization. In this mode, the user is deleted when they are present in the WorkflowGen directory but not in the directory to be imported.

Group synchronization type

There are three synchronization modes: Add only allows only new groups to be imported, Add and modify allows data for existing groups to be updated, and Add, modify and delete has an additional function that enables archiving of WorkflowGen groups that are not included in the imported directory.

New user default status

This option defines the default status of new user accounts that are created during the synchronization. Set the status to Active if you want a new user account to be activated by default. Set the status to Inactive if you want to manage a new user account activation manually, or to enable the user self-activation feature. This is recommended for clients who are using the per-user license mode.

Self-activation

This option allows an inactive new user account to activate itself when logging into WorkflowGen for the first time. The ‘Inactive’ new user default status option must be selected in order to use this option.

If a user is deleted

In order to provide proper user tracking in WorkflowGen, when a deletion request is generated, users that have performed actions are not actually deleted; you can either deactivate them or archive them. Once archived, the user will retain their unique internal ID, but their username will be renamed with an archive suffix and sequence number.

Launching mode

Triggering can occur manually (using the Synchronize button) or automatically.

• Manual: Manual synchronization makes it possible to perform synchronization on an on-demand basis only. To do this, click the Synchronize button on the synchronization file concerned.

• Test: This mode has the same running mode as manual synchronization, except that processing is, in reality, not performed. Instead, it is only simulated in order to anticipate if synchronization will take place correctly or not. To do this, click the Test button. A synchronization test is logged in the same way as a real synchronization.

• Automatic: Data synchronization can take place automatically. In this case, a scheduled task analyzes the configuration of all the synchronizations on a daily basis, and subsequently runs the process.

Frequency

If synchronization is performed automatically, you can choose the frequency for synchronization. This can be every day, once a week, or once a month. For automatic synchronization, see the Configuration Panel section for instructions on how to set specific dates and times for the operation.

Active Directory connector

Overview

The purpose of the connector is to import users and groups from Active Directory into a WorkflowGen directory. The connector operates with the LDAP protocol using ADSI (Active Directory Service Interface). Access to Active Directory is read-only.

Requirements

• Read-only LDAP access to Active Directory is required for an anonymous account or for an account that has access to the Active Directory server.

• If the Active Directory server is located behind a firewall, the LDAP protocol must be open.

• You can use the ADSVIEW utility tool provided in the setup package to check that your LDAP path refers to the correct container to retrieve the users and groups of your directory.

LDAP path

The connector needs an LDAP path in order to retrieve the data in Active Directory. This path consists of:

• The protocol: LDAP://, in this case.

• The name of the server or its IP address.

• Optionally, the port separated from the name of the server with : (colon). Default: 389

  Note: If you’re using LDAP in SSL mode, you must use port 636; otherwise, you can omit the port number, or use the default one.

• The path in the server's LDAP tree structure.

In order to run the query that is needed to synchronize the users, the Organization (O) and the Organizational Units (OU) must be specified starting from the bottom upwards, preceding them with DC= and separating them with , (comma).

Example:

An Active Directory structure is as follows:

• Top level Domain (DC): thecompany.com

• Organization unit (OU): group within the domain: BusinessUnit2

• Sub-unit (OU): sub-group within the domain: IT Department

In order to access users and groups of IT Department, the LDAP path would be

LDAP://servername:port/OU=IT Department,OU=BusinessUnit2,DC=thecompany,DC=com

The LDAP path does not support the . operator, but it does support spaces. Therefore, the .com is identified by the DC=com operator.

• CN is also supported as a container type.

• Only one branch of the directory can be associated with a given directory. If multiple OUs at the same level must be queried, then the parent of both OUs must be queried, or two directories created. For example, if the structure /Company/Department1 and /Company/Department2 and /Company/Department3 exists, and only departments 1 and 2 must be queried, then either the entire /Company OU should be specified (all three department OUs will be synchronized), or two separate synchronization directories should be created each with one OU specified.

• LDAP query filters are not supported.

• The group query is inherently the same as the user query.

• Groups and users linked to them must exist within the same LDAP path, otherwise mismatched group/user combinations will be excluded from the synchronization and appear as errors in the synchronization log. This typically occurs when Active Directory groups are defined as CNs within an OU that point to users that are in fact defined in other OUs outside the scope in the LDAP path provided. For example, this situation will arise if the LDAP path is defined to link only to the /Company/Department1 OU, and within this OU the /Company/Department1/Team1 group points to users in /Company/Department2. In this case, it is recommended to either choose an LDAP path that includes all OUs that are involved in the groups, or to use the LDAP connector type instead to create more refined individual user/group queries and filters.

For more information, see LDAP connector.

Data to import

Synchronization is performed for users. However, it is also possible to synchronize groups, and consequently group user memberships. You can import data directly from the OU or the container that is the target path. You can retrieve data from the child containers by activating the Deep search mode.

For users to be synchronized, their sn and sAMAccountName attributes must be set in Active Directory. These map to Last name and Username, respectively.

The Active Directory connector does not take into account the Disabled property of AD user accounts; these accounts will therefore be synchronized as active users. If you don't want the synchronization to include inactive AD accounts, you'll need to use the LDAP connector instead, with the (!(userAccountControl:1.2.840.113556.1.4.803:=2)) filter added to the user synchronization query. As well, make sure to set the desired behavior for the If a user is archived option to either Archive (default) or Deactivate whenever an existing account becomes inactive in AD.

Synchronization fields

User synchronization field and Group synchronization field are set to System identifier by default.

If you have an existing WorkflowGen installation that uses an Active Directory connector for synchronization, we recommend switching the user and group synchronization fields to System identifier, since it is a unique identifier for each user and group object in Active Directory.

Retrieving Active Directory data

The information is retrieved in Active Directory using the LDAP path. As such, it provides an in-depth access to the data by targeting the OU from which the users and groups are to be retrieved.

The tables below list the mapping between the key-entry fields for a user and the field names with Active Directory. These mappings can't be edited, so if you want to edit them, you'll need to use the directory LDAP connector (see LDAP connector below).

Users

Field	Active Directory default mapping
Username	sAMAccountName
Password	userPassword
Name	sn
First name	givenName
Email	mail
Default time zone	(none)
Manager	manager
Phone	telephoneNumber
Mobile	mobile
Fax	facSimileNumber
Pager	pager
Office	physicalDeliveryOfficeName
Department	department
Company	company
Job title	title
Employee type	employeeType
Initials	initials
Title	personalTitle
Employee number	employeeID
Postal address	postalAddress
Zip code	postalCode
City	l
State/Area	st
Country	co
LDAP path	ADsPath
Display name	distinguishedName
Distinctive name	cn
Extended attribute 1	extensionAttribute1
Extended attribute 2	extensionAttribute2
Extended attribute 3	extensionAttribute3
Extended attribute 4	extensionAttribute4
Extended attribute 5	extensionAttribute5
System identifier	objectSid

Groups

Field	Active Directory default mapping
Name	sAMAccountName
Description	Description
Email	mail
Group code	groupCode
LDAP path	AdsPath
Display name	cn
Distinctive name	DistinguishedName
System identifier	objectSid

LDAP connector

Overview

The purpose of the LDAP connector is to import users and groups from a generic LDAP directory (e.g. AD, Sun ONE, ADAM, etc.) into a WorkflowGen directory. The connector operates with the LDAP protocol and the connection is performed as read-only.

Requirements

Read-only LDAP access is required for an anonymous account or for an account that has access to the LDAP server. If the LDAP server is located behind a firewall, the LDAP protocol must be open.

User and group synchronization queries

The connector needs an LDAP query in order to retrieve the data in the directory. This query consists of:

• The protocol: LDAP://, in this case.

• The name of the server or its IP address.

• Optionally, the port separated from the name of the server with : (colon). The default port is 389.

• The top level domain.

• The LDAP query and/or filters.

Examples:

An LDAP structure is as follows:

• Top level Domain (DC): thecompany.com

• Organization unit (OU): Group within the domain: BusinessUnit2

• Sub-unit (OU): Sub-group within the domain: IT Department

In order to access users and groups of IT Department, the LDAP queries would be (assuming an Active Directory LDAP structure):

User

LDAP://servername:port/DC=thecompany,DC=com;(&(objectCategory=person)(objectClass=user)(sn=*)(sAMAccountName=*)(memberOf=CN=TheSpecificCN,OU=LowestOU,OU=HigherOU,DC=thecompany,DC=com)(!(userAccountControl:1.2.840.113556.1.4.803:=2)));adsPath,objectSid,sAMAccountName,sn,GivenName,mail,telephoneNumber,mobile,pager,facSimileTelephoneNumber,department,company,EmployeeType,EmployeeId,title,initials,postalAddress,postalCode,physicalDeliveryOfficeName,st,L,co,manager;subtree

Group

LDAP://servername:port/DC=thecompany,DC=com;(&(objectClass=group));adsPath,objectSid,sAMAccountName,Description;subtree

To use a specific CN referencing two groups, the following query filters may be used:

User

LDAP://servername:port/DC=thecompany,DC=com;(&(objectCategory=person)(objectClass=user)(sn=*)(sAMAccountName=*) (memberOf=CN=TheSpecificCN,OU=LowestOU,OU=HigherOU,DC=thecompany,DC=com)(!(userAccountControl:1.2.840.113556.1.4.803:=2)));adsPath,objectSid,sAMAccountName,sn,GivenName,mail,telephoneNumber,mobile,pager,facSimileTelephoneNumber,department,company,EmployeeType,EmployeeId,title,initials,postalAddress,postalCode,physicalDeliveryOfficeName,st,L,co,manager;subtree

Group

LDAP://thecompany/dc=thcompany,dc=com;(&(objectClass=group)(|(sAMaccountName=Group1)(sAMaccountName=Group2)));adsPath,objectSid,sAMAccountName,Description;subtree

• Only one user and group query can be associated with a given directory. If multiple OUs at the same level must be queried, then the parent of both OUs must be queried, two directories created, or a specific query filter devised that includes both OUs.

  For example, if the structure /Company/Department1 and /Company/Department2 and /Company/Department3 exists, and only departments 1 and 2 must be queried, then either the entire /Company OU should be specified (all the department OUs will be synchronized), or a specific filter must be devised that queries only those two OUs.

• Groups and users linked to them must exist within the same LDAP path, otherwise mismatched group/user combinations will be excluded from the synchronization, and appear as errors in the synchronization log. This typically occurs when AD groups are defined as CNs within an OU that point to users that are in fact defined in other OUs outside the scope of the LDAP path provided.

  For example, if the LDAP path is defined to link only to the /Company/Department1 OU, and within this OU the /Company/Department1/Team1 group points to users in /Company/Department2, this situation will arise. In this case, it is suggested to choose a user query that includes all OUs that are involved in the groups.

References

See the following web pages for additional samples of generic LDAP queries:

• http:/www.petri.co.il/ldap_search_samples_for_windows_2003_and_exchange.htm

• http://msdn2.microsoft.com/en-us/library/aa746475.aspx

• http://technet.microsoft.com/en-us/library/aa996205.aspx

Data to import

Synchronization is performed for users. However, it is also possible to synchronize groups, and consequently, group user memberships.

For users to be synchronized, their sn and sAMAccountName attributes must be set in Active Directory. These map to Last name and Username, respectively.

You can import data directly from the OU or the container that is the target path. You can also retrieve data from the child containers by activating the Deep Search Mode.

Synchronization fields

The default synchronization fields are set as follows:

• Users: System identifier

• Groups: name (sn)

Retrieving LDAP data

The following tables list the mapping between the key-entry fields for a user and the field names with LDAP. These mappings can be edited by selecting the Edit mapping button on the directory editing page.

Make sure to save the field mapping whenever you add or modify an LDAP query.

Users

Field	LDAP default mapping
Username	sAMAccountName
Password	(none)
Name	sn
Firstname	givenName
Email	mail
Default time zone	(none)
Manager (must be a valid username)	manager
Phone	telephoneNumber
Mobile	mobile
Fax	facSimileNumber
Pager	pager
Office	physicalDeliveryOfficeName
Department	department
Company	company
Job title	title
Employee type	employeeType
Initials	initials
Title	personalTitle
Employee number	employeeID
Postal address	postalAddress
Zip code	postalCode
City	l
State/Area	st
Country	co
LDAP path	ADsPath
Display name	distinguishedName
Distinctive name	cn
Extended attribute 1	extensionAttribute1
Extended attribute 2	extensionAttribute2
Extended attribute 3	extensionAttribute3
Extended attribute 4	extensionAttribute4
Extended attribute 5	extensionAttribute5
System identifier	objectSid

Groups

Field	LDAP default mapping
Name	sAMAccountName
Description	Description
Email	mail
Group code	groupCode
LDAP path	AdsPath
Display name	cn
Distinctive name	DistinguishedName
System identifier	objectSid

Text connector

Overview

The purpose of the text connector is to import users and groups using text files into a WorkflowGen directory.

Requirements

The text connector requires three different text files:

• User: One text file that contains the data related to the users to synchronize.

• Group: One text file that contains the data related to the groups to synchronize.

• Usergroup: One text file that contains the relationships between the users and the groups according to the selected synchronization fields.

Data to be imported

Synchronization takes place for the users, but it can also be activated for groups. To do this, check the corresponding box in the synchronization configuration sheet.

Selecting files

Since files to be imported have a standard suffix, use Filepath and key in the path followed by the part that is common to the names of the three files.

Example:

If you decide to name your import importWorkflowGen and you have saved it to the DRIVE:\Extract\ directory, you will need to have the importWorkflowGen_USER.txt file in this directory. If you want to perform group synchronization as well, you also need the importWorkflowGen_GROUP.txt and importWorkflowGen_USERGROUP.txt files. When setting the parameters for synchronization, once you have chosen the Text connector, enter DRIVE:\Extract\importWorkflowGen in Filepath.

Text file names

Data import files must have suffixes as described in the following manner:

• The user file must end with _USER.txt

• The group file must end with _GROUP.txt

• The group user member file must end with _USERGROUP.txt

The rest of the file name must be the same for the three files.

Text file structure

Text files begin with a line listing each of the property names separated with a character that is defined as a constant in the connector file. Each line then corresponds to a record, such as a user, with the values also separated by the delimiting character. If a property is empty, it must nevertheless be delimited by the separating character. The default delimiter is ; (semicolon).

The , (comma) separator cannot be used on a server that uses this character as a decimal separator, such as a French server.

The group user member file only has two fields: synchronization fields for groups and for users. These fields are chosen in the directory synchronization module. As well, it is possible to prefix the names of these fields in order to avoid cases where a field name for synchronizing users is the same as that for groups. These parameters are set in the Configuration Panel in the Administration Module when setting the Active Directory synchronization values.

For example, if the user synchronizing field is Username and the field for the groups is name, the file must contain the GROUP_sAMAccountName and USER_sAMAccountName fields.

ADS path

With text files exported from Active Directory, the connector needs the LDAP path in order to allow it to rebuild the ADSPATH property for the users.

List of properties

The following tables list the properties that are needed for synchronizing users, with their equivalents in WorkflowGen. These mappings define the column names in the text file and can be edited by selecting the Edit mapping button in the directory editing page.

Users

Field	Text default mapping
Username	sAMAccountName
Password	(none)
Name	sn
Firstname	givenName
Email	mail
Default time zone	(none)
Manager (must be a valid username)	manager
Phone	telephoneNumber
Mobile	mobile
Fax	facSimileNumber
Pager	pager
Office	physicalDeliveryOfficeName
Department	department
Company	company
Job title	title
Employee type	employeeType
Initials	initials
Title	personalTitle
Employee number	employeeID
Postal address	postalAddress
Zip code	postalCode
City	l
State/Area	st
Country	co
LDAP path	(none)
Display name	(none)
Distinctive name	(none)
Extended attribute 1	(none)
Extended attribute 2	(none)
Extended attribute 3	(none)
Extended attribute 4	(none)
Extended attribute 5	(none)
System identifier	(none)

Groups

Field	Text default mapping
Name	sAMAccountName
Description	Description

User groups

These are the required fields for the group user member file:

• Synchronization field name for groups (e.g. GROUP_SAMAccountName)

• Synchronization field name for users (e.g. USER_SAMAccountName)

Active Directory export text file

You can generate an export text file for user data by using the following command:

csvde –f file.csv –s SERVERNAME –d "OU=myOu,DC=mycompany,DC=com" –p subtree –r "(objectClass=OrganizationalPerson)" –l "ADsPath,cn,displayName,givenName,sn,sAMAccountName,mail, telephoneNumber,mobile,pager,facSimileTelephoneNumber,physicalDeliveryOfficeName,department,company, initials,title,employeeID,employeeType,postalAddress,postalCode,l,st,co,personalTitle"

In this case SERVERNAME is the name of the server hosting the directory, file.CSV is the name of the resulting text file, and OU=myOu,DC=mycompany,DC=com is the path to the container in which you want to put the list of users.

To execute this synchronization automatically, this data export process must be added to the task scheduler before the synchronization script is run. To add a task, see the administrator documentation for the Synchronization module. This method does not allow groups to be synchronized.

Examples of text files

User file

sn;givenName;sAMAccountName;mail;
"USER1-01";"Paul Smith";"psmith";"[e-mail]";
"USER1-02";"John Doe";"jdoe";"[e-mail]";
"USER1-03";"Jack Ryan";"jryan";"[e-mail]";
"USER1-04";"Ted Graham";"tgraham";"[e-mail]";

Group file

sAMAccountName;Description
"HR";"GRP1-01"
"IT";"GRP1-02"

User group file

GROUP_sAMAccountName;USER_sAMAccountName
"HR";"psmith"
"HR";"jdoe"
"IT";"jryan"
"IT";"tgraham"

SCIM connector

The SCIM connector lets you define a new directory that will be used by Azure Active Directory to synchronize users and groups. For information on how to configure this, see the Azure Active Directory Synchronization section in the WorkflowGen for Azure guide.

Self-provisioning connector

The self-provisioning connector is a directory connector that automatically creates and synchronizes a user based on the user's session token claims that contain claims from the OpenID Connect provider ID token. For instructions on how to configure this, see the Auth0 user provisioning section in the WorkflowGen Technical Guide.

Synchronization logs

Overview

Synchronization logs are set up on the Directory synchronization tab in the Configuration Panel; see Directory synchronization in the Configuration Panel section.

Each synchronization, whether manual or automatic, is logged and available to be viewed by Administrators only, in the Synchronization logs option in the Directories menu.

By default, 31 days of logs are maintained. This parameter can be changed by an administrator in the Configuration Panel.

Each log provides the details of each synchronization action performed, including listing all users and groups added, modified, or deleted (archived). This also includes warnings (such as a missing email) and errors (such as a missing last name). Log files can be viewed or deleted.

Location of log files

Log files can be found on the WorkflowGen server under the \wfgen application folder at the following location: \wfgen\App_Data\LogFiles\Dir\Synchro.