3.3.0

Middleware

Please ensure that you have followed all steps as described under the Get Started section.

UI Configuration

In order to be able to make use of middleware for obfuscation, the JavaScript API must be configured for it:

First, set the integrationMode configuration option to 1 (middleware). This value is 0 by default (direct).

If you are using the companion API provided with the product:

  • Set the apiKey value to the API key for the middleware, as provided by Sybrin.

  • Set the passiveLivenessEndpoint to point to the VerifyLiveness function: http://(your-hosting-domain-and-port)/api/FaceLiveness/VerifyLiveness.

If you are using your own backend implementation:

  • Set the passiveLivenessEndpoint to the endpoint that you expect the web SDK to hit.

  • Set the passiveLivenessHttpMethod property to the HTTP method type that the above endpoint accepts (Typically, this would be 'POST').

  • Set the passiveLivenessHeadersCallback function. In this function, you must return the headers object that you expect to receive. To help with setting this up, the function provides the following as parameters:

    • The default headers object and

    • The SnapshotData object containing other relevant data for the capture instance.

  • Set the passiveLivenessBodyCallback function. In this function, you must return the body object that you expect to receive. To help with setting this up, the function provides the following as parameters:

    • The default body object and

    • The SnapshotData object containing other relevant data for the capture instance.

Header Defaults

By default, the header object contains:

  • Content-Type: application/json

  • Authorization: Bearer <token> (If a token is set on configuration options)

  • vec: <initialization vector> (If an encryption key is configured)

Body Defaults

By default, the body object contains:

  • hash: The security hash calculated on the image to ensure that the image comes from a trusted source.

  • facingMode: The facing direction of the camera that was used for capture.

  • correlationId: The correlation ID for the case.

  • media: The data URI of the image that was taken.

  • video: The data URI of the video that was taken, if applicable.

  • apiKey: The API key set in the configuration options (If no token is set on configuration options)

Liveness Snapshot Data Object

The snapshot data object provides the following:

  • imageDataUri (string): The data URI of the image that was taken.

  • videoDataUri (string): The data URI of the video that was taken, if applicable.

  • imageBlob (Blob): The blob data of the image that was taken.

  • videoBlob (Blob): The blob data of the video that was taken, if applicable.

  • hash (string): The security hash calculated on the image to ensure that the image comes from a trusted source.

  • videoHash (string): The security hash calculated on the video to ensure that the video comes from a trusted source.

  • vec (string): The AES initialization vector for the request if encryption is being used.

  • correlationId (string): The correlation ID for the case.

  • facingMode (string): The facing direction of the camera that was used for capture.

  • deviceGroupId (string): The group ID for the physical video device that was used.

  • deviceId (string): The device ID for the physical video device that was used.

Face Compare Snapshot Data Object

The snapshot data object provides the following:

  • face1 (FaceCaptureData): Face capture data instance for face 1. Please see the section below.

  • face2 (faceCaptureData): Face capture data instance for face 2. Please see the section below.

  • vec (string): The AES initialization vector for the request if encryption is being used.

  • correlationId (string): The correlation ID for the case.

Face Capture Data Object

This object encapsulates all data relevant to a face for face comparison. Provided properties are as follows:

  • faceDataUri (string): The data URI of the face extracted from the image that was taken.

  • imgDataUri (string): The data URI of the image that was taken.

  • file (Blob): The blob data of the image that was taken.

  • video (Blob): The blob data of the video that was taken, if applicable.

  • facingMode (string): The data URI of the video that was taken, if applicable.

  • hash (string): The security hash calculated on the image to ensure that the image comes from a trusted source.

  • videoHash (string): The security hash calculated on the video to ensure that the video comes from a trusted source.

  • faceHash (string): The security hash calculated on the extracted face image ensure that it comes from a trusted source.

Using Encryption

  • facingMode (string): The facing direction of the camera that was used for capture.

To use encryption, simply set the encryptionKey configuration on the UI to a 32-character string value, and if you're using the companion API provided by the product, set the UIEncryptionKey in appsettings to be the same value.

If you wish to use encryption with your own backend implementation, you need to implement your own AES decryption step, as appropriate for your platform of choice, on the body sent by the UI. You will need to use the same encryption key as configured on the UI, as well as the initialization vector as passed down in the header as 'vec'.

Companion API Configuration Options

The following properties are exposed as configuration options in the appsetttings file:

{
  "AllowedHosts": "*",
  "PassiveLivenessParamName": "media",
  "BiometricsApiKey": "your-biometrics-api-key-here",
  "BiometricsAuthorizationEndpoint": "your-biometrics-auth-endpoint-here",
  "PassiveLivenessEndpoint": "your-passive-liveness-endpoint-here",
  "IntegrationMode": 0,
  "IntegrationHttpMethodType": "POST",
  "IntegrationEndpoint": "your-integration-endpoint-here",
  "IntegrationHeaders": {},
  "IntegrationBody": {},
  "RemoteVerificationIntegrationMode": 0,
  "RemoteVerificationHttpMethodType": "POST",
  "RemoteVerificationEndpoint": "your-remote-verification-endpoint-here",
  "RemoteVerificationHeaders": {},
  "RemoteVerificationBody": {},
  "LivenessHeaders": {
    "UseV2": true,
    "ModelNumber": 7
  },

  "WebAPIKeyID": "your-api-key-id-here (com.company.webbiometrics)",

  "Security": {
    "UIEncryptionKey": "your-32-character-encryption-key-here",
    "AuthSecret": "your-auth-secret-here (guid)",
    "TokenValidityDays": 1,
    "TokenValidityMinutes": 0
  }
}

Property Details

  • AllowedHosts: Configure CORS.

  • BiometricsApiKey: The API key used to connect to the biometrics backend service. Contact Sybrin to receive your Biometrics API key. No default.

  • BiometricsAuthorizationEndpoint: Endpoint of the biometrics backend service call used to authenticate for usage. No default.

  • IntegrationBody: Sets the body that should be passed to the integration endpoint while synchronizing data. Expressions may be used. No default

  • IntergationEndpoint: The endpoint that the integration call should be made to if IntegrationMode is not 0.

  • IntegrationHeaders: Sets the headers that should be passed to the integration endpoint while synchronizing data. Expressions may be used. No default

  • IntegrationHttpMethodType: Sets the type of HTTP method that should be used for the integration call (POST or GET). Default POST

  • IntergationMode: How the integration call should be handled for the given step. The options are 0 (None - no integration), 1 (Json), 2 (FormData).

  • LivenessHeaders: Sets the headers that should be passed to the biometrics service while running liveness. No default

  • PassiveLivenessEndpoint: Endpoint of the biometrics backend service call used to run passive liveness. No default

  • PassiveLivenessParamName: The parameter name of the passive liveness selfie image passed to the service that handles liveness processing. Default "media"

  • RemoteVerificationBody: Sets the body that should be passed to the remote verification endpoint while verifying. Expressions may be used. No default

  • RemoteVerificationEndpoint: The endpoint that the remote verification call should be made to if RemoteVerificationIntegrationMode is not 0.

  • RemoteVerificationHeaders: Sets the headers that should be passed to the remote verification endpoint while verifying. Expressions may be used. No default

  • RemoteVerificationHttpMethodType: Sets the type of HTTP method that should be used for the remote verification call (POST or GET). Default POST

  • RemoteVerificationIntegrationMode: How the remote verification call should be handled for the given step. The options are 0 (None - no remote verification), 1 (Json), 2 (FormData).

  • Security: Section to configure security parameters.

    • AuthSecret: Authentication secret used to secure the API with. Recommended to be set to a GUID that is not used anywhere else. No default

    • TokenValidityDays: How long (in days) a token provided by the backend service should be valid for. This value gets added to the minute value. Default 1

    • TokenValidityMinutes: How long (in minutes) a token provided by the backend service should be valid for. This value gets added to the days value. Default 0

    • UIEncryptionKey: A 32 character string that will be used to encrypt network traffic from the UI to the middleware. This value must match the encryption key configured on the UI.

  • WebAPIKeyID: Individual API key ID as provided by Sybrin. No default

Expression Parsing

Some properties allow for the use of expressions. To pull data with an expression, use the following format:

${myexpression}

For example, if you wish to pass the correlation ID as a header while running the integration call, set the following configuration:

{
    "IntegrationHeaders": {
        "CorrelationID": "${correlationid}"
    }
}

The left side of the property determines the header name expected on the receiving end and may be set freely. The right side determines the header value.

Expressions may contain certain reserved keywords, or correspond to any header or body value passed with the original request made from the UI component.

Reserved Keywords

The following keywords are reserved for internal values:

  • selfieblobdata: Returns the selfie image in blob data format.

  • selfiestringdata: Returns the selfie image in base64 string format.

  • videoblobdata: Returns the video recording in blob data format.

  • videostringdata: Returns the video recording in base64 string format.

  • livenessresult: Returns the liveness check result in boolean format.

  • livenessconfidence: Returns the liveness result confidence level in numeric (float) format.

Backend Integration

The companion API provides configuration options to allow for dynamic backend integration.

Verification

The companion API can be configured to first do a verification check with a specific backend in order to determine if the case that is coming in is valid.

To make use of this functionality, the following properties must be configured:

  • RemoteVerificationIntegrationMode (Set to 1 for form data or 2 for JSON data)

  • RemoteVerificationHttpMethodType (Set to POST or GET)

  • RemoteVerificationEndpoint (Set to the endpoint that should be queried or posted to)

  • RemoteVerificationHeaders (Set the request headers that must be sent for verification)

  • RemoteVerificationBody (Set the request body that must be sent for verification)

Remember that expression parsing may be use to set up the request body and headers

Data Synchronization

Once a liveness check completes, the result may be forwarded to a specific backend.

To make use of this functionality, the following properties must be configured:

  • IntegrationMode (Set to 1 for form data or 2 for JSON data)

  • IntegrationHttpMethodType (Set to POST or GET)

  • IntegrationEndpoint (Set to the endpoint that should be queried or posted to)

  • IntegrationHeaders (Set the request headers that must be sent for synchronization)

  • IntegrationBody (Set the request body that must be sent for synchronization)

Remember that expression parsing may be use to set up the request body and headers