User authentication with system biometric authenticators
Introduction
The OneWelcome Flutter plugin allows you to authenticate users with the system biometric authenticators. These authenticators are provided by the device's operating system (iOS - Touch ID and Face ID, Android - fingerprint) if they are available on the device. System biometric authenticators can be used for both: regular and mobile authentication. Users will be able to retry system biometric authentication as many times as the OS allows them to. If the OS system's biometric authenticators API returns an error for any reason (for example in case of too many failed attempts), the OneWelcome Flutter plugin will revoke the system biometric authenticator and will perform a fallback to PIN authentication.
Requirements
FaceID
iOS needs to have configured message displayed on FaceID alert. It's configurable by adding NSFaceIDUsageDescription
in your Info.plist
file.
Example configuration
Not specifying this property in your configuration will crash your application when you will try to use Face ID authentication.
Differences between Android and iOS
It should be noted that there are significant differences between Fingerprint on Android and Touch ID on iOS. As a result, some methods may be available on only one of the operating systems. This will be specified where applicable.
Enabling system biometric authenticator authentication
In order to enable fingerprint authenticator authentication for a user, the OneWelcome Flutter plugin provides the registerBiometricAuthenticator method. This function requires the user to be authenticated. After calling this method a pin authentication flow will be started which needs to be completed in order to successfully register the biometric authenticator.
Example code for registering the system biometric authenticator:
Fingerprint authentication may not be available on every device. In this case, or if the authenticator has already been registered, the above method will return an error.
Authenticate using Fingerprint
Once the fingerprint authenticator has been registered and set as the preferred authenticator, the user is able to authenticate using fingerprint. The method to do so is the same as for PIN, the Onegini.instance.userClient.authenticateUser(String profileId, OWAuthenticatorType? authenticatorType)
(Android only) If fingerprint authentication is a possibility for the user, extra handler methods must be implemented, as described in Fingerprint Authentication Flow. This is in addition to the PIN specific methods (which are necessary in case of fallback to PIN).
Example code to start the fingerprint authentication:
If the user fails to authenticate using fingerprint too many times (this limit is set by the OS), the fingerprint authenticator is automatically deregistered and the relevant tokens are revoked by the OneWelcome Flutter plugin. At this point, a fallback to PIN is performed, and the user is request to enter their PIN via PinAuthenticationOpenEvent
. If this too, fails, a platform exception will be thrown which is signalling the authentication has failed.
Fingerprint Events
The resulting fingerprint authentication flow will use the following events:
Event | Description |
---|---|
OpenFingerprintEvent | Fired when a new fingerprint authentication request is made. |
CloseFingerprintEvent | Fired when fingerprint scanning finished either with success or an error. |
ShowScanningFingerprintEvent | Fired when user scanned his fingerprint and the fingerprint validation \n\nis performed. That's a good moment to show an update on the UI informing\n\n user about received attempt. |
ReceivedFingerprintEvent | Fired when user provided incorrect fingerprint but still haven't reach the failed attempts limit. |
Fingerprint Authentication Flow
This required flow contains the following steps:
- Fingerprint authentication is started by calling
authenticateUser
- The SDK broadcasts the
OpenFingerprintEvent
event to indicate that the fingerprint authentication flow has started. -
In order to start the fingerprint authentication on the device you need to call the fingerprint's acceptAuthenticationRequest function
-
In case the fingerprint is incorrect and there are attempts remaining the
NextFingerprintAuthenticationAttempt
will be thrown -
In case the user wants to cancel the Fingerprint authentication, the user can call the Fingerprint's denyAuthenticationRequest function
- In case the user decides to resign from fingerprint and wants to continue with pin authentication, the user can call the fallbackToPin function.
-
-
If the supplied fingerprint was correct the
CloseFingerprintEvent
event will be thrown and the authenticateUser function will resolve with an OWRegistrationResponse