Registration
Before being able to authenticate using the Nevis Mobile Authentication SDK, go through the registration process. In the registration operation, FIDO UAF credentials aree created on both mobile and server side. The credentials are used during authentication to validate that the user provided valid authentication.
To do a registration operation, configure and
initialize the SDK to obtain a
MobileAuthenticationClient
java, swift, flutter.
Depending on the use case, there are two types of registration: in-app registration and out-of-band registration. For more information, see Registration.
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, 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
- 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, flutter, and trigger an in-app registration.
If authorization is required by your backend to register, provide an AuthorizationProvider
java, swift, flutter.
Provide an authenticator selector, which returns the authenticator to be registered.
Depending on the authenticators availale to register, provide any of the following:
- Android/Kotlin
- Android/Java
- iOS/Swift
- 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, flutter to get anOutOfBandPayload
java, swift, 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 mor information on how to get OutOfBandPayload
, see Out-of-Band Payload Decode.
- Provide the
OutOfBandPayload
to anOutOfBandOperation
java, swift 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, 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
- 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, only applicable when running on an Android device, if the biometric 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
Registration.onSuccess
java, swift, flutter, if the operation completes successfully. - Invoke the object provided to
Registration.onError
java, swift, 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, 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, flutter to build the operation. The application provides theAuthenticatorSelector
to the operation being built. - The SDK calls the
AuthenticatorSelector.selectAuthenticator
java, swift, flutter method. TheAuthenticatorSelectionContext
java, swift, 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, 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
interface java, swift, flutter.
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, 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, flutter method. - The SDK validates whether the provided PIN is compliant with the
PinPolicy
java, swift, flutter. - If the provided PIN is not compliant with the PIN policy, the SDK invokes
PinEnroller.enrollPin
again, and thePinEnrollmentContext
java, swift, 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.
When authentication using the biometric authenticator is required, the developer has to provide a BiometricUserVerifier
java, swift, 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, flutter method. - The application invokes
BiometricUserVerificationHandler.listenForOsCredentials
java so that the SDK starts listening for biometric credentials. - The SDK displays a user interface asking the user to provide credentials.
- The user provides biometric credentials.
- The SDK validates that the provided credentials are valid.
- If the provided biometric credentials are not valid, the SDK displays an error informing the user that the provided credentials are not valid. If supported by the OS version, 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.
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 the fingerprint 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.