1 SAFR - Genetec Synergis Integration Guide

1.1 Introduction

Deploying and configuring SAFR and Genetec Security Center (GSC) with Synergis 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.

Please note that SAFR will not import a person record if it does not have a card access credential. Likewise, if the access credential is removed from the cardholder, SAFR will delete the person record in SAFR. SAFR only supports one card access credential per person record. If multiple credentials exist, the most recently updated credential is imported.

To integrate and use the SAFR SCAN RTSP video feed in Genetec Security Center for surveillance please see the SAFR Genetec Integration Guide.

For complete SAFR and SAFR SCAN documentation please visit http://docs.real.com.

1.2 Integration Overview and Requirements

Integrated SAFR - Genetec Synergis is available on Windows and Linux.

Please note that this Guide does not include the Installation of the SAFR Server (SAFR Platform) or the Genetec Security Center (GSC) with Synergis. This guide specifically describes:

  1. Configure GSC to allow SAFR server to import Cardholders and Access Credentials from Synergis.
  2. Configure the External Identification Synchronization in SAFR server.

A typical integration architecture:

1.3 Attribute mapping between Genetec and SAFR

The following is the current imported and supported attributes/field from GSC


SAFR (People data record)


First Name

First Name

Last Name

Last Name

OwnerRoleType in Genetec Credential

Person Type

“Card Holder” if OwnerRoleType not defined.



Email Address


Mobile Phone Number



Access Activation


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.3.1 Import Behavior

  • If deleted in Genetec, SAFR will delete the record.
  • Only access card credentials assigned to a person are imported.
  • SAFR imports the most recently updated credential for each cardholder.
  • For cardholders with Wiegand 26, the Facility code and Card Number is populated in SAFR. For all other card formats, the facility code and card number are populated in the Access Card ID field as a raw card number. Use Raw Card Format in SAFR SCAN for the cases.

1.4 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.4.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.5 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.5.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”.

Graphical user interface

Description automatically generated

4. The following specific privileges will need to be set for SAFR synchronization.

In Application privileges.

Log on using SDK 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.

  1. Application privileges.
    1. Log on using SDK

  1. Administration privileges - -> Access control management
    1. View access rules properties
    2. View badge template properties
    3. View cardholder group properties
    4. View credential properties
    5. View visitor properties

  1. Task privileges --> Maintenance
    1. Audit trails

1.6 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:

  1. Open the Genetec Config Tool.
  2. Open Tasks > Administration > Access Control > General Settings.
  3. 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.7 Enable Web SDK

SAFR is using the Genetec Web SDK for Cardholder synchronization.

  1. Add the Web SDK to Roles.
    1. System -> Roles. Click on Add an Entity and select Web based SDK. See image below.

  1. By default, SAFR uses SSL. To configure Web SDK for SSL enable it in Web SDK UI. The default port is 4590 and will need to match the port in the SAFR External Identity Synchronization configuration. See image below.
    1. 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.8 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 an SSL CERT issued by a trusted authority. If Genetec is using a self-signed CERT (default), you will see the following error when trying to connect.

A screenshot of a computer screen

Description automatically generated

You can resolve this issue in one of three ways:

Install an SSL Certificate issued by certificate authority such as Thawte.

Refer to Genetec documentation

Configure SAFR to use internal trust manager which will truest self-signed CERTs.

See section 1.8.1 below

Configure SAFR and Genetec to use HTTP (Disable SSL)

See section 1.8.2 below

1.8.1 Use Self-Signed CERTS

To enable SAFR’s internal trust manager, modify SAFR Configuration and restart SAFR Server as instructed below.

  1. 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”).
  1. 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
  2. Edit the following line


  1. Set value to true to implicitly trust cert (do not validate) Genetec SSL CERT.
  2. Save genetec.properties file
  3. Restart “SAFR Covi” Windows Service in the Windows Services Control Panel (if on Linux, run ‘stop’ and ‘start’ in the SAFR/bin directory).

1.8.2 Disable SSL CERT Validation Disable SSL CERT Validation in SAFR

  1. Open genetec.properties as described in steps 1 and 2 of section 1.8.1 above.
  2. Edit the following line


  1. Set value to ‘disabled’ to disable SSL (use HTTP).
  2. Save genetec.properties file
  3. Restart “SAFR Covi” Windows Service in the Windows Services Control Panel (if on Linux, run ‘stop’ and ‘start’ in the SAFR/bin directory). Disable SSL CERT Validation in Genetec
  1. Open Genetec Config Tool
  1. Go to Gentec > System > Roles > Web-based SDK
  2. Set “Use SSL Connection” to “Off”

1.9 Set up External Identification Synchronization

To set up identity synchronization between SAFR and Gentec, do the following:

  1. Open SAFR .
  2. 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:

A screenshot of a computer

Description automatically generated with medium confidence

  1. 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.
  2. Click the Apply button.

1.10 SAFR Configuration File


Located in the SAFR application folder under covi\app\config\covi

C:\Program Files\RealNetworks\SAFR or /opt/RealNetworks/SAFR

## DEV/Alternate:
## external.sync.client.genetec.application.id:


## external.sync.genetec.default.ptype:Card Holder
## external.sync.genetec.override.access.clearance:#{null}
## external.sync.genetec.override.access.clearance.level:#{null}
## external.sync.genetec.page.size:250

## genetec.federated.full.sync* forces full sync once a day
## genetec.federated.full.sync.enabled:false
## genetec.federated.full.sync.hour:2
## IF genetec.federated.full.sync.enabled == false, the following
## will indicate duration between full sync, default 7 days:
## genetec.full.sync.frequency.millis:604800000

## auto, enabled, disabled

## changing this will set access facility id on all people imported
## genetec.facility.id.override=123SUCCESS

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 Troubleshooting

3.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.
  • 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 1.8 above to enable SSL Self-signed CERTS or HTTP for the Web SDK.

4 Genetec Federated Systems

4.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.

4.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.

4.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.

  1. SAFR does not do incremental synchronization of Federated Cardholders.
  2. 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.
  3. For the initial synch, SAFR external synch should not be established until all the Cardholders are federated to Host.
    1. 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.
      1. 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.
      2. Deleted Cardholders + Credentials in Genetec will be immediately deleted in SAFR.
      3. New Cardholders will be added to SAFR based on the full synch configuration.
      4. Please contact your SAFR contact person to customize the full synchronization schedule.

Questions or comments about the documentation? Email us at safr-doc-feedback@realnetworks.com .