Your suggested change has been received. Thank you.

close
Thales Logo

All

  • All
back

User authentication

User authentication with system biometric authenticators

search
printsuggest an edit

User authentication with system biometric authenticators

copy link to clipboardIntroduction

The OneWelcome React Native SDK 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 React Native SDK will revoke system biometric authenticator and will perform a fallback to PIN authentication.

copy link to clipboardRequirements

copy link to clipboardFaceID

iOS needs to have configured message displayed on FaceID alert. It's configurable by adding NSFaceIDUsageDescription in your Info.plist file.

Example configuration

<key>NSFaceIDUsageDescription<_key>
<string>FaceID is used as a authenticator to login to application.<_string>

Not specifying this property in your configuration will crash your application when you will try to use Face ID authentication.

copy link to clipboardDifferences 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.

copy link to clipboardEnabling system biometric authenticator authentication

In order to enable fingerprint authenticator authentication for a user, the OneWelcome React Native SDK provides the registerAuthenticator to which you need to pass authenticatorId. This function requires the user to authenticate with PIN.

Example code for registering the system biometric authenticator:

OneWelcomeSdk
    .registerAuthenticator(authenticatorId)
    .then(() => {
        console.error("Register authenticator succeed!");
    })
    .catch(error => {
        console.error("Register authenticator failed: " + error);
    });

You have to also listen for PIN events in case of fallback.

Fingerprint authentication may not be available on every device. In this case, or if the authenticator has already been registered, the above method will reject with an error.

To request a list of available authenticators, the plugin exposes the getAllAuthenticators function. If the device does not meet the fingerprint requirements, the fingerprint authenticator will not be present in the returned array of authenticators.

Note that registering a new authenticator does not set it as the preferred authenticator for the user, which is PIN by default. To change the preffered authenticator setPreferredAuthenticator can be used.

Example code to set fingerprint as the preferred authenticator:

OneWelcomeSdk.setPreferredAuthenticator(authenticatorId)
  .then(()) => {
    console.log('setPreferredAuthenticator succeed!')
  })
  .catch(error => {
    console.log('setPreferredAuthenticator failed!: ', error.message)
  })

copy link to clipboardAuthenticate with fingerprint

There are two ways to start a fingerprint authentication flow.

  1. You register fingerprint as the preferred authenticator using setPreferredAuthenticator and call authenticateUser with null as the second argument.
  2. You get the authenticatorId for fingerprint authentication and pass that into the second argument of authenticateUser

copy link to clipboardAndroid

For authentication with fingerprint, similar to pin, you will need to handle the FingerprintNotificationEvent see addEventListener for more details. You can listen for this event and handle it as follows.

const handleNotification = useCallback(
  (event: Events.FingerprintNotificationEvent) => {
    console.log('handle FINGERPRINT notification event: ', event);
    switch (event.action) {
      case Events.Fingerprint.StartAuthentication:
        onStart();
        break;
      case Events.Fingerprint.OnNextAuthenticationAttempt:
        onNextAuthAttempt();
        break;
      case Events.Fingerprint.OnFingerprintCaptured:
        onCaptured();
        break;
      case Events.Fingerprint.FinishAuthentication:
        onFinish();
        break;
    }
  },
  [onStart, onNextAuthAttempt, onCaptured, onFinish],
);

const listener = OnewelcomeSdk.addEventListener(
  Events.SdkNotification.Fingerprint,
  handleNotification,
);

The SDK fires four events actions which notify you about the status of the fingerprint authentication.

Fingerprint Event Description
StartAuthentication Fired when a new fingerprint authentication request is made, providing an UserProfile object containing the profileId
OnNextAuthenticationAttempt Fired when user provided incorrect fingerprint but still haven't reach the failed attempts limit,
OnFingerprintCaptured Fired when user scanned his fingerprint and the fingerprint validation is performed. That's a good moment to show an update on the UI informing user about received attempt.
FinishAuthentication Fired when fingerprint scanning finished either with success or an error.

There are 3 methods to communicate the fingerprint flow to the SDK after fingerprint authentication has started.

SDK method Description
OnewelcomeSdk.submitFingerprintAcceptAuthenticationRequest() Should be called when user accepts fingerprint authentication request.
OnewelcomeSdk.submitFingerprintDenyAuthenticationRequest() Should be called when user denies the fingerprint authentication request.
OnewelcomeSdk.submitFingerprintFallbackToPin() Should be called when user decides to resign from fingerprint authentication and wants to enter his PIN to finish authentication.

In order to start the fingerprint authentication you need to call submitFingerprintAcceptAuthenticationRequest(). This can be done when you receive the startAuthentication event action.

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 React Native SDK. At this point, a fallback to PIN is performed, and the user is requested to enter PIN.

copy link to clipboardiOS

When starting biometric authentication on iOS the user will be prompted to authenticate with TouchId or FaceId with a native prompt from the OS. Due to differences between how biometric authentication works on Android and iOS we do not need any event listeners for iOS, the flow is handled by the promise from authenticateUser resolving. The user can press the cancel button on the native biometric prompt which will perform a fallback to PIN.

On this page