Registration
Before being able to authenticate using the Nevis Mobile Authentication SDK, go through the registration process. In the registration operation, FIDO UAF credentials are created on both mobile and server side. The credentials are used during authentication to validate that the user provided valid authentication.
The PIN authenticator is fully managed by the SDK: its contents are defined through the SDK during registration.
The device passcode authenticator uses the passcode to lock the device (PIN, password, gesture) which is defined in the operating system settings. The SDK does not manage this passcode.
The biometric authenticators are managed by the operating system, thus to successfully register them, the end-user must previously define biometric credentials (fingerprint, face, iris) in the operating system settings.
Depending on the use case, there are two types of registration: in-app registration and out-of-band registration. For more information, see Registration.
Secure Defaults
If you want to provide highest security with drawbacks regarding usability for end-users, use the following settings during registration:
- Do not allow class 2 sensors by setting
allowClass2Sensors(false)
(Android only) java, flutter - Do not allow to use the device passcode as fallback during biometric authentication by setting
allowDevicePasscodeAsFallback(false)
java, swift, objc ,flutter - Invalidate biometric authenticators when OS biometrics are changed by setting
invalidateOnNewOsBiometrics(true)
java, swift, objc, flutter
In-app registration
If the application triggers the registration, we are in the context of in-app registration.
Authentication Cloud
If your application is using a backend relying on the Authentication Cloud, your application has to obtain an enroll
response or an appLinkUri
to start the registration. You can get the enroll response by your backend invoking the Authentication Cloud API enroll. If the request is successful, the JSON response looks something like this:
{
"userId": "7e16ba00-92e2-4fcb-b30e-1af8fdc843aa",
"username": "u12345",
"status": "new",
"createdAt": "2020-10-09T12:13:11.845958Z",
"updatedAt": "2020-10-09T12:13:11.845958Z",
"authenticators": [],
"enrollment": {
"transactionId": "67cae36e-e3d5-4d67-9aa6-ab7ae3050576",
"statusToken": "eyJhbGciO...PxOZZYow",
"qrCode": {
"type": "image/png",
"size": 300,
"dataUri": "data:image/png;base64,iVBO...YII"
},
"appLinkUri": "https://{instance}.mauth.nevis.cloud/open?dispatchTokenResponse=eyJub...IxIn0"
}
}
Provide the returned JSON response or the value of the appLinkUri
attribute to an
AuthCloudApiRegistration
java, swift, objc, flutter, and trigger an in-app registration.
Provide an authenticator selector, which returns the authenticator to be registered.
Depending on the authenticators available to register, provide any of the following:
- Android/Kotlin
- Android/Java
- iOS/Swift
- iOS/Objective-C
- Flutter/Dart
Identity Suite
When the backend used by your application does not use the Nevis Authentication Cloud, provide the name of the user to be registered to Registration
java, swift, objc, flutter, and trigger an in-app registration.
If authorization is required by your backend to register, provide an AuthorizationProvider
java, swift, objc, flutter.
Provide an authenticator selector, which returns the authenticator to be registered.
Depending on the authenticators available to register, provide any of the following:
- Android/Kotlin
- Android/Java
- iOS/Swift
- iOS/Objective-C
- Flutter/Dart
Out-of-band registration
When the registration is initiated in another device or application, the information required to process the operation is transmitted through a QR code or a link. An example of out-of-band registration is the case where the user provides credentials in a laptop to obtain a registration QR code, and then the user scans the QR code in your application.
The out-of-band registration is done in three phases:
- The payload obtained from the QR code or the link is provided to an
OutOfBandPayloadDecode
java, swift, objc, flutter to get anOutOfBandPayload
java, swift, objc, flutter object. The payload to be provided is of the following type:
{
"nma_data": {
"token": "b4b07559-f934-4597-a1c5-44d89f691e8f",
"redeem_url": "https://fido.siven.ch/nevisfido/token/redeem/registration"
},
"nma_data_content_type": "application/json",
"nma_data_version": "1"
}
For more information on how to get OutOfBandPayload
, see Decode out-of-band payload.
- Provide the
OutOfBandPayload
to anOutOfBandOperation
java, swift, objc, flutter object. When building theOutOfBandOperation
, invoke theOutOfBandOperation.onRegistration
method with an object taking anOutOfBandRegistration
. - Invoke
OutOfBandOperation.execute
. If the provided payload is successfully redeemed in the server, and it corresponds to a registration, the object provided inOutOfBandOperation.onRegistration
is invoked with anOutOfBandRegistration
java, swift, objc, flutter. - Provide an authenticator selector, a
PinEnroller
if a PIN can be registered in your application, and the user verifiers to theOutOfBandRegistration
. - Invoke
OutOfBandRegistration.execute
to continue with the operation.
- Android/Kotlin
- Android/Java
- iOS/Swift
- iOS/Objective-C
- Flutter/Dart
Lifecycle
- When the
execute
method is invoked, the registration is started. - The SDK invokes the Authenticator Selector.
- Depending on the selected authenticator, the SDK does the following:
- Invoke the PIN enroller, if PIN is selected.
- Invoke the biometric user verifier, if a biometric authenticator (biometric authenticator in Android, FaceID or TouchID authenticator in iOS) is selected.
- Invoke the device passcode user verifier, if the device passcode authenticator is selected.
- Invoke the fingerprint user verifier, only applicable when running on an Android device, if the fingerprint authenticator is selected.
- When the operation completes, the SDK does the following:
- Invoke the object provided to
OutOfBandRegistration.onSuccess
java, swift, objc, flutter, if the operation completes successfully. - Invoke the object provided to
OutOfBandRegistration.onError
java, swift, objc, flutter, with the error, If the operation completes with an error.
The PIN authenticator is fully managed by the SDK: its contents are defined and modified through the SDK.
However, the other authenticators are enrolled by the operating system, thus the user has to authenticate at the end of the registration for these authenticators.
Authenticator Selector
The Nevis Mobile Authentication SDK needs to know which is the authenticator used for the operation. The developer has to provide an AuthenticatorSelector
java, swift, objc, flutter when building the operation.
Select an authenticator
The AuthenticatorSelector
is called by the SDK to select an authenticator used for the operation. It is the responsibility of the application to decide whether to ask the user to perform the selection, or to do it directly without user intervention.
- The user initiates an action that requires to select an authenticator, like registration or authentication.
- The application invokes
Operations
java, swift, objc, flutter to build the operation. The application provides theAuthenticatorSelector
to the operation being built. - The SDK calls the
AuthenticatorSelector.selectAuthenticator
java, swift, objc, flutter method. TheAuthenticatorSelectionContext
java, swift, objc, flutter contains a list of authenticator objects, including AAIDs, which uniquely identify each authenticator. - The application shows the list of available authenticators to the user.
The SDK can now continue the operation started by using the selected authenticator.
PIN Enroller
When a PIN authenticator is to be registered, a PIN is to be defined. The developer has to provide a PinEnroller
java, swift, objc, flutter when building the registration operation. The PinEnroller
is in charge of providing the PIN to the SDK. The PinEnroller
asks the user for the PIN and provides it to the SDK, which validates it against the PIN policy.
The PinEnroller
can also define which is the PIN policy to be used through PinPolicyProvider
java, swift, objc, flutter interface.
Enroll PIN
The PinEnroller
is called by the SDK to obtain the value of the PIN to be registered.
- The SDK calls the
PinEnroller.enrollPin
java, swift, objc, flutter method. - The application asks the user to provide a PIN. For example, the application displays a textbox where the user provides a PIN, and another textbox to confirm it.
- The user provides the PIN.
- The application provides the PIN invoking the
PinEnrollmentHandler.pin
java, swift, objc, flutter method. - The SDK validates whether the provided PIN is compliant with the
PinPolicy
java, swift, objc, flutter. - If the provided PIN is not compliant with the PIN policy, the SDK invokes
PinEnroller.enrollPin
again, and thePinEnrollmentContext
java, swift, objc, flutter contains a recoverable error. - On Android and Flutter, if the provided credentials are valid, the
PinEnroller.onValidCredentialsProvided
java, flutter method is invoked.
Biometric User Verifier
The biometric authenticator is specific to Android devices. For iOS please refer to the FaceID or TouchID authenticator.
When authentication using the biometric authenticator is required, the developer has to provide a BiometricUserVerifier
java, swift, objc, flutter when building the operation. The BiometricUserVerifier
does not need to implement the user interface asking for biometric credentials, as this is handled by the SDK.
Biometric user verification
The BiometricUserVerifier
is called by the SDK to ask the user to provide fingerprint credentials.
- The SDK calls the
BiometricUserVerifier.verifyBiometric
java, swift, objc, flutter method. - On Android and Flutter, the application invokes
BiometricUserVerificationHandler.listenForOsCredentials
java, flutter so that the SDK starts listening for biometric credentials. - On iOS, the application invokes the
BiometricUserVerificationHandler.verify
swift, objc method. - The SDK displays a user interface asking the user to provide credentials.
- The user provides biometric credentials.
- The operating system validates the provided credentials.
- If the provided biometric credentials are not valid, the operating system displays an error to inform the user. If supported by the OS version and enabled during registration, it also proposes the user to provide device credentials as fallback: PIN, gestures, or password.
- If the provided biometric information is not valid, and too many failed attempts occurred, then the operation fails, and the object managing the error provided in the
onError
method when building the operation is invoked. - On Android and Flutter, if the provided credentials are valid, the
BiometricUserVerifier.onValidCredentialsProvided
java, flutter method is invoked.
Device Passcode User Verifier
When authentication using the device passcode authenticator is required, the developer has to provide a DevicePasscodeUserVerifier
java, swift, objc, flutter when building the operation. The DevicePasscodeUserVerifier
does not need to implement the user interface asking for device passcode credentials, as this is handled by the SDK.
Device passcode user verification
The DevicePasscodeUserVerifier
is called by the SDK to ask the user to provide device passcode credentials.
- The SDK calls the
DevicePasscodeUserVerifier.verifyDevicePasscode
java, swift, objc, flutter method. - On Android and Flutter, the application invokes
DevicePasscodeUserVerificationHandler.listenForOsCredentials
java, flutter so that the SDK starts listening for device passcode credentials. - On iOS, the application invokes the
DevicePasscodeUserVerificationHandler.verify
swift, objc method. - The SDK invokes the operating system to display a user interface asking the user to provide credentials.
- The user provides device passcode credentials.
- The operating system validates the provided credentials.
- If the provided device passcode credentials are not valid, the operating system displays an error to inform the user.
- If the provided device passcode information is not valid, and too many failed attempts occurred, then the operation fails, and the object managing the error provided in the
onError
method when building the operation is invoked. - On Android and Flutter, if the provided credentials are valid, the
DevicePasscodeUserVerifier.onValidCredentialsProvided
java, flutter method is invoked.
Fingerprint User Verifier
The fingerprint authenticator is supported only on Android devices. The SDK supports the fingerprint authenticator to handle older Android OS versions that do not support the biometric authentication. If the biometric authenticator is supported by the operating system, we recommend to use that authenticator, and not to allow class 2 sensors for maximum security. This means that only the fingerprint will be available as an authentication method of the biometric authenticator.
When authentication with fingerprint is required, the developer has to provide a FingerprintUserVerifier
java, flutter when building the operation. The FingerprintUserVerifier
is in charge of displaying a user interface asking the user to provide fingerprints, and to display the recoverable errors during authentication. For example, if the user moved the finger too quickly.
Fingerprint user verification
The FingerprintUserVerifier
is called by the SDK to ask the user to provide fingerprint credentials.
- The SDK calls the
FingerprintUserVerifier.verifyFingerprint
java, flutter method. - The application invokes
FingerprintUserVerificationHandler.listenForOsCredentials
java, flutter so that the SDK starts listening for fingerprint credentials. The SDK does not automatically display relevant UI. - The application asks the user to provide fingerprint credentials, for example, by displaying a screen with an image of a fingerprint.
- The user provides fingerprint credentials.
- The SDK validates that the provided fingerprints are valid.
- If the provided fingerprints are not valid, the SDK invokes
FingerprintUserVerifier.verifyFingerprint
again, and theFingerprintUserVerificationContext
java, flutter contains a recoverable error. - If the provided fingerprints are not valid, and too many failed attempts occurred, then the operation fails and the object managing the error that was provided in the
onError
method when building the operation is invoked. - If the provided credentials are valid, the
FingerprintUserVerifier.onValidCredentialsProvided
java, flutter method is invoked.
Device Information
For all registration operations, you can provide a DeviceInformation
java, swift, objc, flutter using the deviceInformation
method of each registration object.
The DeviceInformation
contains the name identifying your device and optionally the Firebase Cloud Messaging registration token Android, iOS, Flutter used by the backend to send authentication push notifications to your application. The DeviceInformation
is required only if you require support for encrypted QR codes or push notifications.
There is a single DeviceInformation
for all accounts. It is created when the first successful registration is completed, and it is deleted when the latest authenticator is removed (using the Deregistration or Remove Local Data). When a DeviceInformation
is provided in a registration operation, and a DeviceInformation
is already defined (that is, there is already a registered authenticator), the provided DeviceInformation
is ignored. The device information contents (name and FCM registration token) can be changed using change device information.