Skip to main content
Version: 3.4.x.x RR

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.

note

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:

Authentication Cloud Registration

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:

Registration

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 to get an OutOfBandPayload 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.

  1. Provide the OutOfBandPayload to an OutOfBandOperation java, swift, objc, flutter 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.
  3. Provide an authenticator selector, a PinEnroller if a PIN can be registered in your application, and the user verifiers to the OutOfBandRegistration.
  4. Invoke OutOfBandRegistration.execute to continue with the operation.
Out-of-Band Registration

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:
  1. 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.onErrorjava, swift, objc, flutter, with the error, If the operation completes with an error.
note

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.

  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 to build the operation. The application provides the AuthenticatorSelector to the operation being built.
  3. The SDK calls the AuthenticatorSelector.selectAuthenticatorjava, swift, objc, flutter method. The AuthenticatorSelectionContext java, swift, objc, flutter 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 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 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.

  1. The SDK calls the PinEnroller.enrollPin java, swift, objc, flutter 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 method.
  5. The SDK validates whether the provided PIN is compliant with the PinPolicy java, swift, objc, flutter.
  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 contains a recoverable error.
  7. On Android and Flutter, if the provided credentials are valid, the PinEnroller.onValidCredentialsProvided java, flutter 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 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 method.
  2. On Android and Flutter, the application invokes BiometricUserVerificationHandler.listenForOsCredentials java, flutter 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 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.

  1. The SDK calls the DevicePasscodeUserVerifier.verifyDevicePasscode java, swift, objc, flutter method.
  2. On Android and Flutter, the application invokes DevicePasscodeUserVerificationHandler.listenForOsCredentials java, flutter 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 and Flutter, if the provided credentials are valid, the DevicePasscodeUserVerifier.onValidCredentialsProvided java, flutter method is invoked.

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 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 method.
  2. The application invokes FingerprintUserVerificationHandler.listenForOsCredentials java, flutter 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 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 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.

Last updated on