User authentication

The Flutter Plugin allows for user authentication with either a registered authenticator or with a PIN. Both cases are based on the same method, however a different value for registeredAuthenticatorId is required.

Retrieving registered users

The Flutter Plugin provides a function getUserProfiles to get all registered profiles on the device. You will need to use these to authenticate a profile with the Mobile SDK. By passing one of the profile id's you can authenticate a specific user.

You can authenticate with a PIN or with biometrics. To check if a biometric authenticator is registered for a specific user, use the getBiometricAuthenticator method. Similarly you can get the preferredAuthenticator with getPreferredAuthenticator.

Authenticate user

After a user has been registered, it can be logged in using the authenticateUser or authenticateUserImplicitly method in the case of implicit authentication. The authenticateUser method takes a OWAuthenticatorType and uses it to authenticate the user. The authenticatorType param can also be null, in which case the preferred authenticator (default PIN) will be used. If biometric is passed in while the authenticator is not registered it will use PIN.

var registrationResponse = await Onegini.instance.userClient
    .authenticateUser(profileId, authenticatorType)
    .catchError((error) {
        print("Authentication failed: " + error.message);
    });

if (registrationResponse != null) {
    print("Authentication success!");
}

The result of successful authentication is an OWRegistrationResponse.

Authenticate using PIN flow

In case the user needs to authenticate using a PIN as a result of the selected authenticatorId or the default authenticator, the PIN authentication flow will be started. This flow uses the following events:

This flow contains the following steps:

1. The user starts a PIN authentication flow by calling authenticateUser.
2. The Mobile SDK broadcasts the OpenPinAuthenticationEvent event to indicate that the PIN authentication flow has started.
3. The user needs to respond to the Mobile SDK using the user's supplied PIN by calling the PIN's acceptAuthenticationRequest function.
   1. If the given PIN was incorrect a new event, NextAuthenticationAttemptEvent, will be broadcasted.
   2. If the PIN was correct, the ClosePinAuthenticationEvent event will be broadcasted and the original authenticateUser function will resolve with an OWRegistrationResponse object.

Authenticate using biometrics

The Flutter Plugin allows you to authenticate users with the system biometric authenticators. These authenticators are provided by the device's operating system (iOS with Touch ID and Face ID, Android with 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 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.

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

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

To enable fingerprint authenticator authentication for a user, the 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.

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.

Example code for registering the system biometric authenticator:

Onegini.instance.userClient
    .registerBiometricAuthenticator()
    .catchError((error) {
        print("Register authenticator failed: " + error.message);
    });

Authenticating using fingerprint

When 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

await Onegini.instance.userClient
    .authenticateUser(profileId, OWAuthenticatorType.biometric)
    .catchError((error) {
        print("Authentication failed: " + error.message);
    });

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 Flutter Plugin. At this point, a fallback to PIN is performed, and the user is asked 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 the user scanned their fingerprint and the fingerprint validation is performed. That's a good moment to show an update on the UI informing the user about the received attempt. | |ReceivedFingerprintEvent |Fired when the user provided an incorrect fingerprint but still hasn't reach the failed attempts limit. |

Fingerprint authentication flow

This required flow contains the following steps:

1. Fingerprint authentication is started by calling authenticateUser.
2. The Mobile SDK broadcasts the OpenFingerprintEvent event to indicate that the fingerprint authentication flow has started.
3. In order to start the fingerprint authentication on the device you need to call the fingerprint's acceptAuthenticationRequest function.
   1. In case the fingerprint is incorrect and there are attempts remaining, the NextFingerprintAuthenticationAttempt will be thrown.
   2. In case the user wants to cancel the fingerprint authentication, the user can call the fingerprint's denyAuthenticationRequest function.
   3. In case the user decides to resign from fingerprint and wants to continue with PIN authentication, the user can call the fallbackToPin function.
4. If the supplied fingerprint was correct, the CloseFingerprintEvent event will be thrown and the authenticateUser function will resolve with an OWRegistrationResponse.