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.
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:
Event | Description |
---|---|
OpenPinAuthenticationEvent | Sent when the Mobile SDK is ready to receive a PIN for authentication. |
ClosePinAuthenticationEvent | Sent by the Mobile SDK when it has finished PIN authentication. |
NextPinAuthenticationAttemptEvent | Sent by the Mobile SDK when it has received an incorrect PIN. |
This flow contains the following steps:
- The user starts a PIN authentication flow by calling
authenticateUser
. - The Mobile SDK broadcasts the
OpenPinAuthenticationEvent
event to indicate that the PIN authentication flow has started. - The user needs to respond to the Mobile SDK using the user's supplied PIN by calling the PIN's
acceptAuthenticationRequest
function.- If the given PIN was incorrect a new event,
NextAuthenticationAttemptEvent
, will be broadcasted. - If the PIN was correct, the
ClosePinAuthenticationEvent
event will be broadcasted and the originalauthenticateUser
function will resolve with anOWRegistrationResponse
object.
- If the given PIN was incorrect a new event,
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.
Note
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 is specified where applicable.
Availability
A user can enable biometric authentication only if all the following requirements are met: - (Android) The device is not rooted and supports Class 3 Biometrics. - (iOS) The device is not jail-broken and has hardware support for TouchID or FaceID. - The user has already enrolled biometrics on the device. In other words, they registered at least one fingerprint or face. - The client configuration in the IDAAS-core allows using fingerprint authentication.
Requirements
FaceID: iOS needs to have configured message displayed on FaceID alert. It's configurable by adding NSFaceIDUsageDescription
in your Info.plist
file.
Caution
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
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:
Authenticating using fingerprint
When a biometric authenticator is available, registered and set as the preferred authenticator, the user will be prompted to authenticate with their biometric authenticator instead of PIN. The method to do so is the same as for PIN, Onegini.instance.userClient.authenticateUser(String profileId, OWAuthenticatorType? authenticatorType)
.
Example code to start the fingerprint authentication
(Android only) If fingerprint authentication is a possibility for the user, need to follow authentication flow as described below in biometric authentication flow
Biometric events
The resulting biometric authentication flow will use the following events:
Event | Description |
---|---|
StartBiometricAuthEvent | Fired when new biometric authentication request is made and to show biometric prompt |
FinishBiometricAuthEvent | Fired when biometric authentication finishes |
OneginiBiometricCallback
This is a callback for biometric authentication. To control the flow of biometric authentication you can use following methods:
- showBiometricPrompt(OWBiometricMessages messages) Call this method to show the biometric prompt with customized messages.
- fallbackToPin Call this method when a user decides to resign from biometric authentication and wants to enter their PIN to finish authentication.
- denyAuthenticationRequest Call this method when a user denies the biometric authentication request.
You should use the static instance of OneginiBiometricCallback
.
Example: OneginiBiometricCallback().fallbackToPin()
Biometric authentication flow
This required flow contains the following steps:
- Biometric authentication is started by calling
authenticateUser
. - Flutter SDK broadcasts
StartBiometricAuthEvent
event to indicate that the biometric authentication has started. -
In order to start biometric authentication on the device upon receiving the
StartBiometricAuthEvent
, users need to call biometric callback methodshowBiometricPrompt(OWBiometricMessages messages)
to show biometric prompt with customized messages.dart OneginiBiometricCallback().showBiometricPrompt(OWBiometricMessages( title: "Biometric Authentication", subTitle: "Authenticate user", negativeButtonText: "Use PIN"));
a. In case the user wants to cancel the biometric authentication, the user can call the biometric callback functionbiometricDenyAuthenticationRequest()
. This method closes the biometric prompt shown byshowBiometricPrompt
.b. In case the user wants to resign from biometric authentication and wants to continue with PIN authentication, the user can call the biometric callback method
biometricFallbackToPin()
. This method closes the biometric prompt shown byshowBiometricPrompt
. 4. If the supplied fingerprint is correct,FinishBiometricAuthEvent
event will be thrown andauthenticateUser
method with resolve withOWRegistrationResponse
.