1 SAFR - Genetec Cardholder Integration Guide
1.1 Introduction
The SAFR SCAN integration with Genetec Security Center allows for real-time, high-accuracy biometric authentication, ensuring that only authorized individuals gain access to restricted areas. Deploying and configuring SAFR and Genetec Security Center (GSC) will allow SAFR to import Genetec Cardholders and Credentials to be used on SAFR SCAN face authentication readers. SAFR SCAN is using the imported Cardholder picture, converted into a biometric signature, to verify a person identity when presented at a SAFR SCAN reader. When a person’s identity has been verified the SAFR SCAN reader transmits the imported Access Credentials to the access control panel via Wiegand or OSDP signaling.
This guide describes how to configure SAFR Software and Genetec to import Cardholders and Access Credentials into SAFR SCAN or SAFR Camera devices. This guide does not describe how to configure SAFR SCAN to transmit credentials to panel and receive panel feedback. Please refer to SAFR SCAN documentation for information on setting up SAFR SCAN to format and transmit credentials to the panel.
To integrate and use the SAFR SCAN RTSP video feed in Genetec Security Center for surveillance please see the SAFR Genetec VMS Integration Guide.
For complete SAFR and SAFR SCAN documentation please visit http://docs.real.com.
1.2 System Requirements
Genetec has the following system requirements:
- One machine running Genetec Security Center Version 5.7 or later.
- WebSDK Role enabled
- 1 Genetec License for each camera (Part# GSC-1SDK-REALN-FR)
SAFR has the following system requirements:
-
SAFR Platform Version 3.27 or later
- Each machine running the SAFR Server must meet the following requirements:
- Windows 10, Windows Server 2016 or later
- i5 or Xeon Silver 4216 or faster with at least 4 cores allocated to SAFR Computer
- 16 GB System RAM
- 1 TB Storage
- For systems running more than 50 SAFR SCAN, please consult SAFR Technical Support at support@safr.com or http://support.safr.com
1.3 Integration Overview
1.3.1 Integration overview
Please note that this Guide does not include the Installation of the SAFR Server (SAFR Platform) or the Genetec Security Center (GSC) with Synergis.
1.3.2 Traditional Genetec Integration vs. Genetec RIO Integration
SAFR SCAN supports two integrations to Genetec. Both integrations pull cardholders and credentials from Genetec and push that data to SAFR SCAN readers for purposes of authenting a person in order to grant access. They differ as follows:
- Traditional Integration – SAFR SCAN transmits credentials to a panel which unlocks the door.
- RIO Integration – SAFR SCAN is a full door controller. It unlocks the door and performs door state and REX function. This information is transmitted back to CloudLink.
Following explains the data flow for each integration.
As described above, both integrations leverage Genetec Security Center directory server to push cardholders and credentials to SAFR SCAN. This is performed through SAFR Server which acts as proxy. They then differ as described below.
1.3.2.1 Traditional Integration
Once a person is authenticated, SAFR SCAN sends the cardholder’s credentials over Wiegand or OSDP. On the Genetec side you’ll see an access event with name and door reported. It will be granted or denied based upon the access rules associated for that person. Genetec then returns access denied or access granted disposition to SAFR SCAN over the OSDP or Wiegand wires. SAFR uses the panel feedback to display access granted or access denied. SAFR gets the feedback for Wiegand over the green LED and LED red wires (only single wire is required, LED red is optional). If OSDP SAFR SCAN get the feedback over the same two wires that it sent the credentials.
1.3.2.2 RIO Integration
Once a person is authenticated, SAFR SCAN takes one of two actions:
- If operating in empowered mode, the door is unlocked directly through SAFR SCAN’s dry contact normally open or normally closed relay.
- If operating in cooperative mode, SAFR SCAN sends credentials to Cloud Link via IP Networking and receives a granted or denied response from Cloud Link. SAFR SCAN then takes appropriate action on the door.
In both cases, door state and REX state are returned to Cloud Link. SAFR SCAN acts directly on REX actions by unlocking door locally.
1.4 Attribute mapping between Genetec and SAFR
The following is the current imported and supported attributes/field from GSC
Genetec |
SAFR (People data record) |
Notes |
First Name |
First Name |
|
Last Name |
Last Name |
|
OwnerRoleType in Genetec Credential |
Person Type |
“Card Holder” if OwnerRoleType not defined. |
Image |
Image |
|
Email Address |
|
|
Mobile Phone Number |
Phone |
|
Activation |
Access Activation |
|
Expiration |
Access Expiration |
When expiration is reached, SAFR will generate Access Denied before sending credentials to panel. Record is not deleted. |
Credential Card Format |
Access Card Format |
|
Credential Facility code |
Access Card Facility ID |
Only for cardholders with Wiegand 26. |
Credential Card Number |
Access Card ID |
If multiple card credentials exist for person, only the most recently added or updated credential will be added to person record in SAFR. |
Credential PIN Code |
PIN Credential |
If multiple PINs exist for person, only the most recently added or updated PIN will be added to person record in SAFR. |
1.4.1 Import Behavior
- If deleted in Genetec, SAFR will delete the record.
- Only active card credentials assigned to a person are imported.
- SAFR will not import a person record if it does not have a card access credential.
- If the access credential is removed from the cardholder, SAFR will delete the person record in SAFR.
1.5 GSC Synergis Licensing
SAFR use the Genetec WEB SDK to connect and synchronize cardholders. The SAFR Part number # license must also be installed on GSC to enable this functionality and a “safrsync” user with required permissions needs to be created in Genetec. These are described below.
No additional license or software is required on the SAFR server.
1.5.1 GSC Licensing and the Genetec Part Number
An accompanying Genetec part number for SAFR integration must be added to your Genetec connection license (it is the same license and part number as for SAFR video feed integration) It currently comes in three options based on number of connections. For cardholder synchronization only one license is required per SAFR server.
Part number “GSC-1SDK-RealN-FR1”. Please ask your Genetec representative for the license.
1.6 Configuring API Access
To create a SAFR user in Genetec to synchronize the Cardholders and Credentials a minimum set of privileges will need to be set. If you would like to use one of the Genetec Privilege Templates you will need to use either “Provisioning” or “Administrator”. The specific privileges that need to be applied are documented below in section 1.2.2.1.
1.6.1 Create SAFR Sync User
The specific create a user with the permissions that SAFR will require, do the following:
1. Open the Genetec Config Tool.
2. Click Tasks > User Management.
3. Create a new user (for example, “safrsync”) based on the Privilege template “Supervisor”.
4. The following specific privileges will need to be set for SAFR synchronization.
• In Application privileges.
▪ Log on using SDK
1.6.1.1 Set Privileges for SAFR user
If you create a user without an assigned privilege template, the following specific privileges will need to be set for SAFR synchronization.
-
Application privileges.
- Log on using SDK
-
Administration privileges - -> Access control management
- View access rules properties
- View badge template properties
- View cardholder group properties
- View credential properties
- View visitor properties
-
Task privileges --> Maintenance
- Audit trails
1.7 Set Minimum Cardholder Image Size
It is important to have a good quality images loaded into Genetec to eliminate any false positives and faster face matching times. For optimal performance of SAFR SCAN reader, a face image size of 220 pixels ear-to-ear is required.
The Genetec settings for Maximum picture size does not take into consideration face size pixel density but instead the raw size of the picture. Assuming pictures uploaded are typical head profile shots or selfies we record to set the Maximum picture file size to 200KB. Please check with your Genetec representative to make sure your system is sized for this.
Do the following:
- Open the Genetec Config Tool.
- Open Tasks > Administration > Access Control > General Settings.
- Set Maximum Picture File Size to 200 kb or larger.
Note: File size is not a great predictor of image quality but that’s the only control Genetec provides. Even a 40 kb image can be good quality if cropped just to the face.
1.8 Enable Web SDK
SAFR is using the Genetec Web SDK for Cardholder synchronization.
-
Add the Web SDK to Roles.
- System -> Roles. Click on Add an Entity and select Web based SDK. See image below.
By default, Genetec has SSL enabled with Self-signed CERTs as shown in screenshot below. SAFR is configured to work with this configuration by default.
The default port is 4590 and will need to match the port in the SAFR External Identity Synchronization configuration.
If for some reason you cannot connect via SSL and would like to use unsecured http, please follow the steps outlined in the Troubleshooting section below to disable SSL in SAFR.
1.9 Configuring SSL
Genetec and SAFR must be use the same communication protocol. SAFR can be configured to handle the following conditions.
- SSL (HTTPS) with SSL CERT issued by trusted CERT Authority
- SSL (HTTPS) with self-signed SSL CERT
- No SSL (HTTP)
By default, SAFR is configured to expect a self-signed SSL CERT which is the Genetec default.
1.9.1 Use Self-Signed CERTS
To enable SAFR’s internal trust manager, modify SAFR Configuration and restart SAFR Server as instructed below.
-
Open a text editor with elevated permissions (“Run as administrator”)
- ?Notepad++ is a good text editor for Windows and will automatically elevate permissions when needed.
- ?On Linux use sudo to elevate permissions with editor of your choice (e.g. “sudo vi genetec.properties”).
-
Open genetec.properties file located in following locations (See section 1.10 below)
Windows: C:\Program Files\RealNetworks\SAFR\covi\app\config\covi
Linux: /opt/RealNetworks/SAFR/covi/app/config/covi - Edit the following line
genetec.trust.server.certificate:true
- Set value to true to implicitly trust cert (do not validate) Genetec SSL CERT.
- Save genetec.properties file
- Restart “SAFR Covi” Windows Service in the Windows Services Control Panel (if on Linux, run ‘stop’ and ‘start’ in the SAFR/bin directory).
1.9.2 Disable SSL CERT Validation (HTTP)
1.9.2.1 Disable SSL CERT Validation in SAFR
- Open genetec.properties as described in steps 1 and 2 of section 1.8.1 above.
- Edit the following line
genetec.ssl:disabled
- Set value to ‘disabled’ to disable SSL (use HTTP).
- Save genetec.properties file
- Restart “SAFR Covi” Windows Service in the Windows Services Control Panel (if on Linux, run ‘stop’ and ‘start’ in the SAFR/bin directory).
1.9.2.1.1.1 Disable SSL CERT Validation in Genetec
- Open Genetec Config Tool
- Go to Gentec > System > Roles > Web-based SDK
- Set “Use SSL Connection” to “Off”
1.10 Set up External Identification Synchronization in SAFR
To set up identity synchronization between SAFR and Genetec, do the following:
- Open SAFR
- Click on the Tools menu in the client UI, select the System Configuration tool from the drop-down menu.
Check the Set up External Identity synchronization box. The following dialogue will appear:
-
Enter information for the following fields:
- User directory name: The name of your SAFR user directory.
- External identity host: Select Genetec from the drop-down menu.
- Host Address: The IP address or hostname of the target Genetec server that is running the Web-based SDK Role. This can be different from the directory server.
- Host Port: The port number that the target Gentec server is listening on.
- Host User Id: The User Id (“safrsynch” if used above) of a user who has the credentials to log into the Genetec server.
- Host Password: The Password of a user who has the credentials to log into the Genetec server.
- Click the Apply button.
1.11 SAFR Configuration File
External Identity synchronization with Genetec are customized via configuration file. Available properties are documented in genetec.properties as described below. To ensure configuration changes are persisted during SAFR upgrades, place any customized properties into the persistent.overrides.properties file.
To view available configuration options along with documentation on their behavior:
-
Go to COVI config directory located in
- C:\Program Files\RealNetworks\SAFR\covi\app\config\covi
- /opt/RealNetworks/SAFR/covi/app/config/covi
- Open ‘genetec.properties’
- Review documentation for each property
- Copy desired properties from genetec.properties
- Paste the line into persistent.overrides.properties
2 Genetec Synergis Operation Guide
2.1 Synchronizing People
Person synchronization is automatic. Person records and their credentials are copied from Genetec Synergis to SAFR Server and from there pushed to all readers. Synchronization occurs continually in the background.
SAFR will synchronize people and credentials as follows:
- At initial connection time, all records pre-existing in Synergis are copied to SAFR.
- From then on, records added to Synergis are copied to SAFR.
- Records in SAFR are NOT copied to Synergis.
- Changes to records in Synergis are updated in SAFR.
- If record is changed in SAFR, a warning is displayed and sync to Synergis will be disabled for that record.
- Only records with access credentials will be copied to SAFR.
- Removing credentials or the image in the Synergis results in the record being removed from SAFR.
- Setting record to inactive in Synergis removes the record from SAFR.
Below describes the process (which is automatic).
1. Add a person in Synergis.
2. Add credentials in Synergis
3. That person record and the corresponding credentials are be copied to SAFR and viewable in SAFR Person Window.
3 Genetec Federated Systems
3.1 About Genetec Federation and Identity Sync
Genetec recommendations Federated systems are not the method to be used to manage Cardholders and Credentials centrally. Cardholders and credentials should be created and managed at each federation site and SAFR should be connected to each federated site to synchronize Cardholders and credentials.
Per Genetec subject matter expert on the subject:
Federation is meant as a monitoring tool to bring entities and event data from remote systems into a head end system, such as a GSOC or HQ. Federation is not intended as a means to administer multiple systems.
Although it is possible to give a Federated cardholder local access it is not recursive, meaning the Federation Host cannot grant access to doors at a remote site. Any additional credentials given to a Federated cardholder stay on that local system and are not saved on the source system.
If a customer wants to manage cardholders globally from one location, we typically recommend ClearID or a system design where all Cloudlink devices communicate with a single system. Global Cardholder Management is a last resort and not often recommended or deployed.
There are other options, such as the cardholder sync plugin that could be deployed, but those would be created as local cardholders to the system where the plugin is deployed.
At the end of the day, if you are trying to solve for the Federated model, each system should contain a unique set of cardholders, or should all be synced with the same source (AD or database view), so hopefully you wouldn’t have to worry much about replicated cardholders. If a particular customer chooses to deploy your solution, and their system architecture poses an issue, we should discuss it before deployment.
3.2 SAFR Architecture with Genetec Federated Systems
Cardholders and credentials should be created and managed at each federation site and SAFR should be connected to each federated site to synchronize Cardholders and credentials.
In below diagram, a separate instance of SAFR is connected to each local Genetec Security Center server. No cardholders are managed in the central Genetec Federation server.
This configuration requires a SAFR License Account for each instance of SAFR. This does not incur additional costs but requires that multiple license requests be submitted, one for each SAFR Server.
3.3 SAFR Behavior with Genetec Federation
While not recommended, SAFR maybe connected a Genetec Federation Host. This section describes the behavior when doing so. The recommended configuration (SAFR Server connected to local Genetec Synergis Servers) will result in best performance for both full synchronization and incremental synchronization.
SAFR will synch federated Cardholders from the Federated Host (meaning the Federated Host has cardholders from the Federated system(s)) with the following caveats.
- SAFR does not do incremental synchronization of Federated Cardholders.
- An initial synch will import all Cardholders and credentials that are federated to the federated Host. Thereafter, SAFR can be configured to run a full cardholder synchronization on a regular schedule that will pick up any edits and changes that have been made to the Cardholders since the last synch.
-
For the initial synch, SAFR external synch should not be established until all the Cardholders are federated to Host.
-
There is a race condition where the cardholder and credential are loaded before the picture. Safr’s frequent synch will grab the cardholder and credential before the picture is available on the Host and will not update the record with the picture until next full synch.
- Any changes/edits that are made to existing cardholders on federated system are immediately updated on the federated Host but SAFR is not importing (incremental synch) any changes to existing Cardholders until next full synch.
- Deleted Cardholders + Credentials in Genetec will be immediately deleted in SAFR.
- New Cardholders will be added to SAFR based on the full synch configuration.
- Please contact your SAFR contact person to customize the full synchronization schedule.
-
There is a race condition where the cardholder and credential are loaded before the picture. Safr’s frequent synch will grab the cardholder and credential before the picture is available on the Host and will not update the record with the picture until next full synch.
4 Troubleshooting
4.1 Synchronization connection errors in External Identification Synchronization
- Make sure port 4590 (default port) is not blocked by any firewall in the network as well as the local firewall on the GSC server. See Test Connection to Genetec WebSDK below.
- Make sure the Genetec SAFR license is applied in Genetec.
- Make sure when connecting to GSC that the address is the ip address of the Server that is running the Web-bases SDK Role. (see the resource tab of the web-based SDK role)
- SSL error. See section Error! Reference source not found. to enable SSL Self-signed CERTS or HTTP for the Web SDK.
4.2 Test Connection to Genetec WebSDK
To verify if there is network connectivity from SAFR Server to Genetec WebSDK, do the following:
- From the computer running SAFR Server, open a DOS command window
- Enter the following command
telnet 10.124.14.20 telnet
If successful, you will see following output
If unsuccessful, you will see output with "connection failed" such as the following:
⚠️ If installing SAFR and Genetec on same PC, using localhost to connect to Genetec may not work if Genetec is not listening on localhost. If you get “Server unreachable” error, try the IP address instead of localhost.
Questions or comments about the documentation? Email us at safr-doc-feedback@realnetworks.com .
1