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:
BioIDWebService.svc
, the REST-API through the path extension
).
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!
Item | Name |
---|---|
On-Premise BWS installation package | bioidsvc.zip |
BioIDsvc production system | onpremise.bioid.com |
Administrator workstation for installation | workstation.bioid.com |
MongoDB Database Server | mongodb.bioid.com |
TLS Server Certificate installed on onpremise.bioid.com |
Cert:\LocalMachine\My\55D7B0D345775A0A6DADE157EAF9DE05430EE096 |
X.509 Client Certificate installed workstation.bioid.com |
Cert:\CurrentUser\My\80F0BFC6A3450441EF3F6A4D5B470518A0C2E72B |
For a production installation, BioIDsvc requires the following system conditions, either as a physical system or as a VM in a virtualized environment.
OS Enviroment | 64 bit Microsoft Windows Server 2019 or newer (Windows Server 2016 with .NET Framework 4.7.2 installed can be used as well) |
Software | MongoDB Version 3.2 or newer (on same or remote system) |
CPU | Intel Xeon E5 v3 with 2 cores |
RAM | At least 4 GB RAM |
Storage | After startup the service runs in main memory and requires no hard drive space. For installation and for entries in the Windows event log, some MBs of hard drive space are needed. |
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.
Incoming Service | Port | Outgoing Service | Port |
---|---|---|---|
HTTPS | 443 (TCP) | HTTPS | 443 (TCP) |
Remote Desktop Protocol (RDP) | 3389 (TCP/UDP) | MongoDB | 27017 (TCP) |
Remote PowerShell | 5985 / 5986 (TCP) |
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.
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 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 service.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.
The configuration file in the setup directory of the installation package has to be modified according to the target environment.
PSedit
in the Windows PowerShell ISE.
Two elements serve to configure the BioIDSvc: the configuration file (service.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 theservice.
The .NET configuration file service.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.
Parameter | Description |
---|---|
SoapEndpoint |
The well-formed URL for SOAP access to the service (WCF Endpoint). As a protocol,
The host name must be the FQDN of the server in accordance with the SSL certificate, the path can be freely selected
(we recommend simply using bws , e.g.
https:// servername.domain/bws) .
|
WebApiEndpoint |
The well-formed URL for Web API (RESTful) access to the service. As a protocol,
The host name must be the FQDN of the server in accordance with the SSL certificate, the path can be freely selected
(we recommend simply using
api , or extension as in BWS, e.g. https:// servername.domain/api ).
|
UpdateConfigurationInterval |
The service loads its client configuration from the database once at startup, and then again after the time interval defined here.
The update interval for configuration updates in the format hh:mm[:ss] (something between 1 minute and 1 hour).
|
GenerateReportsInterval |
The service regularly generates a usage report. From the log files in the database, daily and monthly usage calculations are created and stored back in the database (collection
This happens shortly after the startup of the service and after the time interval defined here. The interval format is hh:mm[:ss] (something between 1 and 24 hours).
|
ConnectionString{storage} |
The MongoDB Connection String to store and load the biometric data associated with the named
The service supports only a single storage (required according to the definition of a Biometric Class ID), which is used here as well as in the client configuration.between 1 and 24 hours).
|
MongoDBConnectionString |
The MongoDB Connection String, used to write the log data and to read the client configurations. The two connection string values are usually identical, e.g. mongodb://server.domain:27017. |
Syntax:
install-bioidsvc.ps1 [[-sslThumbprint]
Parameter
-sslThumbprint
: The optional thumbprint of the SSL certificate in LocalMachine/My
certificate store that should be bound to the SSL port.
-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:
bin
directory are copied into the target directory C:\Program Files\BioIDSvc
.
service.config
file is copied, if it does not exist yet.
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.zip" -Destination "C:\Users\Administrator\Downloads"
Invoke-Command -Session $RemoteSession -ScriptBlock { Expand-Archive -Path "C:\Users\Administrator\Downloads\bioidsvc.zip" }
# OR if the zip file with the installation package was extracted on the local system
Copy-Item -ToSession $RemoteSession -Path "C:\tmp\bioidsvc\" -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\setup\install-bioidsvc.ps1" 55D7B0D345775A0A6DADE157EAF9DE05430EE096 }
******************************************************************************
Installing BioIDSvc from C:\Users\Administrator\Downloads\bioidsvc\bin
using configuration at C:\Users\Administrator\Downloads\bioidsvc\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.3190.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...
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)
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:
Parameter | Description |
---|---|
_id |
The unique name of the client to whom this entry belongs. |
Storage |
The name of the storage to which the client is granted access. The service supports only a single storage, therefore
a consistent name must be used, which the service retrieves with the help of the connection string in
ConnectionString{Storage} in the configuration file.
|
Partition |
The client is only granted access to the partition defined here. If this entry is omitted, the client has access to all classes in the given storage. |
IdentifyPartitions |
An optional array of partitions, each one requiring one identification module to be started. If only one Partition is defined, then only this partition can be used here. |
Expires |
The configured client expiry. After this date, the client does not get access granted to the service any more. |
SaveEnrollmentPatterns |
Defines whether the raw data used for enrollment should be saved. This data is not needed for
the service to function, but can help a user or administrator to understand which data has
actually been trained and added to the template. It is highly recommended to set this
parameter to true (as we are planning to update our classifiers, we may need to have
access to the raw data in the future to re-calculate the biometric templates).
|
LogSamples |
Defines whether data sent to the service should be saved. Used for diagnostic purposes and is typically turned off. (Saved samples are deleted after a certain time, typically after 21 days.) |
Certificates |
An optional array of certificates that the client can use for authentication with SOAP requests. Each entry
in this array has at least the element Thumbprint containing the thumbprint of the certificate,
and the optional element Expires with the ISO 8601 expiration date of the certificate.
|
ClientApps |
An optional array of App-ID/-secrets that the client can use for Basic Authentication for REST calls.
Each entry in this array consists of the elements Identifier , the unique App-ID, and the element
PasswordHash , the hash of the corresponding secret.
|
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,
"Expires" : ISODate("2018-06-10T12:00:00.000Z"),
"SaveEnrollmentSamples" : true,
"LogSamples" : true,
"ClientApps" : [
{
"Identifier" : "testclient.1",
"PasswordHash" : "pbkdf2:10000:3DntNYmkB57KMNfAy+R7vcnR:gY0h5sxz6LDgJhnCSXEUQOMDwia3pwDh9EzVnPum"
}
]
}
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),
Expires : ISODate("2021-12-31T12:00:00.000Z"),
SaveEnrollmentSamples : true,
LogSamples : false,
ClientApps : [ { Identifier : "testclient.1", PasswordHash : "pbkdf2:10000:3DntNYmkB57KMNfAy+R7vcnR:gY0h5sxz6LDgJhnCSXEUQOMDwia3pwDh9EzVnPum" },
{ Identifier : "sample-rest-app.2345739", PasswordHash : "pbkdf2:10000:Eca3iWXJ4Gq592U7hM5jO8MO:i6bdQVgwx30R2UAHBHopl+ZjedjFrQLpBuiBeZPw" } ] } )
In general we distinguish between three types of data:
Biometric data is managed in various collections according to the biometric trait face, 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:
Collection | Description |
---|---|
FaceTemplates | The calculated biometric face 'Templates'. |
FaceFeatures | The biometric 'Features' extracted from an image. The face template is then calculated from all features in a class. |
FaceFeatures | The biometric 'Features' extracted from an image. The face template is then calculated from all features in a class. |
FacePatterns | The biometric 'Features' extracted from an image. The face template is then calculated from all features in a class. |
PeriocularTemplates | The calculated biometric periocular 'Templates'. |
PeriocularFeatures | The biometric periocular-'Features' extracted from an image. The periocular template is then calculated from all features in a class. |
PeriocularPatterns | Optional original images. Used only for informational purposes, e.g. to manually verify which images were actually used to generate the biometric template for a class. |
VoiceTemplates | The calculated biometric voice Templates'. |
VoiceFeatures | The biometric 'Features' extracted from the audio data. The voice template is then calculated from all features in a class. |
VoicePatterns | Optional original audio data. Used only for informational purposes, e.g. to manually verify which audio files were actually used to generate the biometric template for a class. |
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.
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, enabling 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.
There are three places, where configuration data is stored:
service.config
install-bioidsvc.ps1
(optional)
The configuration file service.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 server
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.
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 }
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'.
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
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
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.
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
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 }