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.
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:
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:
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