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:

BWS Instance


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:

BWS Manage


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 transferred 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 PermissionClient Permission
OperationOwnerEditSupportViewOwnerEditSupportView
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.

Scripting

The BWS Management API is a Restful Web API. We provide a Swagger UI to interact with the API easily using a web browser. But the API of course can also be used from any kind of programming or scripting language. Please note that we use PowerShell sample scripts throughout this documentation, but other tools or languages can be used as well. 

Authentication

All BWS Management APIs require an OAuth2 access token for authentication. The token at least needs to have an identifier for the user (sub-claim) and the bwsmanage-claim be issued. You can request such a token using the BioID Connect OAuth 2.0 token endpoint. To get such a token issued, some requirements must be fulfilled:

  • You need to have a BioID Connect user account. We recommend to create a specific technical account for this purpose here:  https://account.bioid.com/register. Please do not use multi-factor authentication with this account!
  • Use the technical account to create a BioID Connect client app here: https://account.bioid.com/connect (click on "Your BioID Connect client apps..." - Manage and register a new client app). Please enter a "Application Name" and "Authorized Redirect URIs" (although the later is not needed for this purpose). With the new client app, a Client-ID and Client-Secret will be created. 
  • Now you have to let us know that you want to use the new BioID Connect client app to call into the BWS management API, so we can apply the required bwsmanage scope to this client app (the UI currently does not provide this feature). Please send an email to support@bioid.com (or your BioID contact person) also mentioning the created Client-ID.

Having this requirements fulfilled, you should have a (technical) BioID Connect user account and a BioID Connect Client-ID together with a Client-Secret (referenced in the scripts as $clientId and $clientSecret) available, that you can use to call into the BioID Connect token endpoint to retrieve an access token: 

Fill authorization header with BioID Connect access token
# get a token from BioID Connect
$credentials = Get-Credential -Message "Enter your credentials to access BWS Management API"
$body = @{grant_type='password'; username=$credentials.UserName; password=$credentials.GetNetworkCredential().password; client_id=$clientId; client_secret=$clientSecret; scope='managebws offline_access'}
$response = Invoke-WebRequest -Uri "https://account.bioid.com/connect/token" -Method Post -Body $body
# and put the created access-token into an authorization-header for later use with the BWS Management API
$token = (ConvertFrom-Json $response.Content).access_token
$headers = @{"Authorization" = "Bearer " + $token}
# optionally you can keep the refresh-token for later use
$refreshToken = (ConvertFrom-Json $response.Content).refresh_token

Once a token has been requested, optionally the refresh-token can be used to fetch new access-tokens:

$body = @{grant_type='refresh_token'; refresh_token=$refreshToken; client_id=$clientId; client_secret=$clientSecret; scope='managebws offline_access'}
$response = Invoke-WebRequest -Uri "https://account.bioid.com/connect/token" -Method Post -Body $body
$token = (ConvertFrom-Json $response.Content).access_token
$headers = @{"Authorization" = "Bearer " + $token}
# Currently BioID Connect does not support sliding refresh-tokens and the refresh-token expires after 8 days!
#$refreshToken = (ConvertFrom-Json $response.Content).refresh_token


Script BWS Management API

As we now have an authorization header available for the BWS Management API calls, we should be able to call into the API. But we still need some permissions to do so:

  • You need to have owner permissions on the BWS installation or BWS client you want to manage.
  • Use the BWS Portal and add (edit-) permissions for the technical account to the client or installation the script is going to access.

Here is a short example of how to use the authorization header to get some information about a BWS client (running on the Multitenant installation) we have access to (the name of the BWS client is assumed to be in the $client variable):

$response = Invoke-WebRequest -Uri "https://bwsmanage.bioid.com/api/v1.0/clients/Multitenant/$client" -Headers $headers
$response.Content | ConvertFrom-Json

You can find a list and a description of all available BWS Management APIs with our Swagger UI.


Sample Scripts

Count the number of classes that have a face template enrolled:
$response = Invoke-WebRequest -Uri "https://bwsmanage.bioid.com/api/v1.0/classes/Multitenant/$client/Face/classcount" -Headers $headers
$response.Content
Get a list of classes enrolled with a BWS client:
$response = Invoke-WebRequest -Uri "https://bwsmanage.bioid.com/api/v1.0/classes/Multitenant/$client/?maxclasses=10000" -Headers $headers
$response.Content | ConvertFrom-Json
Get the bws-log of a BWS client of the last hour:
$now = Get-Date
$to = [System.Web.HttpUtility]::UrlEncode($now.ToString("o"))
$from = [System.Web.HttpUtility]::UrlEncode($now.AddHours(-1).ToString("o"))
$uri = [System.Web.HttpUtility]::UrlPathEncode("https://bwsmanage.bioid.com/api/v1.0/logs/Multitenant/$client") + "?from=$from&to=$to"
$response = Invoke-WebRequest -Uri $uri -Headers $headers
$response.Content | ConvertFrom-Json