BPS users list synchronization

Applies to version: 2017.1.x and above; author: Jacek Język

Introduction

The BPS users list contains all information about users in the system. The AD cache was replaced with the BPS user list, but the AD and AAD are still the preferred methods for managing user data. The BPS users list will now combine users synchronized from the AD or AAD with those from external authentication providers, into one universal cache of all users of the system. The BPS user list serves as the base for granting privileges to view and access the system, and also contains data of the company structure. Its status has to be constantly updated to provide users with uninterrupted access. This is why a correct configuration of this system element and monitoring the synchronization are critical system tasks.

Configuration

To configure the list, go to Designer Studio -> System settings -> Global parameters -> BPS users list. 

 

Fig. 1. BPS users list

 

To define the parameters of BPS users list synchronization, click the "Synchronization configuration" button. The configuration window with four tabs will appear on the screen:

• Settings
• Credentials
• Schedule
• Advanced

Designating synchronized AD domains

In the "Settings" tab, you can select a domain or a sepcific Organization Unit (OU) from which user/group/organization data will be downloaded. You can select several domains or OUs which will be synchronized. The domain and OU list are available by clicking on “+” button.

Sidenote:

The configuration of synchronized domains/OU’s is done also in the WEBCON BPS installer during system update from older versions to 2017.1. However in this case synchronization is not done by the installer, but by WEBCON WorkFlow Service in time set in the schedule after correct installation.

Users can work with the system (i.e. data access) as soon as the first successful synchronization is complete.

 

Fig. 2. The "Settings" tab

 

Data synchronization from Active Directory is carried out in the context of the user that is defined in the “Credentials” tab. So in the context of this user, the list of domain/OU’s possible to synchronization is loaded.

Available on the list by default, is a domain to which a server with WEBCON WorkFlow Service installed belongs. Also available are all domains from the same domain forest. If there are configured trust relationships with another domain/forest, then those also trusted domains/forests are also visible on the list.

An OU structure is displayed within the domains, which allows to narrow down the synchronization to a chosen entity.

During the synchronization, data is downloaded from selected OU’s. However if downloaded objects have a relation to the object from outside the synchronized entity (i.e. users’ superior belongs to other, not synchronized domain), then despite the lack of this domain in configuration, necessary data considering this object (i.e. superior’s) will be downloaded. Downloading data from outside the synchronized entities is subject to additional conditions (i.e. proper privileges) – more details of the synchronization can be found in the further part of this article.

The range of data downloaded from the Active Directory during synchronization is included in Appendix A. However it is possible to download additional data about the synchronized item from AD and save it in the BPS database. 30 additional properties that were read from the AD are available to download, and their values will be saved on selected database columns.

Pointing to additional data for synchronization is not necessary.

 

Fig. 3. The "Settings" tab

 

Some information about a user can be independently stored both in Active Directory and in the user's SharePoint profile. This information is:

	Attribute name in AD	Attribute name in SP
E-mail address	mail	E-mail
Displayed name	displayname	Name
Department	department	Department
Job title	title	Job Title

 

 

The synchronization configuration allows you to indicate from which source (Active Directory or SharePoint) this information will be downloaded. Selecting the "Data set in the user's SharePoint profile should overwrite data from Active Directory" downloads the data saved in the SharePoint profile. Leaving it non-checked downloads the data from Active Directory. 

 

Fig. 4. The "Sharepoint user profile data overrides..." option

 

Connection data setup

BPS user list synchronization with Active Directory is performed by WEBCON WorkFlow Service in the context of the user defined in the synchronization configuration in the “Credentials” tab. The user for synchronization must have appropriate privileges allowing to read data from the domains/OU indicated in the configuration. 

Minimal privileges needed to execute a correct synchronization:

• read account restrictions
• read general information
• read public information

The default user in the context of whom the synchronization is executed is the user on whom the WEBCON WorkFlow Service works.

 

Fig. 5. The "Credentials" tab

 

Synchronization schedule

The schedule allows defining hours of synchronization execution. In order to ensure that WEBCON BPS has current data, synchronization should be carried out a couple of times a day.

Default configuration carries out the synchronization every 3 hours. In most cases, this configuration is enough to bring up to date even frequently changing data. The synchronization mechanism is additionally integrated with user management actions (“Active Directory” action groups and “SharePoint – privileges”). If such an action is executed, the system will start synchronization for users edited outside the schedule and instantly update the BPS user list.

Synchronization schedule can be tailored to the specific needs of individual system implementations. When changing synchronization hours it is important to remember about: frequency of data changes by the AD and SharePoint or maintenance of the system (it requires halting the synchronization in a specified timeframe).

 

Fig. 6. The "Schedule" tab

 

Synchronization schedule configuration is also available from the service configuration menu in “System settings”.

 

Fig.7. The "Schedules" section

 

Synchronization types and diagnostic options

Synchronization can be carried out in two ways, as Incremental synchronization or Full synchronization.

The default mode is Incremental synchronization. While it is carried out, the user and group data are updated in a differential way which means only the data that changed since the last synchronization. Status of added/removed objects is also refreshed. In Full synchronization, all the data is refreshed regardless if it was changed since the last synchronization or not.

For purely performance reasons, it is recommended to use Incremental synchronization in the vast majority of cases. Full synchronization should be used only in certain cases, especially when Incremental synchronization doesn’t refresh the elements correctly. This can be indicated by wrong range of data displayed on the user form and reports, lack of user on BPS user list or errors of incremental synchronization.

 

Fig. 8. The "Advanced" tab

 

BPS user list synchronization can be started manually. Clicking on “Incremental synchronization” or “Full synchronization” will initiate the synchronization accordingly to the current configuration. It is important to save the configuration before the manual start of the synchronization.

Options “Incremental synchronization – Debug” and “Full synchronization – Debug” allow starting synchronization with an expanded data logging. DEBUG mode allows for an accurate analysis of all synchronization steps and should only be used for diagnostic reasons.

Monitoring the synchronization

To ensure uninterrupted work for WEBCON BPS users, synchronization has to be constantly monitored and all the abnormalities corrected.

Events that might occur during the synchronization are divided into two categories: errors and warnings. This division comes from the influence of a specific event on the work of the system.

Examples of events labeled as errors:

• No access to the synchronized domain/OU
• It is not possible to download users’ ID (login, User Principal Name) or group (SID).

Examples of events labeled as warnings:

• It is not possible to download a part of user/group data
• It is not possible to download superior’s data coming from an unsynchronized domain
• It is not possible to download group data coming from an unsynchronized domain

Full information about the synchronization along with errors and warnings is saved in the synchronization log. It is accessible from WEBCON BPS Studio level or system Event Log.

 

Fig. 9. Possible errors

 

In case of events qualified as errors, the information can be sent to a specified e-mail address as administrative notification. To configure such notification for users list synchronization choose “Users list synchronization” in the notification range.

 

Fig. 10. The "Administrative notifications" section

 

Synchronization description

Rules of the synchronization will be described based on a handful of BPS and Active Directory configuration scenarios.

 

Full domain synchronization

A whole AD domain from which the data has to be synchronized is selected in BPS configuration.

 

Fig. 11. The "Settings" tab

 

 

Example of Active Directory’s structure in OU New York consists of employees, but their superior is a part of OU London. OU London contains also other user and group objects.

The user in the context of whom the synchronization is executed („Credentials” tab) has privileges allowing to read data both from OU New York and OU London.

 

Fig. 12. Example of Active Directory’s structure

 

During the synchronization data of all the users and groups of OU New York will be downloaded (User1, User2, User3 and Employees). For users whose superior belongs to OU London, even though of the fact that synchronization is executed for OU New York, the superior’s data will be also downloaded. This also means that his data (the Manager), groups that he belongs to (Management) and his relationships with his superiors will be loaded.

Other users and groups from OU London will not be downloaded (UserA, UserB, UserC, and Users).

If there are subordinate OU’s in OU London, then this data will be downloaded as well.

All the changes (adding/removing a group, user, affiliations) will be saved in the BPS database and have their reflection in BPS users list.

 

Synchronization of specified OU without access to unsynchronized OU

In BPS configuration a specific OU was selected from which the data is going to be synchronized. (Active Directory contains a couple of OU’s).

 

Fig. 13. The "Settings" tab

 

This sample Active Directory structure in OU New York consists of employees, but their superior is a part of OU London. OU London contains also other user and group objects.

The user in the context of whom the synchronization is executed („Credentials” tab) has privileges allowing to read data from OU New York but doesn’t have access to OU London.

 

Fig. 14. Example of Active Directory’s structure

 

During the synchronization data of all the users and groups of the OU New York will be downloaded (User1, User2, User3, and Employees). For users whose superior belongs to OU London, the superior’s data will attempt to be read. However, the lack of privileges to this data will cause the reading to fail. In the synchronization log, a warning will appear informing about the lack of ability to read data for this “Manager” user.

If there are subordinate OU’s in OU London, then this data will be downloaded as well.

All the changes (adding/removing a group, user, affiliations) will be saved in the BPS database and will have their reflection in BPS users list.

 

Data synchronization with SharePoint

BPS user list synchronization is carried out through a few connected steps. Apart from data synchronization from Active Directory, one of the synchronization steps is SharePoint data synchronization.

Downloading group and SharePoint user data start with searching in SharePoint farm for all the Web Applications with active BPS feature. Next all the users, group users, and groups are downloaded for all SharePoint sites of this Web Applications.

Data from both sources (AD and SharePoint) is merged (i.e. additional information about user’s affiliation to SharePoint groups) and then saved in WEBCON BPS database. The diagram below shows the steps of the synchronization process.

 

Fig. 15. The synchronization process

 

 

Deleting users/groups marked as "not entirely update"

The minimum range of data allowing to identify a specific user, is their login and UPN. For groups it is the SID. If those identifiers are read from Active Directory then the synchronized object is saved in BPS database. If the identifiers are not read, the information about user/group will not be saved in BPS database which means it won’t be available in BPS users list as well.

Identifiers themselves are not enough for correct system operation, especially when it comes to the functionalities based on privileges, group affiliation or organizing structure. This is why in case the full information about user/group was not downloaded, this object is marked as “not fully updated” with corresponding information in the synchronization log.

The administrator must to identify the reason for it (i.e. lack of specific read privileges) and fixing the configuration if needed, to ensure a full update. In some cases it might be needed to use Full synchronization instead of Incremental synchronization.

If data marked as „not fully updated” is not fixed in 24 hours, then in the next synchronization after this time passes, the data will be completely removed from the database and the user’s work in the system will not be possible.

 

Appendix A – Range of data downloaded from AD during synchronization

Target database column	AD form field name	Mandatory attributes(*)
[COS_IsActive]	useraccountcontrol (ADS_UF_ACCOUNTDISABLE)	X
[COS_AD_accountexpires]	accountexpires
[COS_AD_countrycode]	countrycode
[COS_AD_iscriticalsystemobject]	iscriticalsystemobject
[COS_AD_localeid]	localeid
[COS_AD_objectguid]	objectguid
[COS_AD_objectsid]	objectsid	X
[COS_AD_objectversion]	objectversion
[COS_AD_primarygroupid]	primarygroupid
[COS_AD_samaccounttype]	samaccounttype	X
[COS_AD_securityidentifier]	securityidentifier
[COS_AD_useraccountcontrol]	useraccountcontrol	X
[COS_AD_whenchanged]	whenchanged
[COS_AD_whencreated]	whencreated
[COS_AD_company]	company
[COS_AD_comment]	comment
[COS_AD_department]	department
[COS_AD_description]	description
[COS_AD_displayname]	displayname
[COS_AD_distinguishedname]	distinguishedname	X
[COS_AD_givenname]	givenname
[COS_AD_homedirectory]	homedirectory
[COS_AD_homephone]	homephone
[COS_AD_info]	info
[COS_AD_ipphone]	ipphone
[COS_AD_mail]	mail
[COS_AD_manager]	manager
[COS_AD_memberOf]	memberOf
[COS_AD_mobile]	mobile
[COS_AD_name]	name
[COS_AD_objectcategory]	objectcategory
[COS_AD_objectclass]	objectclass
[COS_AD_ou]	ou
[COS_AD_pager]	pager
[COS_AD_postalcode]	postalcode
[COS_AD_postofficebox]	postofficebox
[COS_AD_samaccountname]	samaccountname
[COS_AD_showinaddressbook]	showinaddressbook
[COS_AD_sn]	sn
[COS_AD_st]	st
[COS_AD_streetaddress]	streetaddress
[COS_AD_telephonenumber]	telephonenumber
[COS_AD_title]	title
[COS_AD_userparameters]	userparameters
[COS_AD_userprincipalname]	userprincipalname	X
[COS_AD_wwwhomepage]	wwwhomepage
[COS_AD_physicalDeliveryOfficeName]	physicalDeliveryOfficeName
[COS_AD_cn]	cn
[COS_AD_proxyaddresses]	proxyaddresses

 

(*) – mandatory attributes mean the minimal range of data downloaded during synchronization. The lack of access to the results in skipping the object (user or group) during synchronization. This object will not visible in the BPS users list.