DoorSynch Application v2.0.0
Copyright © Dr Andrew Gray
| Revision History | ||
|---|---|---|
| Revision 1.0.0 | 11-July-2007 | AJG |
|
DoorSynch 1.0 release. | ||
| Revision 2.0.0 | 15-February-2008 | AJG |
|
DoorSynch 2.0 release. | ||
Abstract
DoorSynch is a .Net 2 Windows application which enables users to synchronize the user sets of ACTAtek door access control units with a range of external data sources, and to visualise differences between them. The data sources that DoorSynch 2 supports include: Janus systems, SQL Server 2005 databases, MySQL databases, MS-Access databases, Excel spreadsheets and CSV files.
This document describes how to install and use the 'DoorSynch' Windows application, which has been developed by RCRT in partnership with Cambridge ICT.
For more information, see: http://www.rcrt.co.uk
The purpose of DoorSynch is to enable an ACTAtek door access control unit's user set to be synchronized with an external data source or system.
The data sources / systems that are supported by DoorSynch 2 include: Janus security systems, SQL-Server 2005 databases, MySQL databases, MS-Access databases, Excel spreadsheets and CSV files.
An ACTAtek unit stores user data internally, which determines the set of users that are allowed access through the door(s) managed by the unit. The user information stored includes their: Names, User IDs, 'Smart Card' numbers, and access group memberships.
The DoorSynch application is designed to enable the user sets in the data source and the ACTAtek to be viewed, to enable differences in the two sets of users to be identified, and to enable an ACTAtek's user-set to be synchronized with the data source/system.
The DoorSynch Windows Application allows this synchronization process to be run 'on demand', whereas the DoorSynch Windows Service enables it to be done automatically at predefined intervals.
This document consists of the following sections:
Section 1: Is the Introduction.
Section 2: Summarises the relevant aspects of ACTAtek door access control units.
Section 3: Describes how to install the DoorSynch application on a client machine, and unlock the software.
Section 4: Provides an overview of the DoorSynch application's user Interface.
Section 5: Describes how to set-up and configure the DoorSynch Windows application.
Section 6: Explains how to use DoorSynch to synchronize an ACTAtek's user set with an external data source.
Section 7: Provides further details of the 'differencing' and 'update' processes that are performed by DoorSynch.
Section 8: Describes some of the security considerations that should be taken into account when using DoorSynch.
The DoorSynch Application's User Interface
ACTAtek units provide a SOAP XML Web Service API which allows external applications to interface with the unit, and manipulate its state.
The DoorSynch application communicates with ACTAtek using these web services, connecting via either standard http, or secure https transport.
DoorSynch is a Windows application which uses the Microsoft .Net 2 framework, and which requires a client machine to have .Net 2 already installed. The application is distributed ready for installation by a standard msi installer, as shown below:
When the application is first started, the user is asked whether they wish to 'unlock' the application. When they chose to do so, they will be presented with a product license 'unlock' dialog, as shown below:
The user should enter their e-mail address and license code in the fields provided. If this information is correct, then the license code will be validated, and the product unlocked, which is then confirmed to the user.
Note
Users should use the same e-mail address for any subsequent 'unlocks', also if the user has a registered account on the RCRT website, then they should use their registered e-mail address.
The DoorSynch application starts automatically when it is first installed. It can subsequently be run in the usual way: either using the Windows 'Start' menu, or via a dedicated desktop link. The application's user Interface appears as shown previously, and includes the following core components:
A Menu Bar
The menu bar is at the top of the main form, and includes the following pull down menus: 'File', 'Tools', 'Event Log' and 'Help'.
The menu bar also includes two display fields on the right-hand-side, which show the selected data source and ACTAtek units.
A Central Tab Control.
This is the main component of the user interface, and includes a number of tab pages that are described below.
A Status Bar
This includes a status message on the left; and displays a link to the application's event log viewer when an error occurs.
The tab pages available on the application's main tab control are as follows:
'Source Data'
This tab page provides a view of the user data in the source system as a (read-only) table.
This table is populated by clicking the 'Load' button on the tab, which then queries the source system and displays the results.
In order for this functionality to work, the 'Data Source Configuration' section on the 'Configuration' tab must be correctly populated.
'ACTAtek Data'
This tab page provides a view of the user data in the ACTAtek unit as a (read-only) table.
This table is populated by clicking the 'Load' button on the tab, which interrogates the ACTAtek unit using SOAP xml web services, and displays the results.
In order for this functionality to work, the 'ACTAtek Configuration' section on the 'Configuration' tab must be correctly populated.
'Update Actatek'
This tab page provides the ability to either: (i) view differences between the data sets in the two systems, or (ii) synchronize the ACTAtek's user set with a data source/system.
When a 'Differencing' operation is performed, a list of the differences in the two user sets is computed and displayed as a table on the page.
When an 'Update' operation is performed, the list of differences is first displayed, and then updated in real-time as the user updates are executed. A 'Progress Bar' located on the tab indicates how much of the synchronization operation has been completed.
Operation Logs
This tab page allows a user to open and view the 'Operational Log' files that are maintained by DoorSynch.
These logs provide an audit-trail of all of the changes made to the ACTAtek user set by DoorSynch, including time-stamps for all user 'add' and 'remove' operations.
Configuration
This tab page is where the configuration data that is used to 'drive' the application is entered.
There are two main sections: (i) 'Data Source Configuration', and (ii) 'ACTAtek Configuration'. There is also a 'Log Directory' field, which specifies where in the file system the 'Operational Log' files should be stored.
Before the application can be used, it must be configured correctly. This is done using the controls on the application's 'Configuration' tab, as shown below.
The application can store configuration data for multiple data sources, and for multiple ACTAtek units. The required data source and ACTAtek combination can then be selected from pre-configured lists, prior to a differencing or synchronization operation.
When the application is shut down, this configuration data is saved, and then recovered when the application is later re-started.
In the example shown below, an 'MS Access' database is being used as the primary source of user data:
Data sources can be added or removed from the application using the 'New' and 'Remove' buttons in the 'Data Source' box on the 'Configuration' tab. The active data source can then be selected using the 'Source' selector.
When a 'New' data source is added, a dialog is displayed which lists the types of data source that are available, and allows the new data source to be named.
The following types of data sources are supported; details of the configuration fields for each type of data source are given in Section 5.3:
Janus System.
Janus is a popular security management system which uses an SQL server 2005 database.
To add a Janus data source, the connection and authentication information for the Janus database are required.
DoorSynch can connect to the Janus DB using either: (i) Windows authentication, or (ii) SQL Server authentication, as required.
SQL Server 2005 Database.
To add an SQL Server 2005 database data source, the connection and authentication information for the SQL Server 2005 database are required, together with the names of the relevant source objects in the database (source table/field names, etc).
Note that this option can also be used to add a 'Janus' data source, if the names of the source data objects are known.
MySQL Databases.
To add a MySQL database data source, the connection and authentication information for the MySQL database are required, together with the names of the relevant source objects in the database (source table/field names, etc).
MS-Access Databases.
To add an MS-Access database data source, the location of the MS Access database on the file system is required, with optional authentication information, together with the names of the relevant source objects in the database (source table/field names, etc).
The table and field names can be selected from pull down lists that are automatically populated by DoorSynch when the 'Refresh Details' button on the MS-Access DB configuration control is pressed.
MS-Excel Spreadsheets.
To add an MS-Excel spreadsheet data source, the location of the source spreadsheet on the file system is required, together with the names of the relevant source objects in the spreadsheet (sheet/column names, etc)[1].
The sheet and column names can be selected from pull down lists that are automatically populated by DoorSynch when the 'Refresh Details' button on the MS-Excel Source configuration control is pressed.
The 'Headers Row' checkbox determines whether the first row in the spreadsheet contains the column / field names, or not, in which case generic names are used.
Note that a '$' symbol is automatically appended to the source sheet names when they are mapped to candidate table source objects.
LDAP Servers.
This option is available from DoorSynch v 2.1.
CSV Files.
To add a CSV file data source, the location of the source CSV file on the file system is required, together with the names of the relevant source fields in the file.
Note: it is assumed that the first row in the CSV file contains the names of the file's data fields.
The appropriate field names can be selected from pull down lists that are automatically populated by DoorSynch when the 'Refresh Details' button on the CSV File Source configuration control is pressed.
ACTAtek units can be added or removed from the application using the 'New' and 'Remove' buttons in the 'ACTAtek box' on the 'Configuration' tab. The active ACTAtek unit can then be selected using the 'ACTAtek' selector.
The connection information that must be entered for an ACTAtek unit comprises the unit's: (i) Network address, (ii) Login id, (iii) Password, and (iv) The connection protocol to be used.
If non-standard ports are used for http/https (which default to 80 and 443), then the port number can be appended onto the unit's network address in the usual way.
Once the connection information has been entered, the 'Group' and 'Department' selection lists can be populated, this is done by pressing the 'Refresh Lists' button on the ACTAtek configuration control.
Once these lists are populated, the default 'Department' and default 'Group' can be selected from these lists. These settings determine the department and group to which any new users that are added to the ACTAtek are assigned.
Note
There is interplay between the 'Department' and 'Group' selections in an ACTAtek. The groups that are available may depend on the department that has been selected. So, when the 'Department' selection is changed, the choices in the 'Group' selector are automatically refreshed.
The following table provides details about the configuration fields available in 'DoorSynch'.
Table 1. Fields on The DoorSynch 'Configuration' Tab
| Janus Data Source | ||
| Authentication | Pull down | The Janus database client authentication mechanism: 'Windows' or 'SQL Server'. |
| DB Server | Text Field | The name/address of the Janus database's host machine. E.g. 'locahost' for the local machine. |
| DB Login | Text Field | The 'user id' to be used to log in to the Janus database. This may be left blank for 'Windows' authentication, and then the active Windows user account is used. |
| Password | Password Field | The 'password' to be used to log in to the Janus database. This may be left blank for 'Windows' authentication, provided that the 'DB Login' field is also left blank. Note: the letters of the password are displayed as asterisks. |
| SQL Server 2005 Data Source | ||
| Authentication | Pull down | The database client authentication mechanism: 'Windows' or 'SQL Server'. |
| DB Server | Text Field | The name/address of the database's host machine. E.g. 'locahost' for the local machine. |
| DB Login | Text Field | The 'user id' to be used to log in to the database. This may be left blank for 'Windows' authentication, and then the active Windows user account is used. |
| Password | Password Field | The 'password' to be used to log in to the database. This may be left blank for 'Windows' authentication, provided that the 'DB Login' field is also left blank. Note: the letters of the password are displayed as asterisks. |
| Source Table | Text Field | The name of the source table (or view) to be used in the database. |
| User Key Field | Text Field | The name of the field in the source table/view to be used as the unique user key by the Actatek unit. |
| Surname Field | Text Field | The name of the field in the source table/view which contains the user's surname. |
| Forename Field | Text Field | The name of the field in the source table/view which contains the user's forename(s). |
| Card SN Field | Text Field | The name of the field in the source table/view which contains the user's card serial number. Note: this serial number must be in decimal form. |
| MySQL Data Source | ||
| All Fields | - - - - - - - - - - | These are the same as for the 'SQL Server 2005' data source type. |
| MS Access Data Source | ||
| DB File Path | File Chooser / Text Field | The location of the MS Access database file to be used. |
| Protected | Checkbox | Whether the Access DB is protected, and requires client authentication information. |
| DB Login | Text Field | The Access DB login to be used, this is only required if 'Protected' is checked. |
| DB Password | Password Field | The Access DB password to be used, this is only required if 'Protected' is checked. Note: the letters of the password are displayed as asterisks. |
| Source Table | Pull down | As per the SQL Server 2005 database data source. |
| User Key Field | Pull down | " " |
| Surname Field | Pull down | " " |
| Forename Field | Pull down | " " |
| Card SN Field | Pull down | " " |
| MS Excel Data Source | ||
| XLS File Path | File Chooser / Text Field | The location of the MS Excel spreadsheet file to be used. |
| Headers Row | Checkbox | This sets whether or not the first row in the spreadsheet contains field names. |
| Source Table | Pull down | The name of the datasheet in the xls file to be used as a source data table. |
| User Key Field | Pull down | The name of the column in the selected datasheet that contains the unique user key to be used by the ACTAtek unit. |
| Surname Field | Pull down | The name of the column in the selected datasheet that contains the user's surname. |
| Forename Field | Pull down | The name of the column in the selected datasheet that contains the user's forename(s). |
| Card SN Field | Pull down | The name of the column in the selected datasheet that contains the user's card serial number. Note: this serial number must be in decimal form. |
| CSV File Data Source | ||
| File | File Chooser / Text Field | The location of the CSV file to be used. |
| User Key Field | Pull down | The name of the field in the CSV file that contains the unique user key to be used by the ACTAtek unit. |
| Surname Field | Pull down | The name of the field in the CSV file that contains the user's surname. |
| Forename Field | Pull down | The name of the field in the CSV file that contains the user's forename(s). |
| Card SN Field | Pull down | The name of the field in the CSV file that contains the user's card serial number. Note: this serial number must be in decimal form. |
| ACTAtek Connection | ||
| Address | Text Field | The network address for the ACTAtek unit. |
| Login ID | Text Field | The account to be used to log in to the ACTAtek unit. Note: it is recommended that a dedicated DoorSynch Administrator account is set up on ACTAtek, rather than using an existing 'Administrator' or 'Super Administrator' account. |
| Password | Password Field | The password for the ACTAtek account to be used. Note: the letters of the password are displayed as asterisks. |
| Protocol | Pull down | There is a choice of 'http' or 'https'. Https uses SSL to encrypt the communications between DoorSynch and the ACTAtek unit. |
| (Default) Department | Pull down | This sets the default 'Department', to which any new users are assigned when they are added to the ACTAtek unit by DoorSynch. |
| (Default) Group | Pull down | This sets the default 'Group', to which any new users are assigned when they are added to the ACTAtek unit by DoorSynch. Note that the contents of the 'Group' selection list are dependant on the chosen 'Department'. |
| Operational Logging | ||
| Log Directory | Directory Chooser / Text Field | This is the directory into which DoorSynch writes its operations log files, for example: 'C:\DoorSynchAppLogs'[a]. |
[a] Note: if both the 'DoorSynch' application and the 'DoorSynch' service are used together, it is recommended that they use separate directories to store their log files. | ||
The following sections describe how to use the DoorSynch application.
To view the user set for the chosen data source/system, you must first ensure that the data source's configuration is set correctly, then select the 'Source Data' tab and click on the 'Load' button.
The user data will then be displayed as a (read only) table, as shown below:
To view the user set for the chosen ACTAtek, you must first ensure that the ACTAtek's configuration information is set correctly, then select the 'ACTAtek Data' tab and click on the 'Load' button.
The user data will then be displayed as a (read only) table, as shown below:
Once the application has been properly configured, select the 'Update Actatek' tab and click the 'Differences' button within the 'Operations' box.
This will query both the selected data source/system and the selected ACTAtek unit, and produce a user difference table. This table shows the set of user update operations that are required to synchronize the ACTAtek unit's user set with that of the chosen data source.
There are three types of 'User Update Operation' that are defined:
Add User.
A user record has been found in the data source that is not in the ACTAtek, and needs to be added to the ACTAtek.
Remove User
A user record has been found on the ACTAtek which is not in the data source, and needs to be removed from the ACTAtek.
Nothing
This is shown when a user record has been found in the ACTAtek unit which is not in the source system, but will not be removed because it is classed as 'exceptional'. This might, for example, correspond to an ACTAtek management or superuser account[2].
Note
If an ACTAtek user record does not have a 'Card SN' value defined, then it is flagged as an 'exceptional' case, and it is not deleted.
To do this, select the 'Update Actatek' tab, and click the 'Run Update' button in the 'Operations' box.
This will first populate the 'difference table', and then perform the set of Add/Remove operations required to synchronize the Actatek's user set with the chosen data source.
As this process executes, the progress bar on the tab indicates how far the update has progressed, and the 'Door Users' box provides a summary of the user changes made to the ACTAtek unit.
The DoorSynch 'Update' process uses a 'delta' algorithm, which computes the differences in the user sets between the data source and the ACTAtek unit, and then performs a series of operations on the ACTAtek to add or remove users. This approach is both efficient, and well suited to the API provided by ACTAtek units.
Note
When computing the differences, DoorSynch only compares the sets of user keys in the two systems.
There is also a 'retry' algorithm built-in to the update process, to overcome any short-term problems that might occur while updating the ACTAtek. For example, if a user update operation should fail due to a temporary network instability, then the update would be 're-tried' several times before being flagged as a failure.
DoorSynch removes users from the ACTAtek if:
The user appears in the ACTAtek unit, but not in the data source/system, and
The user has a CardSN value set on the ACTAtek unit[3].
DoorSynch adds a new user to the ACTAtek unit if:
The user appears in the data source/system, but not in the ACTAtek unit.
Note
Provided a user's key remains the same, then if their data on the ACTAtek is modified after it has been added by DoorSynch, then these changes will not be over-written by DoorSynch on subsequent runs.
For example, if a user's settings have been changed on an ACTAtek to give them membership of a different group, then these changes will not be lost when the next synchronization occurs.
When a user is added to the ACTAtek unit, the following data fields are assigned:
Table 2. Data Fields Set within ACTAtek When a New User is Added
| ACTAtek Field Value | Source Value |
| User ID | This is taken from the assigned 'User Key' field in the source system. Note: for a 'Janus' source system, the 'CardNumber' field is used to provide the user key. |
| First Name | This is taken from the assigned 'FirstName' field in the source system.[a] |
| Last Name | This is taken from the assigned 'SurName' field in the source system. |
| Other Name | Not Set. |
| Card SN | This is taken from the assigned 'Card SN' field in the source system. Note: The data source must supply this as a decimal number. DoorSynch converts this value to the appropriate Hexadecimal representation required by ACTAtek. Note: for a 'Janus' data source, the 'CardId' field is used. |
| Departments | A single department, taken from the 'Default Department' selector on the 'Configuration' tab. |
| Groups | A single group, taken from the 'Default Group' selector on the 'Configuration' tab. |
[a] Where necessary, the first and last names passed to ACTAtek are truncated to 20 characters in length, which is ACTAtek's name length limit. | |
When DoorSynch adds a new user to an ACTAtek, the status of that user is immediately set to 'Active', and their swipe card access is also enabled.
DoorSynch maintains two separate types of logs:
A Windows Event Log.
An Operations Log.
The Windows Event Log
DoorSynch writes logging entries to the RCRT Windows event log, which is shared by all RCRT Windows applications.
Events and Errors that are logged include:
DoorSynch application start-up events.
ACTAtek update events.
Errors that occur in the DoorSynch application.
The RCRT Windows event log can be viewed using the MS Windows 'Management Console', as shown below[4].
This event log can also be viewed using the 'View Log' item in the DoorSynch application's 'Event-Log' pull down menu. This launches the DoorSynch application's own event log viewer.
Note that, 'clicking' on an entry in this viewer will launch a separate dialog which shows details of the selected event. Both of these dialogs are shown below:
The DoorSynch Operations Log
DoorSynch maintains an 'Operations Log' which provides an audit-trail of the user update operations that are performed on ACTAtek units.
These logs are stored as xml files on the host machine's file system; the directory where the files are stored is set using the 'Log Directory' field in the application 'Configuration' tab.
A new log file is automatically created every month and named accordingly. For example, the log file for July 2007 was called: 'AppOperationsLog_Jul2007.xml'.
These logs can be viewed using the 'Operation Logs' tab on the DoorSynch application. This provides the ability to load and view, either the latest log, or any previous log file.
The main security issues that are raised by the use of the DoorSynch application, excluding any additional issues specific to the ACTAtek units and data sources/systems themselves, are as follows:
Access to the DoorSynch application is controlled by Windows account security, it is not separately password protected. Clearly, the machine/account hosting the application should not be left unguarded.
If DoorSynch's host terminal were left open, then any login ids could be read directly from the DoorSynch application, however, all passwords are obscured on the user interface.
Communications with external data sources are protected by the relevant security mechanisms, often an authenticated login and a secured communications channel. In addition, where DoorSynch is installed on the same machine as a data source, then no data will be transmitted between them over the network.
However, DoorSynch does usually communicate with ACTAtek units over a network using the SOAP protocol, which transmits requests and responses encoded as xml.
These xml packets are 'readable'; consequently, if standard http communication is used, then there is a risk that a 'network sniffer' could intercept and acquire the message contents.
In situations where this is a concern, DoorSynch can be configured to use the https protocol[5]; data will then be transmitted to and from the ACTAtek in an encrypted format using SSL.
This option can be selected using the 'protocol' selector in the 'ACTAtek Configuration' section of the 'Configuration' tab.
[1] Note that 'password protected' spreadsheets are not currently supported.
[2] 'Nothing' operations are indicated in the 'Update Operations' table, but they are not stored in the DoorSynch operation logs.
[3] A user on the ACTAtek unit that does not have a CardSN assigned will not be removed by DoorSynch.
[4] On Windows XP, this can be opened by right-clicking on the 'My Computer' icon, and selecting 'Manage'.
[5] https is the application start-up default setting, this runs on port 443 by default.