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 dataExtractionEndpoint to point to the ExtractData function: http://(your-hosting-domain-and-port)/api/DocumentCapture/ExtractData.

If you are using your own backend implementation:

Set the dataExtractionEndpoint to the endpoint that you expect the web SDK to hit.
Set the dataExtractionHttpMethod property to the HTTP method type that the above endpoint accepts (Typically, this would be 'POST').
Set the dataExtractionHeadersCallback 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 data extraction instance.
Set the dataExtractionBodyCallback 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 data extraction 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:

frontImageHash: The security hash calculated on the front image to ensure that the image comes from a trusted source.
backImageHash: The security hash calculated on the back 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.
frontImage: The data URI of the front image that was taken.
backImage: The data URI of the back image that was taken.
countryCode: The country code of the document that was captured.
documentType: The type of the document that was captured.
apiKey: The API key set in the configuration options (If no token is set on configuration options)

Snapshot Data Object

The snapshot data object provides the following:

frontDataUri (string): The data URI of the front image that was taken.
backDataUri (string): The data URI of the back image that was taken, if applicable.
frontBlob (Blob): The blob data of the front image that was taken.
backBlob (Blob): The blob data of the back image that was taken, if applicable.
frontHash (string): The security hash calculated on the front image to ensure that the image comes from a trusted source.
backHash (string): The security hash calculated on the back image to ensure that the image comes from a trusted source, if applicable.
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.
countryCode (string): The country code of the document that was captured.
documentType (string): The type of the document that was captured.
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.

Using Encryption

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": "*",
  "ExtractionFrontParamName": "FrontImage",
  "ExtractionBackParamName": "BackImage",
  "IdentityApiKey": "your-identity-api-key-here",
  "IdentityAuthorizationEndpoint": "your-identity-auth-endpoint-here",
  "DataExtractionEndpoint": "your-data-extraction-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": {},
  "WebAPIKeyID": "your-api-key-id-here (com.company.webidentity)",
  "Security": {
    "UIEncryptionKey": "your-32-character-encryption-key-here",
    "AuthSecret": "your-auth-secret-here (guid)",
    "TokenValidityDays": 1,
    "TokenValidityMinutes": 0
  }
}

Property Details

AllowedHosts: Configure CORS.
DataExtractionEndpoint: Endpoint of the identity backend service call used to data extraction. No default
ExtractionBackParamName: The parameter name of the back document image passed to the service that handles data extraction. Default "BackImage"
ExtractionFrontParamName: The parameter name of the front document image passed to the service that handles data extraction. Default "FrontImage"
IdentityApiKey: The API key used to connect to the identity backend service. Contact Sybrin to receive your Identity API key. No default.
IdentityAuthorizationEndpoint: Endpoint of the identity 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).
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:

backblobdata: Returns the document back image in blob data format.
backstringdata: Returns the document back image in string data format.
extracteddata: Returns all extracted fields in dictionary format. For form data integration mode, this will be parsed into a JSON string.
faceblobdata: Returns the face portrait image in blob data format.
facestringdata: Returns the face portrait image in string data format.
frontblobdata: Returns the document front image in blob data format.
frontstringdata: Returns the document front image in string data 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 document data extraction 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