BWS Management

BioID® Web Service

The BioID Web Service (BWS) provides on-demand cloud-based multimodal biometrics as a service. In particular, it offers highly accurate face, eye and voice recognition with advanced liveness detection that asserts user presence with high levels of assurance. BWS' built-in patented anti-spoofing detection against photo and video replay attacks helps to prevent identity frauds.

BWS Installation

The BWS is available as a cloud service as well as on-premises as a Windows service. The BWS cloud service is typically hosted by BioID on Azure using Azure Storage services. On-premises installations and other BioIDSvc installations, on the other hand, use a MongoDB database. Regardless of where BWS is being hosted, here is what a BWS Installation looks like:

The BWS is a standalone Windows service. Depending on the platform it is running on, it is assembled as a Azure Worker role running in the Azure cloud or as a Windows NT Service running on Windows servers. It self-hosts the Windows Communication Foundation (WCF) for its standard SOAP access and a simple HTTP server to support RESTful Web APIs. To access the service via SOAP, clients need to authenticate with their certificates. To access the service via Web API, the clients have to use basic authentication with an application-id and -secret, or bearer authentication with a previously fetched bearer token.

To implement its biometric functionality, BWS makes use of the BioID Framework (a BioID in-house framework to easily implement image- and signal-processing work-flows). The hosted BioID Runtime runs multiple BioID Graphs, each performs a specific biometric operation.

Depending on the platform, the BWS keeps its data in a MongoDB database (BioIDSvc) or in various Azure Storages.

It is very typical that a BWS installation consists of multiple instances and a load-balancer in front of it.

BWS Management

For the management of all BWS installations, a centralized BWS Management API is used together with a uniform control interface, the BWS Portal. The Management API supports both cloud and BioIDSvc (i.e. typically on premises BWS installations using a MongoDB database) installations.

Below is a system overview with all the management components:

The core components are the service that provides the BWS Management API, and the user interface (an Angular single page app) called BWS Portal.

  1. Access Control: The BWS Portal uses the OpenID Connect Identity Provider BioID Connect to authenticate the users.
  2. Once a user is authenticated, BWS Portal uses the OAuth2 access token (and, for convenience, the refresh token) delivered by BioID Connect to access the Management API.
  3. The BWS Management API always validates the access token at the OpenID connect introspection endpoint of BioID Connect before it allows access.
  4. The BWS configuration data and the user permissions to the various objects are kept in the BWS configuration SQL database.
  5. Changes made to the configuration can be effected by the Management API by one of the following:
    1. Using a Azure management certificate to update the configuration at the installation specific Azure storage.
    2. Using a connection string to the installation specific MongoDB database (as provided by the BWS installation administrator) to update the configuration collection (clients).
  6. The Management API can, upon request, perform BWS SOAP API calls on behalf of a configured client. This is currently only necessary for biometrics related management tasks such as deleting a class or deleting a pattern from a class. If no certificate is attached to a client, these tasks must be performed explicitly by the BWS client application.

Installation Administration

By design, there are two type of users: installation administrators and client developers. In principle, the administrators manage the permissions to the installation as well as the creation of clients (tenants) for the developers. In addition, the administrators oversee the usage of the installation, and optionally manage the certificates, which are needed by clients who want to use the SOAP API.

Initial installation configuration

The initial installation configuration entries in the BWS database are created by BioID. The ownership of the installation is then transfered to one of the administrators of the installation. This administrator is required to update the installation configuration in order to connect the database entry with the real installation by adding the MongoDB connection string. It should be noted that the connection string is always encrypted before it gets stored in the database and only Owners of the installation have access to the connection string.

In addition to the connection string, the URLs to the endpoints must also be adapted. This information is necessary for the developers to find the API endpoints.

Please note that for BioIDSvc installations, the configuration file BioIDSvc.exe.config needs to have the according configuration entries, see BioIDSvc documentation.

As soon as a connection string to a MongoDB database is entered or modified, the BWS Management API will attempt to add all existing clients from this database to the BWS database. The administrator typically gets a list of messages explaining what has happened, e.g.:

  • Client '{clientName}' is in the BWS database (...) and in the MongoDB database of the installation (...) and has not been synchronized. Note that, when the client is updated the next time, the BWS database version is written to the installation! → Please review this client-configuration and update if necessary.
  • Certificate '{certName}' (with thumbprint {thumbprint}) has been added to client '{clientName}'. → The client uses a certificate that is known by the BWS database; everything is fine.
  • A certificate with thumbprint {thumbprint} is not in the BWS database and cannot be added to client '{clientName}'. Note that, when the client is updated the next time, this certificate setting is lost! → Well, the certificate was added manually. We recommend that you upload it to the database and attach it to the client, so that developers can download the certificate when needed.
  • Client '{clientName}' has been synchronized from the MongoDB database of the installation to the BWS database. Please modify the permissions of this client to grant the developers access to the client. → The client has been synchronized, but the developers have no access yet as you have been set as the Owner
  • Client '{clientName}' is only in the BWS database, but not in the MongoDB database of the installation. You have to update this client explicitly so that the BWS database version is written to the installation! → Please review this client and figure out what could have happened.

Adding clients

The administrator of an installation adds clients to the database by simply creating a new client. The following information is needed:

  • A unique name for the client.
  • An expiry date. As each installation supports multi-tenants, each client has a limited lifetime, which must be configured upon creation and can be modified later. Expired clients will cease to function.
  • An optional certificate can be preloaded if SOAP access is needed (this can always be done later, see below).
  • A Storage for the client to store its data (most installations have only one Storage available, particularly BioIDSvc installations).
  • A Partition for the client to use. One can choose the next available Partition or manually enter the Partition number. A Partition number can only be used by exactly one client.
  • An optional flag to enable identification API. In this case an additional 'Graph' is started on the installation that enables the client to execute biometric identifications on this partition.
  • Some initial logging settings, which can always be modified by the developers.

Using BWS portal, the ownership of the new client configuration can be transferred to a developer immediately, or later, see below.

Upload certificates

For accessing the BWS 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 certificate on the client matches one of the configured certificates for this client. The certificates can be issued by one's own local PKI or tools like OpenSSL. Alternatively, certificates can also be issued by BioID: simply forward such request to support@bioid.com together with name of the certificate and how long it shall be valid. A client certificate issued by BioID will be uploaded to the installation accordingly.

A valid X.509 certificate (with private key embedded) can also be uploaded by using the certificates button of the installation. An uploaded certificate needs to be assigned to a client using the client's certificates button. When a certificate is assigned, developers can download it as needed.

Client Administration

BWS clients are created by an installation administrator. The administrator can move or add the ownership of the client to a developer.

Selecting a client (all accessible clients are listed by default in the BWS Portal start screen, or by selecting ANALYTICS - Clients) brings up the usage dashboard and a Configuration menu item for the selected client. Depending on the permissions to the client, one can manage certain client settings here:

  • Manage user permissions to the client (Owners only).
  • Switch logging of images on or off (requires write permission).
  • Create and update Web API keys (requires write permission).
  • Download or request client certificates (requires write permission).

Permissions

Two write permissions and two read permissions are defined for both installation administrators and client developers as follows :

  • Owner (full access): Owners of an installation are the administrators of that installation. Owners of a client are developers with full access to all client information including logged samples or biometric classes. Owners can also assign permissions to other users.
  • Edit (read/write access): Users with edit permission to an installation or client have the same rights as Owners except that they cannot add or modify permissions.
  • Support (read access): Support rights (particularly to clients) are assigned to support users for them to view logged data temporarily typically for troubleshooting purpose.
  • View (read only): Typically for users who need only the access to the usage statistics of an installation.

A full list of access rights is shown in the table below.

  BWS Database Permissions

Installation Permission Client Permission
Operation Owner Edit Support View Owner Edit Support View
Installations







Create







Read (tick) (tick) (info) (info) (info) (info) (info) (info)
Update (tick) (tick)





Delete (tick)






attach/detach certs (tick) (tick)





Clients







Create* (tick) (tick)





Read (info) (info) (info)
(tick) (tick) (info) (info)
Update* (tick) (tick)





Update flags*



(tick) (tick)

Delete*** (tick) (tick)





attach/detach certs* (tick) (tick)





Certificates







read info (tick) (tick) (tick)
(tick) (tick) (tick) (tick)
download (tick) (tick)





upload



(tick) (tick)

delete



(tick)


Web API keys







Create*



(tick) (tick)

Read



(tick) (tick)

Update*



(tick) (tick)

Delete*



(tick) (tick)

Classes







Read



(tick) (tick) (question)
Delete**



(tick) (tick)

Delete pattern**



(tick) (tick)

Client Permissions







Create



(tick)


Read (tick) (tick)

(tick) (tick)

Update



(tick)


Delete



(tick)


Installation Permissions







Create (tick)






Read (tick) (tick)

(tick) (tick)

Update (tick)






Delete (tick)






Usage







read client usage (tick) (tick) (tick) (tick) (tick) (tick) (tick) (tick)
read instance usage (tick) (tick) (tick) (tick)



Logs/Accounting







read client log (tick) (tick) (tick) (tick) (tick) (tick) (tick) (tick)
read samples



(tick) (tick) (tick)
read installation log (tick) (tick) (tick) (tick)



read diagnostic log (tick) (tick) (tick)




Storages







read (tick) (tick)





(tick) - full access
(info) - partial access
' ' - no access
(question) - currently no access, but might be reasonable (e.g. for "Biometric Officers")

*) The settings from the BWS database are sent to the configuration storage of the BWS installation (Azure config file or MongoDB clients table).
**) Requires a certificate assigned to the client to let the BWS management API call into the BWS installation on behalf of the client.
***) *) and **) to delete all classes of the client.

Note: There are some additional overall database permissions which are not listed in the table above, e.g. permissions that are needed to create new Installation entries, to upload certificates issued by BioID to an installation, as well as for accounting purposes.