Inter-App communication for Android

Launching BioID app

The BioID facial recognition app uses standard Android Intents for inter-app communication.
In order for your Android app to open the BioID app, you must create an intent and call startActivityForResult(intent, requestCode).

To enroll a user biometrically

Uri uri = new Uri.Builder()
		.scheme("bioid-enroll")
		.appendQueryParameter("access_token", accessToken) // required: BWS web token that has previously been issued by the token extension
		.appendQueryParameter("state", state) // optional: client specific data to maintain state between request and callback (e.g. some information about the user you are verifying)
		.build();
Intent intent = new Intent(Intent.ACTION_VIEW);
intent.setData(uri);
	
startActivityForResult(intent, requestCode);


To verify a user biometrically

Uri uri = new Uri.Builder()
		.scheme("bioid-verify")
		.appendQueryParameter("access_token", accessToken) // required: BWS web token that has previously been issued by the token extension
		.appendQueryParameter("state", state) // optional: client specific data to maintain state between request and callback (e.g. some information about the user you are verifying)
		.build();
Intent intent = new Intent(Intent.ACTION_VIEW);
intent.setData(uri);
	
startActivityForResult(intent, requestCode);


Before you begin, you have the choice

A. Do you want to use BioID as your identity provider?

If you want to use BioID as an identity provider (information like username, password, email address etc. stored by BioID) then BioID Connect is the right choice. The integration is easy, especially if you already support OpenID Connect or OAuth 2.0. Currently the service is available free of charge.

In the future we may charge for the service or limit the number of transactions.

A.1 Get a Client ID

To connect with the app using BioID Connect requires a client ID and client secret. If you already registered in the app, simply use the account you created. If you do not yet have a BioID account you will first need to register. Then go to your profile and select BioID Connect to register a new client application. You will then receive your client ID and secret.

A.2 User registration and enrollment

Your end users install the BioID app and sign up for a BioID account; they will then be prompted to enroll their biometrics.



B. Do you want to use your own identity management?

If you want to use your own identity management you can enhance your app to use BioID Web Service directly. In this case your users cannot be enrolled through the app. You must enroll them through a separate channel, for instance on your website using our Unified User Interface.

The biometric data is stored anonymously with no other personally identifiable information such as a name or email address.

B.1 Request a trial instance of BioID Web Service (BWS)

You can apply for a trial instance of the BioID Web Service. After the trial instance has been set up you can continue to create and configure your BWS client application.

B.2 Register a BWS client application

Create and configure your BWS client application on BWS Portal.

Select your BWS Client and go to Configuartion section and create a Web API key. In the dialog window the app identifier and secret is shown. Both values are required for your app later on (the real data replacing the placeholder text for CLIENT_APP_ID and CLIENT_APP_SECRET constants in sample code below).

Take a look at the Web API endpoint for the example https://bws.bioid.com/extension (BWS-Installation Multitenant). In this case the BWS instance name is bws. This would replace the dummy text for the BWS_INSTANCE_NAME constant in the sample code below then.

For the creation of BCIDs for users in your app the following information is needed

Storage e.g. bws 
Partition e.g. 12 
ClassID – this is a unique number you assign to the user, e.g. 4711. The BCID with the example values from above is bws.12.4711. This value consisting from the three parts storage, partition and ClassID separated by a period ('.') would replace the dummy text for the BCID constant in the sample code. For more information about BCID take a look at Biometric Class ID.

Now you have all necessary data to call BWS!

B.3 User registration and enrollment

When you use the app with your own identity management, the app simply provides a pass-through function for enrollment and verification using the BWS token you provide, and ignores the BioID account (if any) registered to the user's device.

B.4 Request BioID Web Service (BWS) Token

The following sample code explains how to request a BWS token using the popular library Retrofit 2.
Feel free to use any network library which you are comfortable with.
For more information please take a look at Request a BWS token to be used for authorization.

// Retrofit service definition
interface BwsService {
	@GET("/extension/token")
	Call<String> getToken(@Query("id") String appId, @Query("bcid") String bcid, @Query("task") String task);
	@GET("/extension/result")
	Call<OperationResult> getResult(@Query("access_token") String accessToken);
	class OperationResult {
		boolean Success; // all other JSON properties are not used in this sample and therefore not included in this class
	}
}
	
// create Retrofit service with basic-auth support
BwsService createBwsService() {
	Interceptor basicAuthInterceptor = new Interceptor() {
		@Override
		public okhttp3.Response intercept(Chain chain) throws IOException {
			Request request = chain.request().newBuilder()
					.addHeader("Authorization", Credentials.basic(CLIENT_APP_ID, CLIENT_APP_SECRET))
					.build();
			return chain.proceed(request);
		}
	};
	
	OkHttpClient httpClient = new OkHttpClient.Builder().addInterceptor(basicAuthInterceptor).build();
	
	Retrofit retrofit = new Retrofit.Builder()
			.baseUrl(String.format("https://%s.bioid.com", BWS_INSTANCE_NAME))
			.client(httpClient)
			.addConverterFactory(ScalarsConverterFactory.create())
			.addConverterFactory(MoshiConverterFactory.create())
			.build();
	
	return retrofit.create(BwsService.class);
}
	
// request BWS token for verification (for enrollment use the task "enroll")
bwsService.getToken(CLIENT_APP_ID, BCID, "verify").enqueue(new Callback<String>() {
	@Override
	public void onResponse(Call<String> call, Response<String> response) {
		if (response.code() == 200) {
			String token = response.body();
			Log.i(TAG, "obtained BWS token " + token);
		} else {
			Log.w(TAG, "requesting BWS token returned status code " + response.code());
		}
	}
	@Override
	public void onFailure(Call<String> call, Throwable t) {
		Log.w(TAG, "requesting BWS token failed", t);
	}
});

 B.5 Verify BWS Result

The inter-app communication is a good helper to interchange data between apps but not in a secure way. Therefore you must validate the BWS result in the callback to your app.
This can be done very simply.The BioID app calls your app back and your app receives a BWS result as access_token.

The following example code now shows you how to validate this BWS result token from your app. For more information please take a look at Fetches the result of the last biometric operation performed with the token provided.

// callback in response to calling startActivityForResult(intent, requestCode)
void onActivityResult(int requestCode, int resultCode, Intent data) {
	if (resultCode != Activity.RESULT_OK) {
		// biometric operation did not start -> no need to query result
		Log.i(TAG, "biometric operation did not start");
		return;
	}
	
	String state = data.getStringExtra("state");
	Log.i(TAG, "state which was previously set using the optional query parameter of the intent: " + state);
	
	String accessToken = data.getStringExtra("access_token");
	Log.i(TAG, "access_token to request result of biometric operation: " + accessToken);
}
	
// request result of biometric operation
bwsService.getResult(accessToken).enqueue(new Callback<BwsService.OperationResult>() {
			@Override
			public void onResponse(Call<BwsService.OperationResult> call, Response<BwsService.OperationResult> response) {
				switch (response.code()) {
					case 200:
						if(response.body().Success) {
							Log.i(TAG, "biometric operation was successful");
						} else {
							Log.i(TAG, "biometric operation was not successful");
						}
						break;
					case 204:
						Log.i(TAG, "biometric operation did not complete");
						break;
					default:
						Log.w(TAG, "querying result returned status code " + response.code());
				}
			}
	
			@Override
			public void onFailure(Call<BwsService.OperationResult> call, Throwable t) {
				Log.w(TAG, "querying result failed", t);
			}
});