1 Installation and Configuration

1.1 Introduction

Deploying and configuring SAFR and AMAG Symmetry will allow SAFR to import AMAG person records and credentials to be used on SAFR SCAN face authentication readers. SAFR SCAN is using the imported face image, 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 person record, 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.

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

1.2 Integration Overview and Requirements

Integrated SAFR - AMAG Symmetry is available on Windows and Linux.

Please note that this Guide does not include the Installation of the SAFR Server (SAFR Platform) or the AMAG with Symmetry. This guide specifically describes:

Configure Symmetry to allow SAFR server to import People and Access Credentials from Symmetry.

Configure the External Identification Synchronization in SAFR server.

A typical integration architecture:

1.2.1 Attribute mapping between AMAG and SAFR

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

AMAG	SAFR (People data record)	Notes
First Name	First Name
Last Name	Last Name
n/a	Person Type (default “none”)	SAFR defaults all Person Type records to “None”.
Picture	Picture	If no picture in person record, import only name and credentials for use with card only access.
PIN	PIN
Card Format	Access Card Format
Facility code	Access Card Facility ID
Card Number	Access Card ID
Active Date	Access Activation	Record not added until Active Date is reached.
Inactive Date	Access Expiration	SAFR Expiration set to same if before Inactive Date. If after Inactive date, record not added.

One card is imported for each card assigned to a card holder. Each card is stored in the same SAFR person record.

1.3 Symmetry Configuration

SAFR integration to AMAG requires the AMAG Data Connect module which requires license from AMAG. It is also required to setup DataConnect Export and create a user with permissions to export data. These are described below.

No additional license or software is required on the SAFR server.

1.3.1 AMAG Module Licensing

The Data Connect modules must be installed on AMAG with an accompanying AMAG license. Follow the following for the Data Connect .

1. Log in to Symmetry as a user with the System Manager role. (There is a default user called Manager; its password is the same as its username but with lower case m.)
2. Click the Maintenance tab.
3. Under Licensing select System Licenses.
4. Click Add.
5. Enter the serial number from the license PDF file for the Data Connect module.

One license is applied, you should now see a Data Connect Module License added.

6. Log out of Symmetry and back in to apply this change.

1.3.2 DataConnect Export Setup

Log in to Symmetry as a user with the System Manager role. (There is a default user called Manager; its password is the same as its username but with lower case m.)

Select Operation, then Data, then Data Export.

Select all items that need to be exported and click OK.

Following are the minimum options required by SAFR:

IMPORTANT: If card holders have multiple cards, make sure to check Multiple Cards > Extended Support as shown.

1.4 SQL Server Configuration

The following tasks are best done using SSMS (SQL Server Management Studio) which is freely downloadable from this link: Download SQL Server Management Studio (SSMS).

After you have installed the management studio, log in using Windows credentials.

1.4.1 Enable SQL Server Authentication

SAFR only supports SQL Server Authentication. If not already enabled, SQL Server as follows.

Open SSMS and right click on the SQL Server entry and select “Properties” as shown below.

Select “Security” page and set Server authentication to “SQL Server and Windows Authentication mode” as shown.

Restart SQL Server in Windows Services Control Panel for this change to take effect.

1.4.2 Add Export SQL User

Account must use SQL Server authentication. Windows Authentication is not supported.

Expand out the Security section, right click on Login, and select New Login…

Choose and enter a Login Name and Password. Also disable the password policy, expiration, and/or change checkboxes . Please note that the login name entered here will also be the login name that it used when configuring SAFR to connect to AMAG for External Identity Synchronization.

• Use SQL Server authentication. Windows authentication is not supported.
• Enabling “Enforce password expiration” is allowed but administrator will need to ensure to update password and update SAFR configuration at the required intervals.

Click OK.

Expand “Logins” and open the new user just created.

Select User Mapping, check multiMax and multiMaxExport databases. Then select each database you just added and select db_datareader for both in the “Database role membership” list below.

Click OK.

1.4.3 Grant Permissions

Expand

Right-click on each database (multiMax and multiMaxExport) and click properties.

Select Permissions and click on the username created in the earlier step. Then scroll to the “Execute” Permission in the “Explicit” list below and click “Grant” as shown:

Click Ok

Open properties again for that database and view the “Effective” tab. Ensure at least following effective permissions are present.

The permission is added from the Explicit tab as described above. Generally, all permissions except EXECUTE are already present.

Repeat Step 8 thru 11 for multiMaxExport database.

Click OK to save changes.

1.4.4 SQL Server Port

SQL Server can be configured for static or dynamic ports. Default is static port on port 1433. Take note of the port SQL Server port for use when connecting SAFR below.

If using dynamic ports, omit the port number from SAFR’s Connection settings and include SQL Server Instance Name in the Host address as shown below in Setup External Identity Synchronization.

See https://learn.microsoft.com/en-us/sql/tools/configuration-manager/tcp-ip-properties-ip-addresses-tab for more information.

1.5 Configuring SSL

AMAG and SAFR must be use the same communication protocol. By default SAFR is configured to use HTTPS and trust the SSL Certificate on the SQL Server which works with most deployments.

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)

1.5.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 amag.properties”).

7. Open amag.properties file located in following locations (See SAFR Configuration File below)
   Windows: C:\Program Files\RealNetworks\SAFR\covi\app\config\covi
   Linux: /opt/RealNetworks/SAFR/covi/app/config/covi
8. Edit the following line

amag.trust.server.certificate:true

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

1.5.2 Disable SSL CERT Validation

1.5.2.1 Disable SSL CERT Validation in SAFR (use HTTP)

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

amag.ssl:auto:disabled

3. Set value to ‘disabled’ to disable SSL (use HTTP).
4. Save amag.properties file
5. Restart “SAFR Covi” Windows Service in the Windows Services Control Panel (if on Linux, run ‘stop’ and ‘start’ in the SAFR/bin directory).

If disabled, SQL Server must be configured to allow HTTP.

1.6 Set up External Identification Synchronization

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

6. Open SAFR Software (either SAFR Desktop or SAFR Server Web Console)
7. Open System Configuration page
   1. SAFR Desktop: Tools menu > System Configuration
   2. SAFR Server Web Console: Click on “Status” page
8. Scroll down Remote Control and Sync Configuration: section

9. Enter information for the following fields:

User directory name	The name of your SAFR database name where users and events are stored. Default is ‘main’.
External identity host	Select AMAG from the drop-down menu.
Host Address	The IP address or hostname of the AMAG SQL server. If using dynamic ports, SQL Server instance name should also be appended (usually MSSQLSERVER). For example: 10.124.12.55\MSSQLSERVER SAFR does not connect to netbios names. If you have netbios name of AMAG Server, you can get the ip address by executing following in a DOS command window: > Nbtstat.exe -a NETBIOSNAME Where “NETBIOSNAME” is the netbios name of your AMAG Server.
Host Port	The port number that the target AMAG SQL Server is listening on. If using “TCP Dynamic Ports”, leave the field empty (ghost text of 1433 will show but will not be used). See SQL Server Port above for more information. “TCP Port” is be configured in the SQL Server IP Addresses configuration tab. If you know what the current dynamic port is, SAFR will connect to that port until next time it is updated, but this is not recommended because incremental sync will stop working at some point.
Host User Id	The User Id should be the same Login name created above in section 1.3.3 ”Add Export SQL User”.

Host Password: The Password should be the password entered above in 1.3.3. “Add Export SQL User”.

10. Click the Apply button.

1.7 SAFR Configuration File

The following file defines custom properties specific to AMAG Sync

Filename: amag.properties
Location: C:\Program Files\RealNetworks\SAFR\covi\app\config\covi

## Defines mapping from AMAG Credential format ID to either built-in or custom
## SAFR Card Format Name. Ensure each entry has form of "SAFR_NAME:AMAG_FMT_ID".
## AMAG Credential Formats located in
## Install > System > Default Settings > Credential Formats configuration screen.
amag.card.format.mappings={'Legacy:0','PIV FASC-N:1','SR Series (15 digit):2','SR Series (10/12 digit):3','CMV_U:4','CMV_F:5','HID SE:6','HID Corporate:7','Barcode 37:8','NXP Desfire 56:9','AMAG – 62:10','AMAG – 32:11','AMAG – 63:12','HID Corporate 35:13'}

## Setting this will limit import to only those persons who are assigned cards
## with these card formats IDs as defined in AMAG Credential Formats located in
## Install > System > Default Settings > Credential Formats configuration screen.
## Formats occurring first in the array have priority over those appearing later.
## Identities without any of the card format IDs are not imported and
## are deleted if imported previously.
## Uncomment to enable this filter.
## amag.card.format.filter={1, 5}

amag.integrated.security=false
amag.encrypt=true
amag.trust.server.certificate=true
amag.ssl.protocol=TLSv1.2

## Changing this will set access facility id (AMAG Customer Code) on all people
## imported. Uncomment to enable
## amag.facility.id.override=123

1.7.1 Card Format Mapping

The card.format.mapping list defined the string that, if matched to an existing SAFR card format (either builtin or custom) will appear in the SAFR person record.

Builtin card formats can be found in the Card Format configuration in the Person settings page (Tools > People > Edit Person > Card Format dropdown) or SAFR SCAN Reader Operation Settings (Tools > Video Feeds > Feed … menu > Operation Settings > Card Format > Card Format dropdown).

Custom Card Formats can be added to the Card Format dropdown by first defining them in Feed Default (Tools > Video Feeds > main … menu > Set Feed Defaults

2 Operation Guide

2.1 Synchronizing People

Person synchronization is automatic. Person records and their credentials are copied from AMAG Symmetry 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 Symmetry are copied to SAFR.

From then on, records added to Symmetry are copied to SAFR.

Records in SAFR are NOT copied to Symmetry.

Changes to records in Symmetry are updated in SAFR.

If record is changed in SAFR, a warning is displayed and sync to Symmetry will be disabled for that record.

Only records with access credentials and image will be copied to SAFR.

Removing credentials or the image in the Symmetry results in the record being removed from SAFR.

Setting record to inactive in Symmetry removes the record from SAFR.

Below describes the process (which is automatic).

1. Add a person in AMAG.

That person record and the corresponding credentials are be copied to SAFR and viewable in SAFR Person Window.

2.2 Card Format

SCAN reader card format config must be set to match the card format imported by AMAG. Moreover, only 1 card format can be supported at once.

Here is an example of how to set SCAN custom card format for the following AMAG 37 bits card format:

SCAN custom card format:

It’s important to mention that for people imported as "Legacy" and SCAN card format set as AUTO - No data will be sent to the Panel.

3 Troubleshooting

Questions or comments about the documentation? Email us at [email protected] .

3.1 Connection Error when Connecting to AMAG Server

3.1.1 Connection Errors

There are a few reasons you may get connection errors. First check, the hostname and port of the SQL Server are accurate. Also ensure that the username and password are correct as sometimes this is misreported as a connection error.

• Invalid TLS Certificate Errors
  • If you get the following error, see Configuring SSL above.
    • Connection Failed: Invalid TLS Certificate Errors
• SQL Server is using “TCP Dynamic Ports” and not listening on port 1433 (default) or the port has changed from when initially configured. See SAFR Host Port in Setup External Identify Synchronization section above for more details.
• SQL Server account is configured for Windows Authentication.
  • Windows Authentication is not supported. Only SQL Server Authentication is supported by SAFR. Using Windows Authentication results error: Connection Failed: Unreachable.

3.2 How to check record count

1. Open SQL Server Management Studio, connect to your server
2. Select “New Query with Current Connection” from File menu.
3. Run the following 2 queries.

Regular Cardholders for both SE and HSE

SELECT COUNT(DISTINCT CH.CardID)
FROM [multiMAX].[dbo].[ViewCardHolderTable] As CH,
[multiMAX].[dbo].[ViewCardInfoTable] As CR
WHERE CH.CardID = CR.CardID
AND Inactive = 0
AND ForcedInactive = 0
AND IndividualForcedInactive = 0
AND Lost = 0

Visitor Cardholders

SELECT COUNT(DISTINCT V.CardID)
FROM [multiMAX].[Reporting].[Visitors] As V,
[multiMAX].[dbo].[ViewCardInfoTable] As CR
WHERE V.CardID = CR.CardID
AND Inactive = 0
AND ForcedInactive = 0
AND IndividualForcedInactive = 0
AND Lost = 0

The sum of Regular Cardholders and Visitor Cardholders queries should be the same as the number of records in SAFR. If differing consult SAFR Support and include count generated by following query as well.

Regular Cardholders joined with Export Table (Only for AMAG Symmetry SE)

SELECT COUNT(DISTINCT CH.CardID)
FROM [multiMAX].[dbo].[ViewCardHolderTable] As CH,
[multiMAX].[dbo].[ViewCardInfoTable] As CR,
[multiMAXExport].[dbo].[DataExportTable] AS EX
WHERE CH.CardID = CR.CardID
AND EX.CardNumber = CR.CardNumber
AND Inactive = 0
AND ForcedInactive = 0
AND IndividualForcedInactive = 0
AND CR.Lost = 0

3.3 Debug Logging

SAFR Logs external sync activities for debugging purposes. This section describes location of and how to control the output to the external synchronization log file.

External Synchronization log file is in the following locations:

Windows: C:\Program Files\RealNetworks\SAFR\covi\logs\ext-sync.log
Linux: /opt/RealNetworks/SAFR/covi/logs/ext-sync.log

You will also find archived versions (compressed and prefixed with date) in the logs directory. These may be needed if requested by support.

The following line controls logging level for external synchronization. By default the logging level is 'WARN' as shown below.

<logger name="com.real.rpcloud.covi.sync.external" level="WARN" additivity="false">

If asked by support, the level can be changed to DEBUG or TRACE by changing level as shown below:

<logger name="com.real.rpcloud.covi.sync.external" level="DEBUG" additivity="false">

3.4 Check Card Format Issues

If AMAG does not appear to be receiving credentials when SCAN shows access granted message, try the following.

Make sure that SAFR SCAN I sending credentials by enabling debug logging.

1. Open SAFR SCAN Web Console
2. Add “&debug=1” to the URL as in:
   
3. Click on the “Logs” tab at top of page
4. Perform a transaction (present face or card)
5. Click Refresh button and view latest log output.

Example of a successful Card and Face Authentication:

2024-Sep-09 22:08:00.026511: INFO/accessCredential(547633302800): processPcscCardread(): cardFormatData.format=Wiegand-26, cardFormatData.layout=, cardFormatData.parity=, cardFormatData.byteOrder=normal
ATR[20]:3b 8f 80 01 80 4f 0c a0 00 00 03 06 40 00 00 00 00 00 00 28
UID[4]:0f 93 44 80
PACS[4]:0f 93 44 80
PACS padding_bits: 6
2024-Sep-09 22:08:00.026859: INFO/accessCredential(547633302800): processPcscCardread(): Received Wiegand-26: FacilityCode=31, CardID=9865,
2024-Sep-09 22:08:00.694637: INFO/accessCredential(547633302800): receive_gpio_ttl_aux1_in: messageValue=0
2024-Sep-09 22:08:00.708613: INFO/accessCredential(547633302800): Use credentialData.accessCardRawBytes for cardDataOut.
CardDataOut[4]:0f 93 44 80
Padding_bits: 6
2024-Sep-09 22:08:00.708926: INFO/accessCredential(547633302800): sendCardDataOut(): Sending out 26 bits of Wiegand-26 card data to wiegand-out...OK
2024-Sep-09 22:08:01.238326: INFO/accessCredential(547633302800): receive_gpio_ttl_aux1_in: messageValue=1
2024-Sep-09 22:08:10.065342: INFO/accessControl(547623298704): Access Denied: Control panel feedback or control panel timeout

The log shows a card read, the card number and raw data sent over the Wiegand wiring and the panel feedback received via the LED wires. The message “Sending out 26 bits of Wiegand-26 card data to wiegand-out...OK” indicates that SCAN successfully sent data to the panel and panel should have received it.

If SAFR is sending data, but panel is still not acknowledging a card read, the card format may be not what the panel is expecting. To see if any data is received on the panel, open the following dialog and resubmit the request to.

Where:

• Lines with CV is a grant access (e.g. p=0CXaaaaasss000)
• Lines with CX is a denied (e.g. p=0CXaaaaasss000)

1