1. Introduction

This manual describes the configuration of the server-side components of the GBS ETR application. GBS ETR is a web application that allows users to analyze and treat exceptions generated by GBDS.

The configuration procedure should be done only after the installation step. For more information, refer to GBS Apps Setup Manual.

2. Configuration

The configurations steps are:

  1. Configure Tomcat;
  2. Configure Certificates;
  3. Generate encrypted password;
  4. Enable Best of Biometrics;
  5. Configure Keys or Biographics shown;
  6. Configure Label Highlighting;
  7. Configure Allowed Treatments;
  8. Configure Web Access;
  9. Configure PSBIO environment;
  10. Configure Lights Out;
  11. Configure other config.properties settings;

All steps are described below.

2.1. Tomcat Configuration

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

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

To change the port, look for Connector port=. This is the port for the backend operations.

2.2. 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 -->, and adjust these settings:

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

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

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

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

Warning

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

2.3. Database password encryption

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

  1. Go to the following directory:

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

  2. Execute the command:

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

  3. The encrypted password will be displayed after “Encrypted password is:”

Note

Store this encrypted password. It will be used in the next step.

2.4. Enabling Best of Biometrics

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

When applied, Best of Biometrics evaluates each fingerprint and palmprint template individually and selects the templates with the highest quality on each finger and/or palm position among all the merged transactions. Then, it updates the person profile to unify the “best” biometrics in a single active transaction that will be used for biometric comparison. This operation does not apply to Face and Iris templates, to which the latest images will override the older ones, regardless of the quality.

Danger

Best of Biometrics is a feature available to GBDS and ETR. Notwithstanding that they fulfill the same function, they are NOT the same process and SHOULD NOT be activated together.

For more information, contact Griaule Support Team.

To enable Best of Biometrics in ETR, the database must have the parameters treat.multiMerge.consolidation and bob.trustedUpdate.active set to 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 update the 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 enabled and it is needed to deactivate it, use the following query:

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

2.5. Configuration of keys or biographics to show in Exceptions List

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

To configure a new field, is necessary to have this field added to the MySQL database. Log in to the mysql server using:

mysql -u<user> -p

Execute the following statement to verify the existent fields:

use sphinx;

select * from field;

Verify the number of fields that return in 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 = the name of the field to be used
  • descriptionEN = the description in English
  • descriptionBR = the description in Portuguese
  • descriptionES = the description in Spanish
  • string = the type of the value (string or integer) – keys and biographics can use string
  • KEY = the kind of the field: KEY or BIOGRAPHIC
  • 8 = Its the order of the fields. Just increase the number of fields that already exists (the current number was returned in the previous query)
  • 1 = enable field for cardscan. Don’t need to change this value

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

Copy the response (everything inside of showFields).

Send a POST request to the same endpoint URL with the modified JSON settings (all the desired fields should be informed - old fields and new fields, otherwise only the informed 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"
}

2.6. Configuration of Label Highlighting

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

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

Copy the response (everything inside of system configuration).

Send a POST request 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.

2.7. Configuration of allowed treatments

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

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 value of key with type ENROLL can be: enroll.same_fingers, enroll.different_fingers, enroll.recollect, enroll.merge
  • The value of key 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 in 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 in the ETR screen for the attempt person to enroll in the database. Available values: KEEP, DISCARD, MERGE, and BLACKLIST.

3. Application properties Configuration

This section will describe the possible configurations at config.properties file. To access the file, open with:

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

An example config.properties file is found at Configuration File Example section.

Danger

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

3.1. ETR Configuration

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

etr.ip=http://<ip>
etr.port=<port>

Important

Its also possible to use https at etr.ip configuration.

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

3.1.1. Specific configuration for Extra ETR environments

It is possible to have more than one instance of ETR running. It is essential to allow only one ETR to listen to the exception notification to avoid doubling the exceptions at the database.

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

3.1.2. 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 getMatchedPersonWithTguid configuration defines the criteria for retrieving data in enrollment exceptions:

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

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

Note

This configuration has no effect on update exceptions.

Danger

It is strictly recommended to not change filter.people.pguid without proper orientation, risking compromise ETR functioning. For further information contact Griaule Support Team.

3.2. Lights Out

Lights Out is a feature that allows enrollment and update exceptions to be automatically treated according to configured parameters. To enable lightsOut to treat an exception, the parameters lightsOut.enroll.active and lightsOut.update.active should be set as true. The possible values are true or false.

Danger

To Lights Out operate correctly, ALL Lights Out configuration parameters at config.properties archive must be present, as described in the example file at Configuration File Example section. Missing or erasing some configuration parameters may cause unexpected behavior issues.

Also, the user is able to customize the Lights Out for each enroll or update operation to use other biometric or biographic information. The customizable options are referent to fingerprints, face, iris, biographic information, and labels and are described below.

Important

All parameters below are available to both enroll and update operations, so in “lightsOut.{operation}.”, the “{operation}” text can be replaced by “enroll” or “update”, as example the parameter lightsOut.{operation}.minimum.fingerprints can be lightsOut.update.minimum.fingerprints or lightsOut.enroll.minimum.fingerprints

3.2.1. Label Configuration

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

3.2.2. Fingerprint Configuration

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

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

  • lightsOut.{operation}.fingerScore.any_finger, that set the threshold to all fingers;

  • lightsOut.{operation}.fingerScore.{side}_{finger}, that defines the threshold to a specified finger. {side} is left or right, and {finger} is the finger name.

    • {side}: left or right.
    • {finger}: little, ring, middle, index, and thumb.

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

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

3.2.3. Face Configuration

Face options are to enable the use of face in the parameter lightsOut.{operation}.useFace and set the quality threshold at lightsOut.{operation}.faceScore

3.2.4. Iris Configuration

Iris customizable parameters are:

  • lightsOut.{operation}.useIris which define if Iris will be used;

  • lightsOut.{operation}.minimum.irises, which set the minimum iris needed;

  • lightsOut.{operation}.irisScore.any_iris is the quality threshold defined for all iris;

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

3.2.5. Biographical Configuration

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

The biographic keys needed to be present can be listed at the parameter lightsOut.{operation}.biographicRules 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 Lights Out treatment to the enroll operation if key1 and key2 match in both profiles, key3 do not match, and the other pre-defined rules such as useFace, useIris, and fingers threshold and minimum fingerprints matches are also valid.

Note

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

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

3.3. Pooling Configurations

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

3.4. Refused Transactions Configurations

The refused transaction configurations controls whether ETR should resend a refused transaction after all exceptions that generated that transaction where solved.

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

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

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

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

3.5. Final file configurations

The final properties that require attention and must be edited to match each specific deployment 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.

Note

Remember to substitute the correct encrypted password generated in the Database password encryption section in the file.

3.5.1. Property Descriptions

listAnalysisTreatments.initialTimestamp

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

listAnalysisTreatments.offset

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

listTreatedTreatments.initialTimestamp

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

listTreatedTreatments.offset

This property controls the length of the time interval used for querying GBDS for treated exceptions, as described under 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 ETR. If true, the application will list all untreated analyses first and then treated ones. If false, the application will list based on the time interval of the analysis.

listTreatments.offsetDelay.milliseconds

This property controls the length of the delay between each call from GBDS.

4. Finish Configuration

After all configuration steps are complete, go back to the GBS Apps Setup Manual - Configuration Section.

5. Double Blind

Double Blind analysis is used when there is need for every decision to pass through a second analysis to confirm the decision. If the second decision differs from the first on, there will be a third and final verdict of a supervisor.

To activate or deactivate the Double Blind ETR Server installation must be complete. To change its status, proceed as following:

  1. Log in the MySQL

  2. Update the sphinx database table setting 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

6. Configuration File Example

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

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

# **************************************************************************************************************
# 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

# **************************************************************************************************************
# GDBS 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
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