Fingerprint injection | Simulate sensor authentication

Many mobile devices now support hardware features that authenticate the user by reading a fingerprint or by analyzing the user's photo as captured by the device camera. Using these features, applications can better authenticate the user's identity. This is used both by the operating system, when opening the device, and by applications, for example financial and medical applications that require conclusive identification before accessing sensitive records.

Perfecto offers support for testing and automation of these applications on Perfecto Lab devices. When testing an application dependent upon the authentication hardware, the main feature to test is the ability of the application to address the following scenarios:

The user is successfully identified.
The user is not authenticated by the sensor.

To cover these scenarios, Perfecto supports fingerprint injection (via manual testing as well as an Appium extension) that can be used at the point of authentication to supply the different authentication results.

Known limitations

At this point, the sensor authentication feature has the following limitations:

The feature is supported for:
- All iOS versions supported by Perfecto
- Android devices running version 6.0 and later
iOS requires that the device undergo an enrollment procedure with the Touch ID or Face ID service prior to using the authentication hardware (see Special considerations for iOS devices). However, device enrollment is not supported for devices running iOS 15 or later.
The feature is not supported for applications created with the Xamarin environment when using the Secure Keychain interface library.
The feature is designed to allow testing how an app responds to various authentication results and not to test how the OS behaves. It is not designed to test the mobile OS behavior. For example, each mobile OS may decide to lock the user out of subsequent authentication attempts after a certain number of failed attempts. However, when using this feature, authentication does not go through the OS itself. Therefore, the automatic OS behavior will not apply. To test how the app responds to a case where the user has been locked out, Perfecto supports injecting this error code explicitly using the fingerprint injection command.

Testing flow for fingerprint authentication

When testing or automating an application that uses face ID or Fingerprint authentication, either manually or as part of an automation script, make sure to follow this flow:

Select the device on which to run the application. Be sure that the device selected supports the desired authentication feature.
Install the application onto the device. Use Perfecto's sensor instrumentation to prepare the application for testing/automation.
Start the application.
When the application reaches the point of authentication (that is when the authentication dialog box opens), do the following:
- If testing manually, trigger the desired authentication result by using the options available with the fingerprint/face ID option. For more information, see Inject a fingerprint or face ID.
- If using automation, invoke the Set sensor authentication command to supply the authentication response.
Make sure that the application has responded to the authentication result as expected.

Error messages

The following error messages may appear as a result of using the interactive sensor authentication simulation feature:

Target application is not instrumented: Appears if you activate the injection when the active application is not instrumented for sensor authentication simulation.
Operation timed out: Appears if you activate the injection when the application is not accessing the sensor reader.
Fingerprint command not supported: Appears if the device does not support the sensor reader hardware or is running a version of the device OS that does not support the functionality.
BACKEND_FAILURE_ERROR: setSensorAuthentication command failed. Reason: handset server: Connection error: Appears if you have multiple applications with sensor instrumentation open.

Device prerequisites

Fingerprint simulation works with any Android or iOS device that supports the hardware fingerprint reader.

FaceId works only on iOS devices that support face identification (iPhone X and later).

Appium support

To activate the functionality from an Appium script, do the following:

To install the application:

If installing the application as part of the driver creation, add the following capability setting:
Copy
```
capabilities.setCapability("sensorInstrument", true);
```

If installing with the Perfecto command mobile:application:install, supply the sensorInstrument parameter with a value of "sensor".

Copy

Map<String, Object> params = new HashMap<>(); // use either the "identifier" or "name" parameter to identify the app params.put("sensorInstrument", "sensor"); // <<additional parameters to identify the application to install>> ooo driver.executeScript("mobile:application:install", params);

To simulate the sensor reader:

At the point where the script needs to simulate the sensor reader:

Identify that the application is prompting the user to identify through the sensor reader.

Run the mobile:sensorAuthentication:set command:

Copy

Map<String, Object> params = new HashMap<>();
// use either the "identifier" or "name" parameter to identify the app
params.put("identifier", <application package identifier>); 
params.put("resultAuth", "fail");  // may be either "fail" or "success"
params.put("errorType", "lockOut");  // may be authFailed, userCancel, userFallback, systemCancel, or lockout
driver.executeScript("mobile:sensorAuthentication:set", params);

If the automation script is simulating a failure result (meaning the resultAuth parameter is set to fail), the errorType parameter indicates more information on why the authentication failed. This allows the script to activate different failure scenarios. The error types supported include:

authFailed - indicates that the fingerprint was not recognized and therefore not authenticated.
userFallback - indicates that the user selected an option to provide a different authentication method, for example using a password.
userCancel - indicates that the user selected an option to cancel the authentication.
systemCancel - indicates that the system cancelled the authentication.
lockout - indicates that this is a multiple-failure scenario and the user account should be locked.

Special considerations for iOS devices

As mentioned above, iOS requires that the device undergo an enrollment procedure with the Touch ID or Face ID service prior to using the authentication hardware. If the device has been enrolled with the identification service, the procedure detailed above works as described. If the device has not yet been enrolled, the OS does not prompt the user to provide authentication, and Perfecto intercedes and provides a prompt (see the following image).

Perfecto's iOS biometric implementation currently does not support the scenarios described in the following table.

Scenario	Workaround
The app is moved to the background during an authentication command.	None
Enrolled devices only: The OS authentication prompt is cancelled.	To simulate how the app responds in this situation, explicitly inject `userCancel`.
Enrolled devices only: The OS message “Try Face ID / Touch ID again” appears.	None. This does not affect the app because it does not receive any notification from the OS when this message is displayed
Enrolled devices only: The OS message "Reached max failed authentication attempts" appears.	To simulate how the app responds in this situation, explicitly inject `lockout`.

Special considerations for Android devices

On Android, Perfecto supports injecting fingerprints to apps using the legacy Fingerprint API as well as the newer Biometric API.

When testing apps using the legacy Fingerprint API, there is no need to physically enroll the device to fingerprint. However, to test apps using the Biometric API, the device must undergo a fingerprint enrollment procedure for fingerprint injection to work.

When injecting fingerprint authentication results to the app, the app behavior varies according to the API used:

For apps using the Fingerprint API, the normal app/OS authentication popups will appear.
For apps using the Biometric API, due to technical reasons, a custom Perfecto popup similar to the original OS popup is used to indicate that authentication is needed. When fingerprint injection fails, a text message indicates the result.
To test how the app responds when a user has been locked out, you can inject the error code explicitly by using the fingerprint injection command with the errorType parameter set to Lock Out. For more information, see Set fingerprint.