BWS Windows Service

The BioIDSvc is a version of the BioID Web Service (BWS), where the Azure WorkerRole is replaced by a Microsoft Windows service with an identical implementation of the BWS APIs. The main difference is the use of a MongoDB database instead of the Azure Storage service.

Differences to the BioID-hosted Azure services:

• The SOAP- and REST-interfaces of the BioIDSvc are accessed through the URLs and paths defined in the configuration file (in BWS the SOAP service is accessed through the path BioIDWebService.svc, the REST-API through the path extension).
• Because a database (MongoDB) is used for data management, the Biometric Class IDs (BCIDs) don't support different Storages. The only storage that can be used is configured in the ConnectionString{storage} parameter in the configuration file BioIDsvc.exe.config.
  
  

Sample applications, tools and source code:

To test and troubleshoot the service, you can use the BWS PowerShell Cmdlets. Various Blog entries contain code and other helpful information. In the BioID GitHub repositories (https://github.com/BioID-GmbH/) you can find a BWS command line tool, among others.

For this documentation following configuration is assumed. Replace server names and other parameters according to your environment!

System Requirements

For a production installation, BioIDsvc requires the following system conditions, either as a physical system or as a VM in a virtualized environment.

System

^*) Identification as related to face and/or periocular recognition. Identification with voice recognition requires significantly more resources.

Network

The network ports assume default values. They should be adapted to local conditions as needed. Likewise changes to Windows Firewall settings may be needed, if a non-default configuration is used.

To establish a secure connection to BioIDsvc, a valid X.509 certificate issued to the FQDN of the server must be installed on the server in the certificate storage LocalMachine/My.

This can be done manually or by using the installation script. See the comments in the install script install-bioidsvc.ps1 for further information.

For the connection to the database the connection string (see: https://docs.mongodb.com/manual/reference/connection-string/) for the MongoDB database instance is required.

The service creates all necessary collections and indices automatically in the database object bws.

Installation

Typically Windows PowerShell Remoting is used for the installation of BioIDsvc on a remote system, e.g. on a Microsoft Windows 2016 Core installation with no desktop environment. On systems with an desktop environment the installation package can be unzipped in the windows explorer and the installation script can be started in a local PowerShell window as a user with administrative rights. 

The Installation Package

The BioIDSvc installation package is a compressed  ZIP file with following structure after extracting:

• bin/ - A directory with the binary files that are copied by the installation script into the program folder.
• setup/ - A directory with the PowerShell installation script install-bioidsvc.ps1, the configuration file BioIDSvc.exe.config and optionally other files depending on the product type.

For the transfer to the remote system Windows PowerShell as unprivileged user or Windows Powershell ISE as unprivileged user can be used.

Configuration of the Service

The configuration file in the setup directory of the installation package has to be modified according to the target environment.

Two elements serve to configure the BioIDSvc: the configuration file (BioIDSvc.exe.config in the setup directory of the installation package) and the collection clients in the MongoDB database. The configuration file contains the service's basic settings, which are typically read and analyzed at program startup. The allowed client applications are managed by the database, and are periodically fetched by the service. 

The Configuration file

The .NET configuration file BioIDSvc.exe.config contains the service's basic settings. The following application specific settings in element appSettings should be set to the values of the target installation.

The Installation Script

Syntax:

install-bioidsvc.ps1 [[-sslThumbprint] <String>] [-keepConfig] [-WhatIf]

Parameter:

• -sslThumbprint: The optional thumbprint of the SSL certificate in LocalMachine/My certificate store that should be bound to the SSL port.
• -keepConfig: keeps an existing config-file. By default an existing config-file is copied to a backup file before it is replaced by the bioidsvc.exe.config from the setup folder.
• -WhatIf: shows what happens if the script is executed. The individual commands are not actually carried out.

The following installation steps are performed by the script:

• If a BioIDSvc is already installed, it will first be stopped and uninstalled.
• All files from the bin directory are copied into the target directory C:\Program Files\BioIDSvc.
• The config-file is copied, if the parameter -keepConfig is not set.
• The SSL certificate - if specified - is installed.
• The SSL certificate is bound to the specified HTTPS port.
• A firewall rule for incoming HTTPS data traffic is applied.
• The BioIDSvc is installed using the .NET Framework Installation utility. In addition, BioIDSvc.exe itself contains some installers to install the service, the Application EventLog BWSLog and two EventLog sources (in Application Log and in BWSLog).
• The BioIDSvc is started.

Installation

First a remote session to the system intended to run the BioID Web Service has to be initiated. The installation package is transferred to the remote system and the installation script is executed. 

Open a Windows PowerShell or Windows PowerShell (ISE) on workstation.bioid.com and create a remote session. 

$RemoteSession = New-PSSession -ComputerName "onpremise.bioid.com" -Credential "~\Administrator"

Next transfer the installation package to the remote system onpremise.bioid.com and extract the files

Copy-Item -ToSession $RemoteSession -Path "C:\tmp\bioidsvc.bioid.com.zip" -Destination "C:\Users\Administrator\Downloads"
Invoke-Command -Session $RemoteSession -ScriptBlock { Expand-Archive -Path "C:\Users\Administrator\Downloads\bioidsvc.bioid.com.zip" }

# OR if the zip file with the installation package was extracted on the local system

Copy-Item -ToSession $RemoteSession -Path "C:\tmp\bioidsvc.bioid.com\" -Destination "C:\Users\Administrator\Downloads" -Recurse

Start the installation on the remote system using the thumbprint of the TLS server certificate.

Invoke-Command -Session $RemoteSession -ScriptBlock { & "C:\Users\Administrator\Downloads\bioidsvc.bioid.com\setup\install-bioidsvc.ps1" 55D7B0D345775A0A6DADE157EAF9DE05430EE096 }

******************************************************************************
Installing BioIDSvc from C:\Users\Administrator\Downloads\bioidsvc.bioid.com\bin
using configuration at C:\Users\Administrator\Downloads\bioidsvc.bioid.com\setup
******************************************************************************
Copying files to C:\Program Files\BioIDSvc\ ...
Binding the SSL certificate tp port 0.0.0.0:443 ...
Adding inbound HTTPS firewall rule ...
Installing and starting the BioIDSvc ...
Microsoft (R) .NET Framework Installation utility Version 4.7.2556.0
Copyright (C) Microsoft Corporation.  All rights reserved.


Running a transacted installation.

Beginning the Install phase of the installation.
See the contents of the log file for the C:\Program Files\BioIDSvc\BioIDSvc.exe assembly's progress.
The file is located at C:\Program Files\BioIDSvc\BioIDSvc.InstallLog.
Installing assembly 'C:\Program Files\BioIDSvc\BioIDSvc.exe'.
Affected parameters are:
   logtoconsole = 
   assemblypath = C:\Program Files\BioIDSvc\BioIDSvc.exe
   logfile = C:\Program Files\BioIDSvc\BioIDSvc.InstallLog
Creating EventLog source BioIDWebService in log BWSLog...
Installing service BioIDSvc...
Service BioIDSvc has been successfully installed.
Creating EventLog source BioIDSvc in log Application...

The Install phase completed successfully, and the Commit phase is beginning.
See the contents of the log file for the C:\Program Files\BioIDSvc\BioIDSvc.exe assembly's progress.
The file is located at C:\Program Files\BioIDSvc\BioIDSvc.InstallLog.
Committing assembly 'C:\Program Files\BioIDSvc\BioIDSvc.exe'.
Affected parameters are:
   logtoconsole = 
   assemblypath = C:\Program Files\BioIDSvc\BioIDSvc.exe
   logfile = C:\Program Files\BioIDSvc\BioIDSvc.InstallLog

The Commit phase completed successfully.

The transacted install has completed.
WARNING: Waiting for service 'BioIDSvc (BioID Web Service) (BioIDSvc)' to start...

Checking the Service

After performing the installation the service is started on the remote system. You can check the status of the service with the Get-Service command.

Invoke-Command -Session $RemoteSession -ScriptBlock { (Get-Service -Name BioIDsvc).Status }

Status   Name               DisplayName                           
------   ----               -----------                           
Running  BioIDsvc           BioIDSvc (BioID Web Service)    

Client configuration

The configuration of client applications of the BioIDsvc is handled through the collection clients in the MongoDB database.

All documents assigned to the service are read in and analyzed at the startup of the service and at regular intervals set by UpdateConfigurationInterval in the configuration file.

Only clients that identify themselves with the certificates specified here or the corresponding App-ID / secrets are granted access to the configured partitions. Specifically, a BWS Client Document contains the following data:

This is a sampe JSON document for the configuration of a client. It creates a client MyClient with the storage name MyStorage and the storage partition 23 for verification and identification.

For testing and debugging the samples for enrollment and the biometric operations are saved. A X.509 client certificate is given allowance to access the BioIDsrv instance for SOAP requests. Also two client apps are allowed access to the service with the combination of App-ID and secret for RESTful API calls.

{
    "_id" : "MyClient",
    "Storage" : "MyStorage",
    "Partition" : 23,
    "IdentifyPartitions" : [
        23
    ],
    "Expires" : ISODate("2018-06-10T12:00:00.000Z"), 
    "SaveEnrollmentSamples" : true,
    "LogSamples" : true,
    "Certificates" : [
        {
            "Thumbprint" : "80F0BFC6A3450441EF3F6A4D5B470518A0C2E72B"
        }
    ],
    "ClientApps" : [
        {
            "Identifier" : "testclient.1",
            "PasswordHash" : "pbkdf2:1000:QAVHuvUNNdWslJxhlDTBZyxW:PjxOuID+lRUOCIHj4Lp8y/MHiT7FIPzECkXU/7l0"
        }
    ]
}

Client Certificates

For accessing the BioIDsvc with the SOAP API, a standard X.509 certificate has to be installed on the client system. Access to the service is granted if the certificates thumbprint on the client matches the thumbprint configured in the Certificates section of the JSON client configuration file.The certificates can be issued by your local PKI or tools like OpenSSL. Alternatively, if you have no local PKI installed but want to use the SOAP API with client certificate credentials, we can issue the necessary certificates for you.

You can then use the BWS PowerShell Cmdlets to test the connectivity from your client system to the BioIDsrv service using the certificate's thumbprint. Assuming the client certificate installed on the client machine and assigned to the client configuration on the server has the thumbprint 80F0BFC6A3450441EF3F6A4D5B470518A0C2E72B following command can be used to display the status of the BioIDsvc:

Get-BWSStatus -BWS 'https://onpremise.bioid.com/bws' -Certificate  ( Get-ChildItem Cert:\CurrentUser\My\80F0BFC6A3450441EF3F6A4D5B470518A0C2E72B )

Version Label           Features                                  
------- -----           --------                                  
2.3     BWS 2.3.18071.1 {QualityCheck, LiveDetection, PhotoVerify}

The technical blog articles Test the BWS accessibility with wget and Test the BWS accessibility with curl explain how to test the status of the service with tools more commonly found on UNIX or GNU/Linux systems.

Password Hashes

To call a REST interface, Basic Authentication with an App-ID and password is necessary. The service can perform the authentication through a hash value stored in the client configuration. To calculate the password hash, a typical standard process is used (salted password hashing with PBKDF2-HMACSHA1). The formatting of the hash then occurs as follows:

pbkdf2:{#iterations}:{base64 of salt}:{base64 of hash}

We provide a simple tool to create those hashes:

https://playground.bioid.com/tools/hashsecret?secret=YOUR_SECRET

To insert this document into the database, the mongo Shell may be used. The mongo Shell can be invoked by using the command mongo (or mongo.exe on Microsoft Windows operating environment).

First select the database and then insert the JSON snippet into the clients collection.

use bws
db.clients.insert( 
	{ "_id" : "MyClient", 
	Storage : "MyStorage", 
	Partition : NumberInt(23), 
	IdentifyPartitions : [ NumberInt(23) ], 
	Expires : ISODate("2018-12-31T12:00:00.000Z"), 
	SaveEnrollmentSamples : true, 
	LogSamples : true, 
	Certificates : 	[{ Thumbprint : "80F0BFC6A3450441EF3F6A4D5B470518A0C2E72B" }], 
	ClientApps : 	[ { Identifier : "testclient.1", PasswordHash : "pbkdf2:1000:c+B2f9wR/uKzFyRXB6QIcbUu:jKjFZ7MVZqW+FTvsNtnhSFd5R1QFkhNDbgWQFI7v" }, 
				      { Identifier : "sample-rest-app.2345739", PasswordHash : "pbkdf2:1000:gmuqNnM6VvwwMNKnsz8FTUi6:PWu3MOpMLTKc9riYWGPd3SkzhY47DsyLh0asYlid" } ] } )

Data Management

In general we distinguish between three types of data:

• biometric data
• log data
• configuration data.

Biometric Data

Biometric data is managed in various collections according to the biometric trait face, periocular or voice and their type. In the Template collections the biometric templates are stored as required for the operations "verification" and "identification". In the Features collections the data are stored that are extracted from the raw data at enrollment and used to generate the templates. Optionally, in the Pattern collections the used raw data can also be stored (these are not needed for operation and serve only informational or diagnostic purposes, see the LogSamples parameter in the client configuration).

In summary, there can currently be up to nine collections for the biometric data:

Synchronization

The BioIDSvc must keep all instances of all identifiers (classifiers that enable identification against a complete partition) up to date. This is done with the help of the collection classifer-updates. If a class is first trained or subsequently retrained or deleted, a corresponding document is written in this collection. All identifiers fetch the collection regularly (approx. every 4 seconds) and update their classes accordingly.

The collection classifier-updates uses a TTL index to automatically delete all documents older than 20 seconds. 

Log data

All calls to the BioIDSvc are logged. This is done with the help of the collections bwslog_yyyy_MM, yyyy represents the year and MM the month in which the entry was generated. In the collection usage, daily and monthly summaries of the log entries are noted.

In the bwslog tables, _id refers to the internally assigned unique JobId, enablng a search for further data relating to this entry. For instance, the data uploaded to the service (if Logging is turned on) is also marked with this JobId in the collection SamplesLog.

All other fields describe the performed operation and are self-explanatory.

In the usage collection, monthly and daily usage statistics are prepared by BioIDSvc at configured intervals. For each client, all operations are summed for the current period (day or month). Accordingly,  _id refers to the Period in the format yyyy_MM (monthly statistics) or yyyy_MM_dd (daily statistics) with appended Client name. All further entries are the sums from the bwslog tables.

Configuration data

There are three places, where configuration data is stored:

• the configuration file BioIDsvc.exe.config
• the client configuration in the config collection of the database
• the installation file install-bioidsvc.ps1 (optional)

The configuration file BioIDsvc.exe.config is in the sub folder setup of the installation folder. It will then be copied into the program folder, usually C:\Program Files\BioIDsvc\. The settings are explained in the section Configuration of the Service in this document and in the comments in the file itself. Configured items are the network URI's of the API's, intervals for configuration updates and reporting and the database connection strings.

The client configuration is stored in the services database. The parameters set in the client configuration are storage identifiers, logging settings and client authentication settings. Those parameters are explained in section Client Configuration in this document.

In the installation script install-bioidsvc.ps1 the services port (defaults to TCP 443 for HTTPS) is set and an TLS servcer certificate could be installed and bound to the port while performing the service installation. This is optional and usually the certificate is installed with PowerShell as explained in the Appendix. Refer to the comments in the installation script if you want to use this feature.

Appendix

Starting and Stopping the Service with Powershell

Following commands can be used to stop, start and restart the service on a remote system after creating a PowerShell remote session:

# First create a remote session if needed
$RemoteSession = New-PSSession -ComputerName "onpremise.bioid.com" -Credential "~\Administrator"


# use Invoke-Command to execute the commands in the remote session
Invoke-Command -Session $RemoteSession -ScriptBlock { Stop-Service -Name Bioidsvc }                                                                                                                    
Invoke-Command -Session $RemoteSession -ScriptBlock { Start-Service -Name Bioidsvc }                                                                                                                   
Invoke-Command -Session $RemoteSession -ScriptBlock { Restart-Service -Name Bioidsvc }  

Getting Information about the BioIDsvc Service

To check the current status of the BioIDsvc service use the Get-Service command:

# First create a remote session if needed
$RemoteSession = New-PSSession -ComputerName "onpremise.bioid.com" -Credential "~\Administrator"

# use Invoke-Command to execute the command in the remote session
Invoke-Command -Session $RemoteSession -ScriptBlock { (Get-Service -Name BioIDsvc).Status }

PSComputerName      RunspaceId                           Value  
--------------      ----------                           -----  
onpremise.bioid.com c270522c-e19e-439c-a525-9751c0deeb75 Running

To display the last 10 entries in the event log on the remote system running a BioIDsvc service you can use following command:

# First create a remote session if needed
$RemoteSession = New-PSSession -ComputerName "onpremise.bioid.com" -Credential "~\Administrator"


# use Invoke-Command to execute the command in the remote session
Invoke-Command -Session $RemoteSession -ScriptBlock { Get-WinEvent -LogName BWSlog -MaxEvents 10 }

   ProviderName: BioIDWebService

TimeCreated                     Id LevelDisplayName Message                                                                                                                                                 
-----------                     -- ---------------- -------                                                                                                                                                 
23/03/2018 11:39:09              0 Information      Voice-Identifiers for partition 23 have been initialized with 0 classes ( 0 0 0 ). (Elapsed: 00:00:00.3706119)                                           
23/03/2018 11:39:09              0 Information      Periocular-Identifiers for partition 23 have been initialized with 0 classes ( 0 0 0 0 ). (Elapsed: 00:00:00.3952226)                                    
23/03/2018 11:39:09              0 Information      Face-Identifiers for partition 23 have been initialized with 0 classes ( 0 0 0 0 ). (Elapsed: 00:00:00.3923160)                                          
23/03/2018 11:39:09              0 Information      The BioID Graph IdentifyGraph_templates_23 is now running.                                                                                               
23/03/2018 11:39:09              0 Information      The BioID Graph VerifyGraph_templates is now running.                                                                                                   
23/03/2018 11:39:09              0 Information      The BioID Graph EnrollGraph_templates is now running.                                                                                                   
23/03/2018 11:39:09              0 Information      The BioID Graph PhotoVerifyGraph is now running.                                                                                                        
23/03/2018 11:39:09              0 Information      The BioID Graph LiveDetectionGraph is now running.                                                                                                      
23/03/2018 11:39:09              0 Information      The BioID Graph QualityCheckGraph is now running.                                                                                                       
23/03/2018 11:39:08              0 Information      Reading BWS configuration for 'bioidsvc.bioid.com' from MongoDB collection 'clients'.     

TLS Certificate installation with PowerShell 

To install the TLS server certificate first transfer the certificate file to the remote system and use a PowerShell session to login into the remote computer. Then use the Import-PFXCertificate command to import the certificate into the LocalMachine certificate store.

$plainpassword = "IAvvhMhhlACU58boyQXz"
$CertPassword = $plainpassword | ConvertTo-SecureString -AsPlainText -Force
Import-PFXCertificate -FilePath .\onpremise.bioid.com.p12 -CertStoreLocation Cert:\LocalMachine\My -Password $CertPassword                                                                                       

   PSParentPath: Microsoft.PowerShell.Security\Certificate::LocalMachine\My
 
Thumbprint                                Subject                                                                                                                                                          
----------                                -------                                                                                                                                                          
09HE8LGSVUW9N6BXVDOAH39A7DEG5MLOANHIK29F  C=DE, O=BioID GmbH, OU=BioID Device Certificate, CN=onpremise.bioid.com   

Display the Certificate Thumbprint

The certificates thumbprint is used to assign the correct certificate to the network port of the BioIDsvc service.To retrieve the thumbprint of the certificates installed in the LocalMachine certificate store following command can be used.

Get-ChildItem Cert:\LocalMachine\My

    PSParentPath: Microsoft.PowerShell.Security\Certificate::LocalMachine\my
 
Thumbprint                                Subject                                                                                                                                                          
----------                                -------                                                                                                                                                          
09HE8LGSVUW9N6BXVDOAH39A7DEG5MLOANHIK29F  C=DE, O=BioID GmbH, OU=BioID Device Certificate, CN=onpremise.bioid.com

Uninstall BioIDsvc

To uninstall the BioIDsvc the service has to be stopped first. Then the service entry in the Windows Registry has to be removed. In a last step the files belonging to the service are deleted from the disk.

Uninstalling on a local system

This applies either to a PowerShell window on a local system or an interactive remote session.

Stop-Service -Name BioIDSvc -Force
$BioIDSVCservice = Get-WmiObject -Class Win32_Service -Filter "Name='BioIDSvc'"
$BioIDSVCservice.Delete()
Remove-Item -Path "C:\Program Files\BioIDSvc" -Recurse

Uninstalling on a remote system

The same steps can be applied with Invoke-Command on a remote system.

# First create a remote session if needed
$RemoteSession = New-PSSession -ComputerName "onpremise.bioid.com" -Credential "~\Administrator"

# use Invoke-Command to execute the command in the remote session
Invoke-Command -Session $RemoteSession -ScriptBlock { Stop-Service -Name BioIDSvc -Force }

Invoke-Command -Session $RemoteSession -ScriptBlock { $BioIDSVCservice = Get-WmiObject -Class Win32_Service -Filter "Name='BioIDSvc'"} 
Invoke-Command -Session $RemoteSession -ScriptBlock { $BioIDSVCservice.Delete() }
Invoke-Command -Session $RemoteSession -ScriptBlock { Remove-Item -Path "C:\Program Files\BioIDSvc" -Recurse }