ETR Web Server Configuration

Introduction

This manual describes the configuration of the server-side components of the GBS ETR. The GBS ETR is an application that allows the user to analyze and handle exceptions generated by the GBDS.

The configuration procedure should be done only after the installation step. For more information, consult the GBS Apps Installation Manual.

Configuration

The configuration steps are:

1. Configure the Tomcat;

2. Configure the Certificates;

3. Generate the Encrypted Password;

4. Enable the Best of Biometrics;

5. Configure the Keys and Biographics shown;

6. Configure the Label Highlighting;

7. Configure the Allowed Treatments;

8. Configure the Web Access;

9. Configure the PSBIO Environment;

10. Configure the Lights Out;

11. Configure other properties of config.properties;

All steps are described below.

Tomcat Configuration

Edit Tomcat's configuration file to configure the certificates and the port the application will use.

vi /var/lib/tomcats/etr/conf/server.xml

To change the port, search for connector port=. This is the port for backend operations.

Certificates Configuration

To enable SSL authentication, search for connector port= in the file /conf/server.xml.

There are two entries. The commented one is the configuration for SSL. Remove the comment delimiters <!-- and -->, then adjust the following parameters:

port="58194"
keystoreFile="/home/griaule/keystore"
keystorePass="password"
keyAlias="1"
clientAuth="true"
truststoreFile="/home/griaule/keystore"
truststorePass="password"

The parameter port must be the desired network port for the application.

Change the path of the keystoreFile and the truststoreFile to the appropriate values. Do the same for the keystorePass and the truststorePass.

The parameter clientAuth="true" will require server authentication to the client and client authentication to the server. This means the client will need to import the certificate into the browser to be able to access the application.

When clientAuth is set to true, the system administrator must provide the file certificate.pfx to end users.

Database Password Encryption

In the file config.properties, the parameter jdbc.password is an encrypted password. To generate the encrypted password, follow these steps:

1. Go to the following directory:

   cd /var/lib/tomcats/etr/webapps/gbs-etr-server/WEB-INF/lib

2. Run the command:

   java -cp gbs-common-db-<version>.jar com.griaule.commons.util.EncryptUtil <desiredPassword>

3. The encrypted password will appear after the message: "Encrypted password is:"

Save the encrypted password. It will be used in later configurations.

Enabling Best of Biometrics

Best of Biometrics is an operation applied when two or more profiles are merged or linked.

When applied, Best of Biometrics evaluates each fingerprint and palm template individually and selects the templates with the highest quality for each finger and/or palm position among all merged transactions. It then updates the person's profile to unify the "best" biometrics into a single active transaction that will be used for biometric comparison. This operation does not apply to Face and Iris templates, for which the most recent images will replace the older ones regardless of quality.

Best of Biometrics is a feature available for GBDS and for the ETR. Although they perform the same function, they NOT are the same process and MUST NOT be together.

For more information, contact Griaule Support team.

To enable Best of Biometrics in the ETR, the database must have the parameters treat.multiMerge.consolidation and bob.trustedUpdate.active set as true.

To create and enable the parameters:

INSERT INTO `sphinx`.`settings` (`name`, `type`, `val`) VALUES ('treat.multiMerge.consolidation', 'ETR', 'true');
INSERT INTO `sphinx`.`settings` (`name`, `type`, `val`) VALUES ('bob.trustedUpdate.active', 'ETR', 'true');

To enable existing parameters:

UPDATE `sphinx`.`settings` SET `val`='false' WHERE  `name`='treat.multiMerge.consolidation' AND `type`='ETR';
UPDATE `sphinx`.`settings` SET `val`='false' WHERE  `name`='bob.trustedUpdate.active' AND `type`='ETR';

If Best of Biometrics is active and needs to be deactivated, use the following query:

UPDATE `sphinx`.`settings` SET `val`='false' WHERE  `name`='bob.trustedUpdate.active' AND `type`='ETR';

Configuring Keys and Biographics to Appear in the Exceptions List

The application shows keys and biographics on the exceptions list screen. It is possible to configure the fields that will be displayed (up to two fields), for example: CPF, idn, documentID, name and any other desired field.

To configure a new field, this field must be added to the MySQL database. Log in to the MySQL server using:

mysql -u<user> -p

Execute the following statement to check existing fields:

use sphinx;

select * from field;

Check the number of fields returned by the query. If you already have 7 fields, the order of the new one should be 8 for example.

Execute the following statement, changing the values accordingly:

INSERT INTO `sphinx`.`field` (`name`, `description_en_us`, `description_pt_br`, `description_es_es`, `field_type`, `field_kind`, `field_order`, `cardscan`) VALUES ('newField', 'descriptionEN', 'descriptionBR', 'descriptionES', 'string', 'KEY', '8', '1');

• newField = name of the field to be used

• descriptionEN = description in English

• descriptionBR = description in Portuguese

• descriptionES = description in Spanish

• string = the type of the value (string or integer) – keys and biographics can use string

• KEY = the type of the field: KEY or BIOGRAPHIC

• 8 = It is the order of the fields. Just increase the number from the fields that already exist (the current number was returned in the previous query)

• 1 = enable the field for cardscan. It is not necessary to change this value

Execute a GET request to the endpoint URL IP:port/config.

Copy the response (everything inside showFields).

Send a POST request to the same endpoint URL with the modified JSON settings (all desired fields must be provided - old fields and new fields, otherwise only the provided fields will be considered):

{
	"showFields": [
		{
			"name": "newField",
			"descriptionEnUs": "descriptionEN",
			"descriptionPtBr": "descriptionBR",
			"required": false,
			"type": "string",
			"kind": "KEY",
			"order": 0,
			"cardscan": true,
			"candidate-list": false
		},
		{
			"name": "name",
			"descriptionEnUs": "Name",
			"descriptionPtBr": "Nome",
			"required": false,
			"type": "string",
			"kind": "BIOGRAPHIC",
			"order": 0,
			"cardscan": true,
			"candidate-list": false
		}
	]
}

The correct response should be:

{
	"status": "OK"
}

Label Highlighting Configuration

The application shows labels when the user is analyzing an exception. It is possible to configure the highlight color of these labels.

Execute a GET to the endpoint IP:port/config.

Copy the response (everything inside the system configuration).

Send a POST to the same endpoint URL, changing the following item in the copied JSON:

{
	"highlightLabels": [
		{
			"label": "OWNED",
			"color": "#ff00f0"
		}
	]
}

In this case, the label OWNED will be highlighted with the specified color.

Allowed Treatments Configuration

The ETR uses the file /var/lib/tomcats/etr/conf/treatments.json to display the treatments that will be available for exception handling:

SAME_FINGERS, DIFFERENT_FINGERS, INCORRECT_ENROLL, MERGE, and RECOLLECT

Example:

{
	"key": "enroll.merge",
	"type": "ENROLL",
	"status": "MERGE_TRANSACTIONS",
	"enabled": true,
	"match-person-effect": "MERGE",
	"enroll-effect": "MERGE"
}

• The key value with type ENROLL can be: enroll.same_fingers, enroll.different_fingers, enroll.recollect, enroll.merge

• The key value with type UPDATE can be: update.same_fingers, update.different_fingers, update.incorrect_enroll, update.recollect, update.merge

To enable it: set the value to true. Otherwise, use false.

• The match-person-effect is the effect that will be displayed on the ETR screen for the reference person in the database. Available values: KEEP, DISCARD, MERGE, and BLACKLIST.

• The enroll-effect is the effect that will be displayed on the ETR screen for the incoming person via enrollment in the database. Available values: KEEP, DISCARD, MERGE, and BLACKLIST.

Application Configuration File

This section describes the possible configurations of the file config.properties. To access it, open it with:

vi /var/lib/tomcats/etr/conf/config.properties

An example of the file config.properties can be seen in the section Configuration File Example.

All lines must be present in the configuration file. Commenting out or deleting lines may cause unexpected behavior. For additional information, contact the Griaule Support Team.

ETR Configuration

This section will show some specific settings for the ETR and the IP and port configuration of the application that the end user will access. The IP and port must be the same configured in the Tomcat Configuration.

etr.ip=<ip>
etr.port=<port>
etr.protocol=<protocol>

Make sure the configuration parameters etr.ip, etr.port and etr.protocol are correctly specified in the file config.properties. In many cases, the IP will be the same for several applications. However, each application will have a different and unique port.

The double-check feature for the ETR can be disabled by executing the following query in the relational database: UPDATE `sphinx`.`settings` SET `val`='false' WHERE `name`='etr.doubleCheck' AND `type`='ETR';

Specific configuration for additional ETR environments

It is possible to have more than one ETR instance running. It is essential to allow only one ETR to listen for the exception notification to avoid duplicating exceptions in the database.

The configuration parameter notification.active defines whether the ETR will listen to notifications. Only one ETR should have it set to true, while all other instances should be set to false.

Specific configuration for PSBIO environment

To configure the environment for PSBIO:

gbds.listExceptions.labels=COMMON_NAME_OF_CERTIFICATE
filter.people.pguid=ALL
getMatchedPersonWithTguid=false

The configuration getMatchedPersonWithTguid defines the criteria to retrieve data in enrollment exceptions.

• When set to true, the reference profile will be retrieved using the Transaction GUID (TGUID)

• When set to false, the reference profile will be retrieved using the Person GUID (PGUID)

By setting this configuration value to true, profile retrieval will not be affected by any updates to the reference person.

This configuration has no effect on update.

It is strictly recommended not to change the configuration filter.people.pguid without proper guidance, at the risk of compromising the ETR operation. For more information, contact the Griaule Support Team.

Lights Out

Lights Out is a feature that allows enrollment and update exceptions to be handled automatically according to the configured parameters. To allow lightsOut to handle an exception, the parameters lightsOut.enroll.active and lightsOut.update.active must be set to true. The possible values are true or false.

For Lights Out to work correctly, ALL Lights Out configuration parameters in the file config.properties must be present, as described in the sample file in the Configuration File Examplesection. The lack or deletion of some configuration parameters may cause unexpected behavior issues.

Additionally, the user can customize Lights Out for each enrollment or update operation to use other biometric or biographic information. The customizable options refer to fingerprints, face, iris, biographic information and labels and are described below.

All parameters below are available for enrollment and update operations, therefore, in *lightsOut.{operation}.*, the text {operation} must be replaced by enroll or update, for example the parameter lightsOut.{operation}.minimum.fingerprints can be lightsOut.update.minimum.fingerprints or lightsOut.enroll.minimum.fingerprints.

Label Configuration

Label configuration can be set in lightsOut.{operation}.disabled.labels, it accepts more than one label at a time and the default value is empty. Choosing one or more values will disable Lights Out if at least one of them is present in the participant's profile.

Fingerprint Configuration

For fingerprints, there are three available parameters, they are:

• lightsOut.{operation}.minimum.fingerprints, which defines the minimum fingerprint matches that must occur to allow Lights Out to execute the treatment;

• lightsOut.{operation}.fingerScore.any_finger, which defines the threshold for all fingers;

• lightsOut.{operation}.fingerScore.{side}_{finger}, which defines the threshold for a specified finger. {side} is for left or right and {finger} is the finger name. Possible values are:

  • {side}: left or right.

  • {finger}: little, ring, middle, index, and thumb.

The parameter .any_finger will be ignored for a finger if the specific finger threshold is different from zero, for example, if lightsOut.{operation}.fingerScore.right_ring=80, the threshold for the right ring finger will be 80 instead of the one defined in lightsOut.{operation}.fingerScore.any_finger.

All these operation parameters are defined by lightsOut.{operation}.fingerScoresRule, which can have the values AT_LEAST_MINIMUM, where it is necessary to reach at least the threshold in the number of fingerprints configured in lightsOut.{operation}.minimum.fingerprints for Lights Out to treat the exception, or ALL, where all fingerprint scores must reach the score threshold.

Face Configuration

The configurable face parameters are: lightsOut.{operation}.useFace to enable the use of face and it is lightsOut.{operation}.faceScore to set the quality threshold.

Iris Configuration

The configurable iris parameters are:

• lightsOut.{operation}.useIris which defines whether iris will be used;

• lightsOut.{operation}.minimum.irises, which defines the minimum number of irises required;

• lightsOut.{operation}.irisScore.any_iris defines the quality threshold for all irises;

  This value will be used if lightsOut.{operation}.irisScore.left_iris or lightsOut.enroll.irisScore.right_iris are set to 0, otherwise, the value of the last two parameters will be used.

Biographic Configuration

Biographic information for Lights Out can be enabled in the parameter lightsOut.{operation}.useBiographics, the possible values for these parameters are true or false.

The biographic keys that need to be present can be listed in the parameter lightsOut.{operation}.biographicRules address to key:MATCH or key:NOT_MATCH. This configuration accepts more than one parameter at a time, for example:

The configuration parameter lightsOut.enroll.biographicRules=key1:MATCH, key2:MATCH, key3:NOT_MATCH will only apply the Lights Out treatment to the enrollment operation if key1 and key2 match in both profiles, key3 does not match and the other pre-defined rules, such as useFace, useIris, finger thresholds and minimum number of fingerprint matches are also valid.

If any of these biometric and/or biographic information is chosen to be used in Lights Out and the profile does not have this information, for example, does not have iris capture and lightsOut.{operation}.useIris=true, Lights Out will not perform the treatment.

The action executed for the automatic handling of exceptions can be defined through the parameter lightsOut.{operation}.treatStatus, the possible values are the same possible values for the exception treatment by the ETR. Additionally, a comment for the chosen treatment can be customized in the parameter lightsOut.{operation}.treatComments.

Pooling Settings

The pooling configuration controls the pagination behavior of the ETR. Two settings control it: pollingPaginationMode and pollingPagination.size. The first controls whether it is active or not, the second controls how many exceptions will be displayed per page. The GBDS default pagination is 1000.

Refused Transactions Settings

Refused transactions settings control whether the ETR should resend a refused transaction after all exceptions that generated that transaction are resolved.

A refused transaction is a transaction that generated an exception with another transaction that also has an exception. Example:

1 - Profile A is in the GBDS
2 - You sent a Transaction A and that transaction generated an exception with Profile A
3 - Then, you sent a Transaction B and that transaction generated an exception with Transaction A.
4 - The GBDS will mark Transaction B as REFUSED.

This feature will resend Transaction B after the exception generated by Transaction A is handled. To enable this feature, set refused.active to true. The parameter resend.tries defines the maximum number of times the ETR will try to resend a refused transaction.

Other settings control the delay in the operation. These are updateStatusDelay, verifyStatusDelay, listRefusedDelay and deleteRefusedDelay. The delay time is defined in seconds.

Final Settings

The final settings that require attention and should be edited to match each specific implementation are jdbc.url, jdbc.username, jdbc.password and gbds.url. Configure the parameters according to the environment.

Some property details are shown in the subsection below.

Remember to replace the encrypted password generated in the section Database Password Encryption in this file.

Description of Settings

listAnalysisTreatments.initialTimestamp

The ETR updates the list of pending exceptions through queries to the GBDS that are restricted by a time range. This parameter defines the start of this time range, expressed in the format DD/MM/YYYY HH:MM:SS. Pending exceptions prior to this value no will be listed in the ETR clients.

listAnalysisTreatments.offset

This property controls the duration of the time range used to query the GBDS for pending exceptions, as described in listAnalysisTreatments.initialTimestamp. The value can be expressed in days, hours, minutes or seconds: 1d, 5h, 30m or 460s.

listTreatedTreatments.initialTimestamp

The ETR updates the list of treated exceptions through queries to the GBDS that are restricted by a time range. This parameter defines the start of this time range, expressed in the format DD/MM/YYYY HH:MM:SS. Treated exceptions before this value will not be listed in the ETR clients.

listTreatedTreatments.offset

This property controls the duration of the time range used to query the GBDS for treated exceptions, as described in listTreatedTreatments.initialTimestamp. The value can be expressed in days, hours, minutes or seconds: 1d, 5h, 30m or 460s.

listTreatments.analysisAndTreated.synchronized

This property defines the listing of treatments in the ETR. If true, the application will list first all untreated analyses and then the treated ones. If false, the application will list based on the analysis time range.

listTreatments.offsetDelay.milliseconds

This property controls the duration of the delay between each GBDS call.

Finishing the Configurations

After completing all configuration steps, return to the GBS Apps Installation Manual - Configuration Section.

Double Blind

Double Blind analysis is used when there is a need for each decision to go through a second analysis to confirm the decision. If the second decision is different from the first, there will be a third and final verdict from a supervisor.

To enable or disable Double Blind, the ETR Server installation must be complete. To change its status, proceed as follows:

1. Log into MySQL

2. Update the configuration of the sphinx database table with one of the following queries:

   #DEACTIVATE
   
   UPDATE `sphinx`.`settings` SET `val`='false' WHERE  `name`='etr.doubleCheck' AND `type`='ETR';
   commit;
   
   #ACTIVATE
   
   UPDATE `sphinx`.`settings` SET `val`='true' WHERE  `name`='etr.doubleCheck' AND `type`='ETR';
   commit;

3. Reset ETR Server

Configuration File Example

This section shows an example of the file config.properties.

#     /$$$$$$$$ /$$$$$$$$ /$$$$$$$
#    | $$_____/|__  $$__/| $$__  $$
#    | $$         | $$   | $$  \ $$
#    | $$$$$      | $$   | $$$$$$$/
#    | $$__/      | $$   | $$__  $$
#    | $$         | $$   | $$  \ $$
#    | $$$$$$$$   | $$   | $$  | $$
#    |________/   |__/   |__/  |__/

# **************************************************************************************************************
# DATABASE (RDB)

jdbc.driverClassName=com.mysql.jdbc.Driver
jdbc.url=jdbc:mysql://localhost:3306/etr?useSSL=false
jdbc.username=griaule
jdbc.password=CDrt8vbewA2YAubPNOLZkw==
jdbc.dialect=org.hibernate.dialect.MySQLDialect
jdbc.showSql=false

# **************************************************************************************************************
# GBDS CONNECTION (& AUTHENTICATION LDAP ONLY)

gbds.url=http://localhost:8085
gbds.user=gbds_bind
gbds.key=Griaule.123
gbds.logLevel=INFO
gbds.timeout=300
gbds.listExceptions.label=

# **************************************************************************************************************
# ETR * GUI

etr.ip=127.0.0.1
etr.port=8089
etr.protocol=http
locale=en_us

# **************************************************************************************************************
# ETR * CONFIGURATION

biometric.modules=FINGERPRINT,FACE
faceQuality.qtdeMinErrors=2
filter.people.pguid=ALL
fingerprint.useSDK=true
gbds.etrUser=etr_server
getMatchedPersonWithTguid.enroll=true
getMatchedPersonWithTguid.update=true
highlight.labels=
listFields=KEY:documentID,BIOGRAPHIC:name
notification.active=true
pollingPagination.size=20
pollingPaginationMode=true
profile.cacheSize=100
profile.cacheTime=5m
same.user.simultaneous.login=false
showField.tguid=true
sync.logLevel=INFO

# **************************************************************************************************************
# ETR * SEND TREATMENTS

sendTreatments.active=true

# **************************************************************************************************************
# ETR * SEARCH TREATMENTS

verifyTreatments.active=true
verifyTreatments.interval.seconds=5
verifyTreatments.maxTries=5

# **************************************************************************************************************
# ETR * POLL ANALYSIS

listAnalysisTreatments.active=true
listAnalysisTreatments.interval.minutes=30
listAnalysisTreatments.delay.minutes=5
listAnalysisTreatments.initialTimestamp=01/01/2020 00:00:00
listAnalysisTreatments.offset=1d

# **************************************************************************************************************
# ETR * POLL TREATED

listTreatedTreatments.active=true
listTreatedTreatments.interval.minutes=120
listTreatedTreatments.initialTimestamp=01/01/2020 00:00:00
listTreatedTreatments.offset=1d

# **************************************************************************************************************
# ETR * LIST TREATED

listTreatments.analysisAndTreated.synchronized=true
listTreatments.offsetDelay.milliseconds=0

# **************************************************************************************************************
# ETR * LO (ENABLE/DISABLE)

lightsOut.enroll.active=false
lightsOut.enroll.disabled.labels=

lightsOut.update.active=false
lightsOut.update.disabled.labels=

# **************************************************************************************************************
# ETR * LO FINGERPRINT

lightsOut.enroll.minimum.fingerprints=12
lightsOut.enroll.fingerScore.any_finger=50
lightsOut.enroll.fingerScore.left_little=60
lightsOut.enroll.fingerScore.left_ring=80
lightsOut.enroll.fingerScore.left_middle=0
lightsOut.enroll.fingerScore.left_index=0
lightsOut.enroll.fingerScore.left_thumb=0
lightsOut.enroll.fingerScore.right_little=0
lightsOut.enroll.fingerScore.right_ring=0
lightsOut.enroll.fingerScore.right_middle=0
lightsOut.enroll.fingerScore.right_index=0
lightsOut.enroll.fingerScore.right_thumb=0
lightsOut.enroll.fingerScoresRule=AT_LEAST_MINIMUM

lightsOut.update.minimum.fingerprints=10
lightsOut.update.fingerScore.any_finger=100
lightsOut.update.fingerScore.left_little=100
lightsOut.update.fingerScore.left_ring=100
lightsOut.update.fingerScore.left_middle=0
lightsOut.update.fingerScore.left_index=0
lightsOut.update.fingerScore.left_thumb=0
lightsOut.update.fingerScore.right_little=0
lightsOut.update.fingerScore.right_ring=0
lightsOut.update.fingerScore.right_middle=0
lightsOut.update.fingerScore.right_index=0
lightsOut.update.fingerScore.right_thumb=0
lightsOut.update.fingerScoresRule=ALL

# **************************************************************************************************************
# ETR * LO OTHER (FACE/IRIS/BIOGRAPHIC)

lightsOut.enroll.useFace=false
lightsOut.enroll.faceScore=70
lightsOut.enroll.useIris=false
lightsOut.enroll.minimum.irises=0
lightsOut.enroll.irisScore.any_iris=0
lightsOut.enroll.irisScore.left_iris=0
lightsOut.enroll.irisScore.right_iris=0
lightsOut.enroll.useBiographics=false
lightsOut.enroll.biographicRules=name:MATCH

lightsOut.update.useFace=false
lightsOut.update.faceScore=100
lightsOut.update.useIris=false
lightsOut.update.minimum.irises=0
lightsOut.update.irisScore.any_iris=0
lightsOut.update.irisScore.left_iris=0
lightsOut.update.irisScore.right_iris=0
lightsOut.update.useBiographics=false
lightsOut.update.biographicRules=name:MATCH

# **************************************************************************************************************
# ETR * LO TREATMENT

lightsOut.enroll.treatStatus=MERGE_TRANSACTIONS
lightsOut.enroll.treatComments=Treated by ETR Lights Out

lightsOut.update.treatStatus=SAME_FINGERS
lightsOut.update.treatComments=Treated by ETR Lights Out

# **************************************************************************************************************
# ETR * Refused Thread

refused.active=true
updateStatusDelay=60
verifyRefusedDelay=60
listRefusedDelay=60
deleteRefusedDelay=60
resend.tries=3

# *************************************************************************************************************
# ADDITIONAL CONFIGURATION
#gbds.additionalHeaders={}
#gbds.flushDebugRequests=false
#gbds.proxy.url=
#gbds.proxy.port=
#gbds.enroll.priority=DEFAULT_PRIORITY
#gbds.trustedEnroll.priority=DEFAULT_PRIORITY
#externalIdName=null