Skip to main content
Version: 4.5.x.x RR (Android, iOS) / 4.6.x.x RR (Flutter) / 5.x.x.x RR (React Native)

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.

tip

To do a registration operation, configure and initialize the SDK to obtain a MobileAuthenticationClient java, swift, objc, flutter, react native.

note

The PIN and password authenticators are fully managed by the SDK: their contents are defined through the SDK during registration.

  • The Nevis Mobile Authentication SDK allows registering only one authenticator of each type per user.
  • 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​

The SDK uses "secure default" to provide the highest security with drawbacks regarding usability for end-users. The following settings influence the biometric authenticators and are listed with the default values used.

  • The SDK does not allow Android class 2 sensors with allowClass2Sensors(false) (Android only) java, flutter, react native
  • The SDK does not allow to use the device passcode as fallback during biometric authentication with allowDevicePasscodeAsFallback(false) java, swift, objc, flutter, react native
  • The SDK invalidates biometric authenticators when OS biometrics are changed with invalidateOnNewOsBiometrics(true) java, swift, objc, flutter , react native
  • The SDK attempts to use StrongBox to store key material (Android only). If StrongBox is not available or key creation fails, the SDK falls back to TEE. Both options are hardware-backed; the private key never leaves the secure hardware. allowStrongBox(false) opts out of StrongBox and always uses TEE, which maximizes device compatibility. For details on the trade-offs and a decision guide, see StrongBox on Android.
info
  • The invalidateOnNewOsBiometrics and allowDevicePasscodeAsFallback flags are mutually exclusive on Android SDK 3.7.0 and above; setting both to true will throw a RuntimeException.
  • On iOS SDK 4.1.x and below, allowDevicePasscodeAsFallback overrides invalidateOnNewOsBiometrics if both are set to true. Starting with iOS SDK 4.2.0, the flags are mutually exclusive; setting both to true is not allowed.
  • When invalidateOnNewOsBiometrics is set to true, the SDK does not automatically remove invalidated authenticators - neither locally nor in the backend. When trying to access an invalidated authenticator, the SDK will throw an OperationError with error code FidoErrorCode.KEY_PERMANENTLY_DELETED.
  • invalidateOnNewOsBiometrics has platform-specific behaviour: On Android removing biometrics (Fingerprints) does not invalidate other existing credentials as opposed to iOS where removal also leads to invalidation.

Device Information​

note

The DeviceInformation object is always required during the first registration operation.

During the first registration operation, provide a DeviceInformation java, swift, objc, flutter, react native using the deviceInformation method of the registration object.

The DeviceInformation contains the name identifying your device and optionally the Firebase Cloud Messaging registration token Android, iOS, Flutter, React Native used by the backend to send authentication push notifications to your application.

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.

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, react native, 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:

Authentication Cloud Registration
loading...

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, react native, and trigger an in-app registration.

If authorization is required by your backend to register, provide an AuthorizationProvider java, swift, objc, flutter, react native.

Provide an authenticator selector, which returns the authenticator to be registered.

Depending on the authenticators available to register, provide any of the following:

Registration
loading...

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:

  1. The payload obtained from the QR code or the link is provided to an OutOfBandPayloadDecode java, swift, objc, flutter, react native to get an OutOfBandPayload java, swift, objc, flutter, react native 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 obtain the OutOfBandPayload, see Obtain an out-of-band payload.

  1. Provide the OutOfBandPayload to an OutOfBandOperation java, swift, objc, flutter, react native object. When building the OutOfBandOperation, invoke the OutOfBandOperation.onRegistration method with an object taking an OutOfBandRegistration.
  2. Invoke OutOfBandOperation.execute. If the provided payload is successfully redeemed in the server, and it corresponds to a registration, the object provided in OutOfBandOperation.onRegistration is invoked with an OutOfBandRegistration java, swift, objc, flutter, react native.
  3. Provide an authenticator selector, a PinEnroller if a PIN can be registered in your application, a PasswordEnroller if a password can be registered, and the user verifiers to the OutOfBandRegistration.
  4. Invoke OutOfBandRegistration.execute to continue with the operation.
Out-of-Band Registration
loading...

Lifecycle​

  1. When the execute method is invoked, the registration is started.
  2. The SDK invokes the Authenticator Selector.
  3. Depending on the selected authenticator, the SDK does the following:
  4. When the operation completes, the SDK does the following:
note

The PIN and password authenticators are fully managed by the SDK: their 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, react native when building the operation.

Performing authenticator "eligibility" checks

It is very important that the authenticator selector performs the necessary checks to determine whether an authenticator is "usable" or not, otherwise the operation will fail.

Checks that need to be done are:

  • Is the authenticator policy compliant java, swift, objc, flutter, react native
  • Is the authenticator supported by the mobile device hardware
  • Is the authenticator not registered (registration) or registered (authentication) for the given user

The JavaDoc contains example code of these checks.

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.

  1. The user initiates an action that requires to select an authenticator, like registration or authentication.
  2. The application invokes Operations java, swift, objc, flutter, react native to build the operation. The application provides the AuthenticatorSelector to the operation being built.
  3. The SDK calls the AuthenticatorSelector.selectAuthenticator java, swift, objc, flutter, react native method. The AuthenticatorSelectionContext java, swift, objc, flutter, react native contains a list of authenticator objects, including AAIDs, which uniquely identify each authenticator.
  4. The application shows the list of available authenticators to the user.
    1. The user selects an authenticator.
    2. The application provides the AAID of the authenticator invoking the AuthenticatorSelectionHandler.aaid java, swift, objc, flutter, react native method.

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, react native 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, react native interface.

Enroll PIN​

The PinEnroller is called by the SDK to obtain the value of the PIN to be registered.

  1. The SDK calls the PinEnroller.enrollPin java, swift, objc, flutter, react native method.
  2. 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.
  3. The user provides the PIN.
  4. The application provides the PIN invoking the PinEnrollmentHandler.pin java, swift, objc, flutter, react native method.
  5. The SDK validates whether the provided PIN is compliant with the PinPolicy java, swift, objc, flutter, react native.
  6. If the provided PIN is not compliant with the PIN policy, the SDK invokes PinEnroller.enrollPin again, and the PinEnrollmentContext java, swift, objc, flutter, react native contains a recoverable error.
  7. On Android, Flutter and React Native, if the provided credentials are valid, the PinEnroller.onValidCredentialsProvided java, flutter, react native method is invoked.

Password Enroller​

When a password authenticator is to be registered, a password is to be defined. The developer has to provide a PasswordEnroller java, swift, objc, flutter, react-native when building the registration operation. The PasswordEnroller is in charge of providing the password to the SDK. The PasswordEnroller asks the user for the password and provides it to the SDK, which validates it against the password policy.

The PasswordEnroller also defines the PasswordPolicy java, swift, objc, flutter, react-native to be used, see PasswordEnroller.passwordPolicy java, swift, objc, flutter, react-native. The PasswordPolicy is the object that determines whether the password is valid or not. For example the password policy can enforce that the password has at least 8 characters and contains at least one capital letter and two special characters.

Enroll password​

The PasswordEnroller is called by the SDK to obtain the value of the password to be registered.

  1. The SDK calls the PasswordEnroller.enrollPassword java, swift, objc, flutter, react-native method.
  2. The application asks the user to provide a password. For example, the application displays a textbox where the user provides a password, and another textbox to confirm it.
  3. The user provides the password.
  4. The application provides the password invoking the PasswordEnrollmentHandler.password java, swift, objc, flutter, react-native method.
  5. The SDK invokes the PasswordPolicy.validatePasswordForEnrollment java, swift, objc, flutter, react-native method to validate the provided password.
  6. The application (through the PasswordPolicy) informs the SDK of whether the password is valid or not.
  7. If the provided password is not compliant with the password policy, the SDK invokes PasswordEnroller.enrollPassword again, and the PasswordEnrollmentContext java, swift, objc, flutter, react-native contains the recoverable error provided by the PasswordPolicy.
  8. On Android, Flutter and React Native, if the provided credentials are valid, the PasswordEnroller.onValidCredentialsProvided java, flutter, react-native method is invoked.

Biometric User Verifier​

info

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, react native 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.

  1. The SDK calls the BiometricUserVerifier.verifyBiometric java, swift, objc, flutter, react native method.
  2. On Android, Flutter and React Native, the application invokes BiometricUserVerificationHandler.listenForOsCredentials java, flutter, react native so that the SDK starts listening for biometric credentials.
  3. On iOS, the application invokes the BiometricUserVerificationHandler.verify swift, objc method.
  4. The SDK displays a user interface asking the user to provide credentials.
  5. The user provides biometric credentials.
  6. The operating system validates the provided credentials.
  7. 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.
  8. 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.
  9. On Android, Flutter and React Native, if the provided credentials are valid, the BiometricUserVerifier.onValidCredentialsProvided java, flutter, react native method is invoked.

Biometric prompt customization​

The biometric prompt shown to users is customizable by providing a BiometricPromptOptions java, swift, objc, flutter, react native object when invoking the BiometricUserVerificationHandler.listenForOsCredentials java, flutter, react native or the BiometricUserVerificationHandler.verify swift, objc method. The BiometricPromptOptions allows you to set properties such as the prompt title, description, and the text for the cancel and fallback buttons. This enables you to tailor the user experience to your application's branding and requirements.

The available customization options for biometric prompt properties differ between native platforms. The table below summarizes which properties can be customized:

PropertyAndroidiOS
Title✅❌
Description / Reason✅✅
Cancel Button Title✅✅
Fallback Button Title❌✅
info

On Flutter and React Native, BiometricPromptOptions allows you to customize all prompt properties. However, the actual customization options and limitations depend on the underlying platform (Android or iOS), and only the properties supported by that platform will take effect.

Biometric Prompt Customization
loading...

To customize only the biometric prompt messages on iOS (including Flutter and React Native apps), add a string catalog or a Localizable.strings file to your iOS project if it does not exist. Then, define the following keys to control the prompt messages:

KeyDefault Value
face_recognition_authenticator_register_operation_prompt_messageUse Face ID to register for Mobile Authentication
fingerprint_authenticator_register_operation_prompt_messageProvide your fingerprint to register for Mobile Authentication
face_recognition_authenticator_authenticate_operation_prompt_messageAuthenticate using Face ID
fingerprint_authenticator_authenticate_operation_prompt_messageAuthenticate with your fingerprint
Default translations

The iOS SDK includes default translations for the above prompt messages in English only. You can override these messages by providing localized strings in your project, but only the message texts can be customized this way. To fully customize all prompt options (such as button texts), use the BiometricPromptOptions object.

Device Passcode User Verifier​

When authentication using the device passcode authenticator is required, the developer has to provide a DevicePasscodeUserVerifier java, swift, objc, flutter, react native 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.

  1. The SDK calls the DevicePasscodeUserVerifier.verifyDevicePasscode java, swift, objc, flutter, react native method.
  2. On Android, Flutter and React Native, the application invokes DevicePasscodeUserVerificationHandler.listenForOsCredentials java, flutter, react native so that the SDK starts listening for device passcode credentials.
  3. On iOS, the application invokes the DevicePasscodeUserVerificationHandler.verify swift, objc method.
  4. The SDK invokes the operating system to display a user interface asking the user to provide credentials.
  5. The user provides device passcode credentials.
  6. The operating system validates the provided credentials.
  7. If the provided device passcode credentials are not valid, the operating system displays an error to inform the user.
  8. 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.
  9. On Android, Flutter and React Native, if the provided credentials are valid, the DevicePasscodeUserVerifier.onValidCredentialsProvided java, flutter, react native method is invoked.

Device Passcode prompt customization​

The device passcode prompt shown to users is customizable by providing a DevicePasscodePromptOptions java, swift, objc, flutter, react native object when invoking the DevicePasscodeUserVerificationHandler.listenForOsCredentials java, flutter, react native or the DevicePasscodeUserVerificationHandler.verify swift, objc method. The DevicePasscodePromptOptions allows you to set the prompt title and the description. This enables you to tailor the user experience to your application's branding and requirements.

The available customization options for device passcode prompt properties differ between native platforms. The table below summarizes which properties can be customized:

PropertyAndroidiOS
Title✅❌
Description / Reason✅✅
info

On Flutter and React Native, DevicePasscodePromptOptions allows you to customize all prompt properties. However, the actual customization options and limitations depend on the underlying platform (Android or iOS), and only the properties supported by that platform will take effect.

Device Passcode Prompt Customization
loading...

To customize only the device passcode prompt message on iOS (including Flutter and React Native apps), add a string catalog or a Localizable.strings file to your iOS project if it does not exist. Then, define the following keys to control the prompt message:

KeyDefault value
device_passcode_authenticator_register_operation_prompt_messageAuthenticate with Device Passcode
device_passcode_authenticator_authenticate_operation_prompt_messageAuthenticate using device Passcode
Default translations

The iOS SDK includes default translations for the above prompt messages in English only. You can override these messages by providing localized strings in your project, but only the message texts can be customized this way. To fully customize all prompt options (such as button texts), use the DevicePasscodePromptOptions object.

Fingerprint User Verifier​

info

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, react native 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.

  1. The SDK calls the FingerprintUserVerifier.verifyFingerprint java, flutter, react native method.
  2. The application invokes FingerprintUserVerificationHandler.listenForOsCredentials java, flutter, react native so that the SDK starts listening for fingerprint credentials. The SDK does not automatically display relevant UI.
  3. The application asks the user to provide fingerprint credentials, for example, by displaying a screen with an image of a fingerprint.
  4. The user provides fingerprint credentials.
  5. The SDK validates that the provided fingerprints are valid.
  6. If the provided fingerprints are not valid, the SDK invokes FingerprintUserVerifier.verifyFingerprint again, and the FingerprintUserVerificationContext java, flutter, react native contains a recoverable error.
  7. 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.
  8. If the provided credentials are valid, the FingerprintUserVerifier.onValidCredentialsProvided java, flutter, react native method is invoked.

Fingerprint prompt customization​

In the cross-platform plugins the fingerprint prompt shown to users is customizable by providing a FingerprintPromptOptions flutter, react native object when invoking the FingerprintUserVerificationHandler.listenForOsCredentials flutter, react native method. The FingerprintPromptOptions allows you to set properties such as the prompt description and the text for the cancel and fallback buttons. This enables you to tailor the user experience to your application's branding and requirements.

info

FingerprintPromptOptions is available only in the cross-platform plugins and effects only on iOS platform. On Android, the SDK always uses the default system prompt for fingerprint authentication, and any customization provided by FingerprintPromptOptions is ignored.

Fingerprint Prompt Customization
loading...

Authorization providers​

Provide an AuthorizationProvider java, swift, objc, flutter, react native to the registration operation based on the backend / project requirements.

Several different AuthorizationProviders are available in the SDK, selecting the correct one depends on the backend as well as the integration scenario.

CookieAuthorizationProvider​

JwtAuthorizationProvider​

JwsAuthorizationProvider​

  • For Identity Suite (using nevisFIDO 7.2402.x or newer) and Authentication Cloud backends using JWT-based authentication.
  • Currently only the deregistration operation supports this AuthorizationProvider.
  • The JwsAuthorizationProvider java, swift, objc, flutter, react native uses the Device Service HTTP API.
  • This authorization provider can be used to deregister authenticators without asking the user to authenticate.
Nevis recommendation

Using the JWS Authorization Provider is the recommended way to perform the deregistration() operation as it does not require the end-user to authenticate.

EmptyAuthorizationProvider​

  • For Authentication Cloud and Identity Suite backends requiring no authorization.
  • Android only.
Last updated on