Releezme System Requirements

Terms and abbreviations

AD                   : Active Directory

AAD                 : Azure Active Directory

References

Reference Title Version
RZM_035 Releezme Customer Data Import (Interface Specification Document) 1.4
RZM_070 Releezme on-premises minimum system requirements
RZM_123 Releezme ImportClient infrastructure diagram

1.1. Introduction

Releezme is the product name of the latest software generation from Vecos. It consists of a server component (in the cloud or on premises) and optionally an import client application that always runs on premises. This document contains the system requirements for the import client.

1.2. Purpose of this document

The purpose of this document is to give the reader a general understanding of the system requirements and the data required for optimal operation of the import client.

1.3. Out of scope

The total system consists of hardware, server software and client software. The hardware (Locker Block Controller, HUB and locks) and related software, and the server software are out of scope for this document.

2. System overview

The Releezme Import Client Service takes care of synchronizing user data from the customer system (users, group membership, badges) to the Releezme server. It is a Windows service that runs on- premises at the customer, regardless of whether the Releezme server runs in the cloud or on- premises.

The ImportClient Windows Service consists of two main parts:

  1. The basic ImportClient (pictured in orange in Figure 1) which maintains user data to be imported in a local database and transfers this data at regular intervals in batches to the Releezme Server via a secured https
  2. The optional DataCollector (pictured in blue in Figure 1) which regularly queries 1 external data source (pictured in purple in Figure 1) for the current user/group/badge data. It then forwards the added/updated/deleted items to the basic ImportClient, which will in turn send them to the Releezme server.

Currently the following external data sources are supported:

  • Active Directory / LDAP
  • CSV file
  • Table or view in MS SQL Server

Besides the DataCollector, the Import database offers an API (a set of stored procedures) that allows third party applications to Add/Update/Delete users and badges.

The conceptual Import Cache database and Import database (see Figure 1) reside in a single Microsoft SQL Server database that runs on-premises at the customer. This database contains a history of the completed/in-process/failed user data records and cached data from the external data source.

The ImportClient and DataCollector are implemented in a single Windows Service that runs on an on- premises server that has access to the Import databases, and if applicable, also has access to the external data source (e.g. Active Directory, CSV file).

The ImportClient authenticates itself to the Releezme server using a company specific access token. As a one-time setup action, this access token is generated on the Releezme server and stored in the configuration file of the ImportClient. The access token is sent with every https request to the web service and grants access to exactly the configured company account on the Releezme server.

3. System requirements

3.1. Server requirements

The Releezme ImportClient Service can run on one physical or virtual (VMware or Hyper-V) machine. In a full on-premises installation, it is recommended to use the same application server and SQL server as used by the Releezme server software. In that case, refer to the minimum system requirements for a full on-premises installation in document RZM_070.

The performance of the import mechanism is greatly influenced by the performance of the SQL server.

For installation an internet connection is not required, i.e., all required additional software is contained in the installation package. However, typically the installation is performed remotely by the Releezme team, so a (temporary) remote desktop connection is desirable.

The Releezme ImportClient Service consists of several components, which rely on additional Microsoft software components (not by default contained in Windows (Server)). These software components are to be supplied and maintained by the customer.

Component Purpose Microsoft software component
Releezme ImportClient Service Mandatory requirements for all components Windows 10 Pro x64 / Windows Server 2012 R2 x64 Standard / 2016 x64 Standard

.Net Framework 4.6.2

Installation Software Required components for installation itself SQL Server Management Studio (at least the same generation as the used SQL Server)
Applications Releezme ImportClient that runs as a service
Database Data storage SQL Server 2014 or 2016, Express or higher (locally or remote)

Table 1: Releezme ImportClient software components

The following table indicates a typical setup:

System Component
Operating system Windows 10 Pro 64bit / Server 2012 R2 Standard 64 bit
CPU 2 CPUs (or 2 vCPUs), minimal 2 GHz
Internal memory 2 GB internal memory (4 GB recommended)
Storage 5 GB free disc space
Ethernet connection Gigabit

 

SQL Server SQL Server 2014 Express Edition or Standard Edition

Table 2:Typical setup

3.2. Database requirements

This section describes the database that the Releezme ImportClient application uses for the ImportDB/ImportCache. See the External SQL section below for the requirements of the external datasource SQL Server.

The Releezme ImportClient application requires a SQL Server 2014 or 2016 installation, Express Edition or Standard Edition (or higher).

  • Operation

The ImportClient can access the database in two ways:

  • SQL Server Authentication
    • Credentials stored in connection string in ImportClient config file
  • Windows Authentication
    • ImportClient must run-as the Windows user. Note that it may not always be possible to combine this with some of the SQL datacollector authentication options (see section 3.4)
  • Installation

During the installation phase, a (possibly separate) user must be available that has sufficient rights to be able to deploy the DACPAC for the Releezme.Import database.

To be able to install DACPAC’s, the following is defined by Microsoft (https://msdn.microsoft.com/en- us/library/ee634742.aspx#Permissions):

“A DAC can only be upgraded by members of the sysadmin or serveradmin fixed server roles, or by logins that are in the dbcreator fixed server role and have ALTER ANY LOGIN permissions. The login must be the owner of the existing database. The built-in SQL Server system administrator account named sa can also upgrade a DAC.”

When the same user is used for both installation and operation, then after installation the rights to the database login user can be reduced to “public”. Note: for system upgrades, the rights must be set back again as specified above.

  • Backup

Backup/restore of the database is the customer´s responsibility, procedure to be discussed during installation of Releezme.

3.3. Connectivity requirements

The Releezme ImportClient Service periodically opens a TCP/IP connection to the Releezme server (on-premises or in the cloud). Depending on the type of datacollector, additional connections to internal customer systems (e.g. Active Directory) may be applicable.

The Releezme ImportClient Service uses at least these outgoing ports:

Component Port Target
Releezme Import API 443 (HTTPS) To Releezme server (either in the cloud or on-premises)
Import db SQL Server 1433 (TCP) To internal Import database SQL Server
Datacollect from external

source

Depends on source type Depends on source type

Refer to RZM_123 for an infrastructure overview that lists all connections, ports, protocols and target hostnames.

The customer must ensure that the Windows firewall allows the required connections.

During installation and initial configuration, and incidentally for diagnostics or support, Vecos requires a remote connection to the server via RDP, TeamViewer or other solution.

3.4. Security requirements

  • Vecos advises to install anti-virus and anti-malware software
  • Updates and patches for Microsoft software is the responsibility of the customer
  • Backup/restore of the database is the responsibility of the customer, procedure to be discussed during installation of Releezme
  • Ensuring that the files/databases on the server are protected from unauthorized access is the responsibility of the customer

4. Input data

There are multiple possibilities to import data into Releezme that each have their own requirements for the input data. Only one of these methods can be used per installation. The validity and completeness of the input data is the responsibility of the customer. Exact specifications are discussed during preparation of installation.

4.1. Data collector

Each type of datacollector periodically accesses the configured external datasource and reads users, group memberships, badge information and locker allocations according to configured filters/mappings. The resulting data is considered to be the full truth; i.e. the customer is responsible for providing the complete set of user/badge data.

The datacollector then calculates the delta between this set of data and the previous data. Only the added, changed or deleted items are transformed into import commands and queued for transmission to the Releezme server.

There is limited support for situations where the customer provides only the added or updated entries, instead of the full truth.

When a failure occurs during reading of the external datasource (e.g. I/O error, authorization failure, not all configured fields available etc) the datacollect run is aborted and no changes are sent to the Releezme server. The datacollector then waits for the next configured trigger time to run again.

The complete mapping of user group identifiers in the customer’s datasource and their corresponding identifier on the Releezme server must be configured during setup in the ImportClient. This requires the full set of possible user group identifiers to be known before setup begins.

4.2. Field mapping

The datacollector configuration can map exactly 1 field from each input row to 1 of the following Releezme fields.

Releezme field Man- datory Length (characters) Format Description
User Unique Identification Yes Max 255 ASCII characters only, no special accents/characters Uniquely identifies each user. Must be unique within the company.

Note: before R1.6 the max was 50 characters.

 

FirstName Max 50 UTF8
Insertion Max 20 UTF8 In the name ‘Jan de Vries’, ‘de’ is an

insertion.

LastName Max 50 UTF8
EmailAddress Max 255 Must be a valid email

address, or empty

PhoneNumber Max 15 Digits, -, +, ( and ) only Note: before R1.9, a minimum length of 6 was required.
User group Membership Max 1024 UTF8 Semicolon separated list of name of the user groups that this user is a member of. Please discuss the set of

accepted user groups beforehand.

BadgeNumber Yes Max 20 Must consist of hexadecimal characters (0-9, A-F), A-F must be

uppercase.

The ‘technical’ value that is read by the badge reader on the locker terminal. Must be unique within the company.
Printed Cardnumber Max 50 UTF8 Descriptive text that is printed on the physical card. Can be a different value than the technical

badgenumber.

LockerFullDoorNumber Max 20 UTF8 Full locker number, including prefix and leading zeroes (e.g. A0001).

Must be unique within a location.

LockerLocation Max 255 UTF8 Location of the locker. Please discuss the set of accepted locations beforehand.

4.3. Specific data collector requirements 

  • Active Directory (AD)

The AD datacollector periodically connects to exactly 1 AD server via LDAP or LDAPS and retrieves the current set of relevant users, group memberships and badges according to one or more configurable LDAP queries and filters. The mapping of AD attributes to Releezme fields is fully configurable. Releezme user group membership can be based on AD attributes, AD group membership or organizational unit (OU) membership. The credentials for the AD server are stored encrypted with the machine key.

The following is required for the AD datacollector:

  1. One user is represented by exactly one AD entry. When applicable, user group membership values and/or badgenumbers must be included as attributes of those AD
    1. The names of those attributes must be equal for all AD
    2. The values of those attributes are expected to be formatted as UTF-8
    3. Binary attribute values are interpreted as UTF-8 text. This means for instance that GUIDs as binary values are not
  2. A read-only AD user account with rights to the relevant part of the domain
  3. An LDAP v3 compatible AD host that is accessible from the server where the ImportClient service
  4. Detailed overview of which users in which AD groups and/or OUs need to be included, and any types of entries that need to be excluded (e.g. service accounts, inactive users).
  5. Detailed overview of which AD attribute maps to which Releezme field
  6. Detailed overview of which user groups need to be recognized and to which Releezme user groups they map
  7. Only basic/simple authentication is supported, a.o. GSS-API is not
  • Azure Active Directory (AAD)

The AAD has the same requirements and functionality as the AD datacollector but communicates using LDAPS (secure LDAP) instead of LDAP.

On top of the AD requirements, the following is required for the AAD datacollector:

  1. Azure AD Domain Services is installed and configured in the Azure environment. For details see https://docs.microsoft.com/en-us/azure/active-directory-domain-services/configure-ldaps
  2. Password hash synchronization to Azure AD Domain Services is enabled for the user that is used for connecting to the AAD
  3. LDAPS is configured for Azure AD Domain Services managed domain
  4. The LDAP certificate is valid and installed on the server (Local Computer>Personal store) where the import client is installed
    1. This can either be a self-signed certificate or a certificate from a public CA or enterprise CA
  5. The LDAP certificate from step 4 is installed in the Azure AD Domain Services
  6. In case of a public CA or enterprise CA, the DNS needs to be updated that the LDAPS client can connect to the LDAPS service (e.g. ldaps.releezme.net needs to point at the external LDAPS access IP). The IP to be used can be found at Azure Portal > Azure AD Domain Services > Properties > Secure LDAP external IP address
    1. The import client can also connect to an IP address for a self-signed certificate, so the Azure internal managed domain (e.g. releezmeorg.onmicrosoft.com) does not have to be able to be translated to an IP
  • CSV file

The CSV data collector periodically reads exactly 1 CSV file from exactly 1 configured path and filename. This CSV file is considered to be the full truth: it always contains exactly all currently relevant users and badges. The format of the CSV file as well as the mapping of CSV columns to Releezme fields is highly configurable: delimiter character, file encoding etc. Each row in the file (except the optional header) represents one user and optionally contains the associated badge and/or user group membership(s).

The following is required for the CSV datacollector:

  1. A file location that is accessible by the ImportClient service (on an actual drive on the application server, or on a mapped file share accessible via drive letter)
  2. File read access on the input file for the account under which the service runs
  3. A mechanism at the customer side that periodically replaces the CSV file with a fresh file containing the new
  4. The file must be encoded as UTF8, UTF16, 7-bit ASCII or ANSI using the application servers’ codepage.
  5. The customer mechanism must make sure that the file is locked for reading while refreshing the file, to prevent the ImportClient from reading an incomplete
  6. Detailed overview of the CSV format (header yes/no, meaning of columns, encoding, quotes)
  7. Detailed overview of which user groups need to be recognized and to which Releezme user groups they map
  8. Detailed overview of which columns map to which Releezme fields
  • External SQL

The SQL datacollector periodically connects to exactly 1 MS SQL Server instance and retrieves the current set of relevant users, groups and badges from a configurable table or view in a configurable database. The mapping of SQL columns to Releezme fields is fully configurable. The credentials for the SQL server are stored encrypted with the machine key.

The following is required for the SQL datacollector:

  1. A Microsoft SQL Server (2005 or higher) (Express Edition or higher) accessible by the ImportClient. This can optionally be the same server as the SQL Server that hosts the ImportDB/ImportCache, but it has to be a different database.
  2. A table or view in the configured database where each row contains exactly the data for one user and optionally his badge and/or user group membership(s).
  3. The ImportClient connects to the database via:
    1. An SQL Server user account with read rights to the relevant database
    2. A domain account that has read rights to the relevant database
      1. ImportClient service must run under this account, using Windows Integrated Security
    3. A local Windows account that has read rights to the relevant database
      1. ImportClient service must run under this account, using Windows Integrated Security
      2. SQL Server instance must run on the same machine as ImportClient
    4. Detailed overview of which user groups need to be recognized and to which Releezme user groups they map
    5. Detailed overview of which columns map to which Releezme fields

4.4. Direct Stored Procedures API

The customer can call a set of stored procedures in the Import database to add, update or delete users and badges. In this case it is the full responsibility of the customer to maintain and cleanup the user data.

This mechanism is described in document RZM_035.

The following is required for the Stored Procedures API:

  1. A separate database user with read/execute rights in the local Import database
  2. Detailed overview of which user groups need to be recognized and to which Releezme user groups they map

5. Monitoring

5.1. Direct stored procedures API

Every Import record that is added via a direct stored procedure call (e.g. AddOrUpdateUser) returns a unique record identifier for that record. This identifier can later be used to request the current status of that record via the GetLocalRecordStatus stored procedure. When the record failed (local validation failed, or rejected by the server) the result of the stored procedure contains a result reason.

5.2. Data collectors

When using datacollectors, the record identifier is not known by the customer, so the stored procedure from section 5.1 can’t be used. Currently (R1.5) there is no dedicated stored procedure to get an overview of the record statuses yet.

(Note: although the customer has access to the internal tables in the Import database on their own on- premises server, the structure of these internal tables is not guaranteed to remain consistent for future versions, so it is not advised to rely on them.)

6. Checklist

This section gives a comprehensive checklist of all the items from this document that the customer is required to prepare.

Server:

  • Virtual (or physical) server
  • Windows 10 Pro x64 or Windows Server 2012 R2 x64 Standard / 2016 x64
  • Windows must have language set to
  • .Net Framework 4.6.2 or higher
  • SQL Server 2014 / 2016 Express or higher (local or remote)
  • SQL Server Management Studio (at least the same generation as the used SQL Server)
  • All Windows updates and relevant Microsoft updates installed
  • 2 (v)CPUs, minimum 2GHz
  • Minimum 2GB RAM (4GB when SQL Server runs on the same server)
  • 5 GB free disk space
  • Gigabit network connection

Accounts (general)

  • An account that can run the ImportClient Windows service (can be Local System account when Integrated Security is not used)
  • Operational public read/write/execute access to the Import SQL database
    • Via SQL Server Authentication (SQL login)
    • Or via Windows Integrated Security (Local or domain user account)
  • SysAdmin/ServerAdmin SQL login during installation and upgrades, for deploying DACPAC

Accounts (datacollector)

  • CSV datacollector: the account that runs the ImportClient service requires read access for the CSV file (see section 3.2 for details)
  • SQL datacollector: SQL login or local/domain account with read rights for the source server/database (see section 3.4 for details)
  • AD datacollector: readonly AD account with access to the relevant part of the domain tree (see section 3.1 for details)

Connections

  • Outbound HTTPS access via port 443 to https://iapi.releezme.net (for Europe) or https://iapi-au.releezme.net (for Australia)
  • Internal connections to SQL server and datacollector source
  • During installation and initial configuration, and incidentally for diagnostics or support, Vecos requires a remote connection to the server via RDP, TeamViewer or other remote collaboration

Security

  • Anti-virus and anti-malware software
  • Installing updates and patches for Microsoft software
  • Backup/restore of the Import database
  • Ensure that the files/databases on the server are protected from unauthorized access

Input data

  • Choose exactly 1 input method: datacollector AD, CSV or SQL, or direct stored procedures API
  • Detailed overview of which user group identifiers need to be recognized and to which Releezme user groups they map
  • For datacollectors: detailed overview of which input field maps to which Releezme field
  • Refer to the corresponding section in section 3 for input method specific requirements