DoorSynch Service v1.0
Copyright © Dr Andrew Gray
| Revision History | ||
|---|---|---|
| Revision 1.0 | 18-Feb-2008 | AJG |
|
DoorSynch Service 1.0 release. | ||
Abstract
DoorSynch Service is a .Net 2 Windows Service that enables users to synchronize the user sets of ACTAtek door access control units with a range of external data sources. This runs as a Windows Service, and can be configured to perform data synchronizations at regular intervals.
The data sources that are supported include: Janus systems, SQL Server 2005 databases, MySQL databases, MS-Access databases, Excel spreadsheets and CSV files. The software also includes a service management application, which can be used to configure and control the service.
This document describes how to install and use the 'DoorSynch' Windows service and its management application, which have been developed by RCRT in partnership with Cambridge ICT.
For more information, see: http://www.rcrt.co.uk
The purpose of the DoorSynch Windows service is to enable an ACTAtek door access control unit's user set to be automatically synchronized with an external data source or system at regular intervals.
This software comprises two parts: (i) The DoorSynch Windows Service, and (ii) The Service Management Application. The latter provides the ability to manage and control the service.
The data sources / systems that are supported by the DoorSynch Windows service 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 Windows Service enables this synchronization to be done automatically at predefined intervals, whereas the DoorSynch Windows Application allows process to be run 'on demand', as required.
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 software on a client machine, and unlock the software.
Section 4: Provides an overview of the DoorSynch Windows service.
Section 5: Provides an overview of the DoorSynch Windows service manager.
Section 6: Describes how to set-up and configure the DoorSynch Windows service.
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 Windows Service Management Application
ACTAtek units provide a SOAP XML Web Service API which allows external applications to interface with the unit, and manipulate its state.
The DoorSynch service communicates with ACTAtek using these web services, connecting via either standard http, or secure https transport.
The DoorSynch Windows service 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. This installer will install both the DoorSynch Windows service, and its associated management application.
When the service manager is first connected to the service[1], 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:
Product License Unlock Dialog
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.
Windows Services are run autonomously by the Windows operating system. This means that in effect they run 'in the background' while the computer is switched on. These services can be viewed, started and stopped[2] using the Windows 'Computer Management Console'[3], as shown below:
Microsoft Computer Management Console
Note
The Installer installs the DoorSynch Windows Service in 'Manual' Startup mode. If it is required that the service should start automatically when the computer restarts, then this should be changed to 'Automatic'.
Note
Windows services should not have any direct dependence on, or interaction with the Windows desktop.
This means that service management should be done indirectly, using separate applications which are able to communicate and interact with the services that they are responsible for.
The DoorSynch service manager provides the ability to start, stop and manage the DoorSynch Windows service. The manager is a separate application, and runs in a separate process to the service itself.
Note: this means that the manager can be started and stopped independently of the DoorSynch service.
The DoorSynch Manager communicates with the service using inter-process communications techniques, and is unable to function unless it is connected to the DoorSynch service.
This means that once the DoorSynch service manager has been started, and the service is itself running, the manager must be connected to the service. This is done using the manager's 'Connect' menu, as shown below:
The Service Manager's 'Connect' Menu
When the service manager is connected to the DoorSynch service, it establishes a communications link with service, and the manager's user interface then becomes active.
Note
When the DoorSynch Service is running a synchronization process, it must communicate with data sources, ACTAtek units, and (optionally) mail servers. This means that any firewall and other security software on the host machine must be configured to allow such traffic from the DoorSynch service, otherwise it will fail.
The DoorSynch service manager 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', 'Service', 'Connect', '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 manager's event log viewer when an error occurs.
The tab pages available on the application's main tab control are as follows:
'DoorSynch Configuration'
This tab page is where the configuration data that is used to 'drive' the data synchronization mechanism is entered, this information is essentially the same as for the 'DoorSynch' application.
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.
'Service Configuration'
This tab page is where the additional configuration data required by the service is entered. There are two sections: (i) Service Timer Configuration, and (ii) Service Notification Configuration.
The first section enables the synchronization process to be turned on and off, and configures how frequently it runs.
The second section allows the service to be configured to send out e-mails when updates and/or errors occur.
Operation Logs
This tab page allows a user to open and view the 'Operational Log' files that are maintained by the DoorSynch service.
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.
Last Update
This enables the user statistics for the last user synchronization to be viewed directly. If an update is currently underway, then the progress of the current update is shown.
Before the service can be used, it must be configured correctly. This is done using the controls on the two 'Configuration' tabs, as shown below. Note that any changes that are made to the configuration settings on the service manager do not affect the DoorSynch service until they are saved.
All of the configuration data is stored by the service itself, if the computer is shut down, then the service recovers this data when it re-starts.
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, when configuring the synchronization process.
In the example shown below, an 'MS Access' database is being used as the primary source of user data:
1. - The DoorSynch Synchronization Configuration Tab
2. - The Service Timer / Notification Configuration Tab
Data sources can be added or removed from the manager using the 'New' and 'Remove' buttons in the 'Data Source' box on the 'DoorSynch 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)[4].
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 Service v 2.
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 synchronization timer is configured on the 'Service Configuration' Tab; this also enables the synchronization timer to be switched on and off.
The e-mail notifier is also configured on the 'Service Configuration' tab; this enables the service to be configured to send out notification emails to either one or two recipients. This can be configured to use either authenticated or unauthenticated SMTP access, and has several notification options, as follows:
Off
No e-mails are sent out.
All Updates
An e-mail is sent out every time a synchronization is performed, whether or not any changes are made.
Change Updates
An e-mail is sent out every time a synchronization occurs that adds or removes a user to/from the ACTAtek.
Errors Only
An e-mail is only sent out if an error occurs in the synchronization process.
The following table provides details about the configuration fields available in 'DoorSynch'.
Table 1. Fields on the DoorSynch Configuration'Tabs
| 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]. |
| Service Timer Configuration | ||
| Service Timer | Pull down | There is a choice of 'Off' or 'On'. This sets whether the synchronization timer is enabled. |
| Timer Interval | Numeric and Pull down. | This sets the synchronization 'repeat' interval. The pull down units are: 'minutes', 'hours' or 'days' |
| Starting From | Date/Time chooser | This sets the date/time of the first scheduled synchronization run, and the reference point for the timer intervals. |
| Ending At | Checkbox and Date/Time chooser. | This is optional and maybe enabled/disabled using the checkbox. This sets the Date/Time of the last scheduled synchronization run. |
| E-Mail Notification Configuration | ||
| Notification | Pull down | There is a choice of: 'Off', 'All Updates', 'Change Updates' and 'Errors Only'. This sets the conditions under which e-mail notifications are sent out, as described previously. |
| SMTP server | Text Field | The network address of the SMTP server to be used to send e-mails. |
| Email From Address | Text Field | This sets the source e-mail address from which the notifications are to be sent. |
| Authentication | Checkbox | Determines whether or not SMTP authentication is to be used. |
| Use SSL | Checkbox | Determines whether an SSL connection is to be used with the SMTP server. |
| Login | Text Field | The SMTP server login. This is only required if 'Authentication' is enabled. |
| Password | Password Field | The SMTP server password. This is only required if 'Authentication' is enabled. |
| Send Address 1 | Checkbox / Text Field | The first e-mail address to send notifications to. The checkbox enables/disables this send address. |
| Send Address 2 | Checkbox / Text Field | The second e-mail address to send notifications to. The checkbox enables/disables this send address. |
| Send Test Mail | Button | This sends out a test email, using the settings that have been entered. |
[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 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[5].
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.
The DoorSynch service and manager maintain 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 start-up events.
ACTAtek update events.
Errors that occur in DoorSynch.
The RCRT Windows event log can be viewed using the MS Windows 'Management Console', as shown below[6].
This event log can also be viewed using the 'View Log' item in the DoorSynch manager 'Event-Log' pull down menu, this launches the manager'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 Manager's Event Log Viewer
The Manager's Event Instance Viewer
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 service manager 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 front-end, 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[7]; 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] See section 5.
[2] The DoorSynch Windows service can also be started and stopped using the DoorSynch Windows service manager.
[3] This can be opened by 'right clicking' on 'My Computer', and then selecting 'Manage'.
[4] Note that 'password protected' spreadsheets are not currently supported.
[5] A user on the ACTAtek unit that does not have a CardSN assigned will not be removed by DoorSynch.
[6] On Windows XP, this can be opened by right-clicking on the 'My Computer' icon, and selecting 'Manage'.
[7] https is the application start-up default setting, this runs on port 443 by default.