Skip to content

Configuring E-Visitor Authentication and Adapter

Required Components

  1. SFA Adapter release version 2.0.17 or above
  2. E-Visitor Authentication Adapter release version 2.0.7 or above

When importing and updating the UIP Configuration, make sure to import the file uip-sfa-eva-stb-integration.json to insert the triggers and workflows needed for communicating to the E-Visitor Adapter from the Kiosk. This also adds a new command to the SFA workflow used for detecting the face in a picture.

E-Visitor Adapter

Decide if you want to install the adapter on the Adapter Hub machine or the UIP.

The Hotel is to ensure that the E-Visitor Adapter machine has system has connectivity to the internet, and to be able to access 'https://public.api.gov.sg/'.

Hoteliers are to assess the Visitor check-in loads at non-peak periods and peak periods to determine the required internet connection speed. STB would like to highlight there are 2 types of data exchange between Hotel and STB: Textual Data and Images.

Coordinate with STB to get the E-Visitor Authentication API Key

The Hotel's IT Team must coordinate with STB to receive their E-Visitor Authentication API Key. In order to receive this key, STB must be provided with a JSON Web Key Set (JWKS) containing the public key used to authenticate requests to STB. This JWKS may be provided as a file or hosted on the internet for STB to access. In order to generate the JWKS needed, a tool is provided with the Kiosk distribution.

NEC E-Visitor Authentication JWKS Generator

The generator tool provided in the Kiosk distribution is used to create a new private key used by the E-Visitor Authentication Adapter and an associated JWKS containing the public key used by the STB EVA system. There are two generators provided with the distribution which perform the same function:

  • eva-jwks-generator.exe - a command line executable for use on Windows systems
  • eva-jwks-generator - an executable for use on Linux systems

Simply execute the tool and it will output a private key to be used in the EVA adapter as the Access Token JWT Signing Key and the JWKS to provide to STB.

E-Visitor Authentication Adapter Private Key:
MHcCAQEEINlMW9k/rIQ/JnUnhEAII8FHW69SQU/2UE27ngB9AtyZoAoGCCqGSM49AwEHoUQDQgAE4+pysbHNY/E/c6TFfXM9oTdT9HakcaIyGBfv1euYUpCUYS2uFd5Wxgo7IiZVW3HcCW+dwakotcghIzWrkSRDhA==

JWKS for STB:
{
  "keys": [
    {
      "kty": "EC",
      "kid": "KNjCeKhyuipSYMZy0GQnHjU2F0Jeq9_kzF0F7-K6H9I",
      "crv": "P-256",
      "x": "4-pysbHNY_E_c6TFfXM9oTdT9HakcaIyGBfv1euYUpA",
      "y": "lGEtrhXeVsYKOyImVVtx3AlvncGpKLXIISM1q5EkQ4Q",
      "use": "sig",
      "alg": "ES256"
    }
  ]
}

Press <enter> to close

Warning

Copy the information output by the JWKS Generator tool and keep it safe; you will need this information during the STB renewal process. Running the tool again will create a different private key and JWKS.

STB will provide an API Key in response to receipt of the JWKS, used to configure the EVA adapter's E-Visitor Authentication API Key.

STB Annual Renewal

The Hotel will need to renew their JWKS and API Key on an annual basis. In order to make this transition seamless, run the generator tool passing the existing private key as a parameter.

  1. Run the utility in the following way "eva-jwks-generator <private-key>":

    eva-jwks-generator MHcCAQEEINlMW9k/rIQ/JnUnhEAII8FHW69SQU/2UE27ngB9AtyZoAoGCCqGSM49AwEHoUQDQgAE4+pysbHNY/E/c6TFfXM9oTdT9HakcaIyGBfv1euYUpCUYS2uFd5Wxgo7IiZVW3HcCW+dwakotcghIzWrkSRDhA==

    a. This will generate a new private key and output JWKS to provide to STB which contains your old public key and the new public key.

  2. Provide the updated JWKS to STB, either by updating the hosted JWKS or providing a file with the updated JWKS to STB, and request a new API Key.

  3. Update the E-Visitor Authentication adapter.

    a. Replace the Access Token JWT Signing Key in the adapter with the updated private key.

    b. Replace the E-Visitor Authentication API Key in the adapter with the updated API key provided by STB.

Warning

Copy this information and keep it safe; you will need this information during the next STB renewal process. Use the latest private key in use by the adapter as the parameter for the JWKS generator each time renewal is performed with STB.

E-Visitor Authentication Adapter Configuration

Follow the input and instructions on the E-Visitor Authentication Adapter page to configure and start the adapter.

Check the External checkbox if installing on an Adapter Hub.

Enter https://public.api.gov.sg/his/v1.0/his/api/v1/visitors/transactions for the “E-Visitor Check-in API URL”.

Follow instructions inline for where to get the remaining values.

//

Kiosk Administrator Configuration for E-Visitor

  • Navigate to Kiosk Administrator -> Global Configuration -> External Validation.
    • Check “Enable External Validation” to turn on E-Visitor guest data send for the Kiosk Client.
    • Enter the webhook name for the E-Visitor Adapter trigger imported from the “uip-sfa-eva-stb-integration.json” file to the field “External Validation Webhook”.
      • The default name is “externalDocumentValidation”.
    • Enter the webhook name for the SFA adapter trigger imported from the “uip-sfa-eva-stb-integration.json” file to the field “Crop Person Face Webhook”.
      • The default name is “detectFace”.
    • Min Image Size (KB): Minimum image size accepted by the external validation system.
      • Default value is 10.
    • Max Image Size (KB): Maximum image size accepted by the external validation system.
      • Default value is 100.
    • Enlarge Cropping Percentage (%): Need to enlarge the cropped area because face match adapters (like SFA) return coordinates which strictly limit to the face features that are used in the face match (eyes, nose, mouth). We want that cropped image to contain the entire face though, so we need to enlarge the cropped area a little.
      • Default value is 60.

    • Exclude country codes (separated by semicolon): List of country codes to be excluded from external validation. Country codes in Alpha-2 or Alpha-3 format are used for this list.

      IMPORTANT

      To exclude local guests with Singapore country coming from scanned document, enter “SGP”.  STB only needs foreign guest information to be passed.