Usage scenarios for the BWS Web API

Application usage scenario

A typical application using the BWS Web API performs the following three steps:

  1. Requests a BWS token using the BWS Token Web API.
  2. Upload two or more captured images using the BWS Upload Web API.
  3. As soon as enough samples have been uploaded, call one of the biometric task web API, i.e. the BWS Verification or BWS Enrollment Web API.

Unified user interface usage scenario

A typical application using the BWS Web API performs the following three steps:

  1. Requests a BWS token using the BWS Token Web API.
  2. Redirect the user to the BWS unified user interface.
  3. The BWS unified user interface redirects the user back to the specified return URL after finishing taking samples where the result can be retrieved using the BWS Result Web API.

Motivation

BioID provides powerful scalable biometrics with its cloud-based BioID Web Service (BWS). This web service has been designed using a service-oriented architecture (SOA) and is implemented as a Windows Communication Foundation (WCF) service. It uses the SOAP protocol (with HTTPS as secure transport protocol) for communication and utilizes client certificates for authentication.

Although SOA based web services using SOAP as transport protocol are widely accepted in enterprise environments, lightweight approaches like RESTful Web APIs gain more and more popularity. Thus we implemented the BWS Web API to support this software architecture approach also.

Implementation Details

One of the reasons to use the SOAP based SOA approach for the BWS is our focus on verifiable secure sever-to-server communication. This is the main model for a BWS implementation. But as client systems allow for more computing power and complexitiy now, e.g. as apps on modern smartphones, we want to support those scenarios as well.

Both SOAP based BWS and the RESTful Web API utilize TLS/SSL (HTTPS) as secure transport protocol. But we cannot use the X.509 certificate based client authentication for the web API as we use it for BWS. Therefore we decided to use a token based mechanism: before you can do anything else with the BWS Web API, you need to get a BWS Token.

To request a BWS Token you need to register your application with your BWS subscription (you can do this as a registered user in the BWS Management portal). With the App-ID and App-Secret you received by the registration you can request a BWS Token by sending a simple http-get request to the BWS Token API using basic authentication. On success you get the token encoded as a JSON Web Token (JWT) in return. Typically the BWS Token is intended to be used for only one biometric operation (such as verification or enrollment).

With the token you can make calls to the other web APIs like upload, verification or enrollment. Thereto the token is supplied with the authorization header using the authorization method JWT.