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.
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.
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.
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.
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.
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.:
The administrator of an installation adds clients to the database by simply creating a new client. The following information is needed:
Using BWS portal, the ownership of the new client configuration can be transferred to a developer immediately, or later, see below.
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.
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:
Two write permissions and two read permissions are defined for both installation administrators and client developers as follows:
A full list of access rights is shown in the table below.
| Installation Permission | Client Permission | |||||||
|---|---|---|---|---|---|---|---|---|
| Operation | Owner | Edit | Support | View | Owner | Edit | Support | View |
| Installations | ||||||||
| Create | ||||||||
| Read | ||||||||
| Update | ||||||||
| Delete | ||||||||
| attach/detach certs | ||||||||
| Clients | ||||||||
| Create* | ||||||||
| Read | ||||||||
| Update* | ||||||||
| Update flags* | ||||||||
| Delete*** | ||||||||
| attach/detach certs* | ||||||||
| Certificates | ||||||||
| read info | ||||||||
| download | ||||||||
| upload | ||||||||
| delete | ||||||||
| Web API keys | ||||||||
| Create* | ||||||||
| Read | ||||||||
| Udate* | ||||||||
| Delete* | ||||||||
| Classes | ||||||||
| Read | ||||||||
| Delete** | ||||||||
| Delete pattern** | ||||||||
| Client Permissions | ||||||||
| Create | ||||||||
| Read | ||||||||
| Update | ||||||||
| Delete | ||||||||
| Installation Permissions | ||||||||
| Create | ||||||||
| Read | ||||||||
| Update | ||||||||
| Delete | ||||||||
| Usage | ||||||||
| read client usage | ||||||||
| read instance usage | ||||||||
| Logs/Accounting | ||||||||
| read client log | ||||||||
| read samples | ||||||||
| read installation log | ||||||||
| read diagnostic log | < | |||||||
| Storages | ||||||||
| read | ||||||||
***) *) and **) to delete all classes of the client.
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.
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:
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.
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:
# 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_tokenOnce 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_tokenAs 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:
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$response = Invoke-WebRequest -Uri "https://bwsmanage.bioid.com/api/v1.0/classes/Multitenant/$client/Face/classcount" -Headers $headers
$response.Content$response = Invoke-WebRequest -Uri "https://bwsmanage.bioid.com/api/v1.0/classes/Multitenant/$client/?maxclasses=10000" -Headers $headers
$response.Content | ConvertFrom-Json$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