Package ch.nevis.mobile.sdk.api.operation.outofband

Interface OutOfBandRegistration

All Superinterfaces:
HttpOperation<OutOfBandRegistration>, Operation
public interface OutOfBandRegistration extends HttpOperation<OutOfBandRegistration>
The operation handling an out-of-band registration. This is the object returned by the SDK, when a OutOfBandPayload was processed and the OutOfBandPayload corresponds to a registration operation.

Example: 

 private void registerWithOutOfBand(Operations operations, OutOfBandPayload payload,
     DeviceInformation deviceInformation) {
     operations.outOfBandOperation()
         .payload(payload)
         .onRegistration(registration ->
             registration.deviceInformation(deviceInformation)
                 .authenticatorSelector((ctx, consumer) -> {
                     // select authenticator
                 })
                 .pinEnroller((ctx, consumer) -> {
                     // handle PIN enrollment
                 })
             .fingerprintUserVerifier(fingerprintUserVerifier)
             .biometricUserVerifier(biometricUserVerifier)
                 .onError(error -> {
                     // handle error
                 })
                 .onSuccess(() -> {
                     // handle success
                 })
                 .execute())
             .onAuthentication(authentication -> {
                 // handle authentication
             })
             .onError(error -> {
                 // handle error
             })
             .execute();
 }

The fingerprint, biometric and device passcode authenticators are enrolled at the OS level. That is why, if one of them must be registered, the user must authenticate through either the provided FingerprintUserVerifier, BiometricUserVerifier or DevicePasscodeUserVerifier. In the case of the PIN and password, the credentials is enrolled during registration, so no authentication is needed.

See Also:

  • Method Details

    • deviceInformation

      OutOfBandRegistration deviceInformation(DeviceInformation deviceInformation)
      Specifies the device information to be used. The DeviceInformation is required only if there is not a DeviceInformation already defined (that is, if this is the first registration). If a DeviceInformation was already provided in an existing registration, the provided value will be ignored.
      Parameters:
      deviceInformation - the device information
      Returns:
      an OutOfBandRegistration

    • allowClass2Sensors

      OutOfBandRegistration allowClass2Sensors(boolean allowClass2Sensors)
      Specifies whether Class 2 (formerly weak) biometric sensors are allowed if the biometric authenticator is selected. By default, the SDK will only allow to use Class 3 (formerly strong) sensors. Using Class 2 sensors is less secure and discouraged. When a Class 2 sensor is used, the FIDO UAF keys are not protected by the operating system by requiring user authentication, nor they can be invalidated when biometrics change (see invalidateOnNewOsBiometrics(boolean)).

      If the SDK detects that only Class 3 (strong) biometric sensors are available in the mobile device, even if Class 2 sensors are allowed, the FIDO UAF credentials will be protected by the operating system by requiring user authentication.

      However, in some cases it may be acceptable for the sake of end-user convenience. Allowing Class 2 sensors will enable for instance the use of face recognition in some Samsung devices.

      Parameters:
      allowClass2Sensors - whether using Class 2 biometric sensors is allowed if the biometric authenticator is selected
      Returns:
      an OutOfBandRegistration
      See Also:

    • allowDevicePasscodeAsFallback

      OutOfBandRegistration allowDevicePasscodeAsFallback(boolean allowDevicePasscodeAsFallback)
      Specifies whether the OS device passcode (PIN, password, gesture) can be used as fallback during biometric authentication. If not specified, the device passcode cannot be used as fallback.

      This setting will be ignored on devices running Android API 29 or lower.

      This setting and invalidateOnNewOsBiometrics(boolean) cannot be enabled together.

      Parameters:
      allowDevicePasscodeAsFallback - whether the device passcode can be used as fallback when using the biometric authenticator, or not
      Returns:
      an OutOfBandRegistration

    • invalidateOnNewOsBiometrics

      OutOfBandRegistration invalidateOnNewOsBiometrics(boolean invalidateOnNewOsBiometrics)
      Specifies whether the authenticator must be invalidated if the user adds new biometric credentials in the OS settings. If the authenticator has been invalidated, and you try to authenticate with it, an error with code FidoErrorCode.KEY_DISAPPEARED_PERMANENTLY will be returned by the authentication operation.

      This setting only applies to biometric (Authenticator.BIOMETRIC_AUTHENTICATOR_AAID) and fingerprint (Authenticator.FINGERPRINT_AUTHENTICATOR_AAID) authenticators.

      By setting this parameter to true, you increase the security but there is a loss of convenience: adding a new OS biometric credential does not imply necessarily that there is a security risk, but if the end-user does it, a new registration will be required, because an invalidated authenticator cannot be recovered.

      If not specified, the authenticator will be invalidated when the user adds a new biometric credential in the OS settings.

      Note that if the device supports Class 2 sensors, and if class 2 sensors are allowed (see allowClass2Sensors(boolean)), the value set in this method will be ignored and the authenticator will not be invalidated if the user adds new biometric credentials in the OS settings.

      There are some known issues associate with this feature when using some Google Pixel devices. See here

      for details.

      This setting will be ignored on devices running Android API 23.

      This setting and allowDevicePasscodeAsFallback(boolean) cannot be enabled together.

      Parameters:
      invalidateOnNewOsBiometrics - whether an addition of biometric credentials in the OS should invalidate this authenticator (if the authenticator is biometric or fingerprint)
      Returns:
      an OutOfBandRegistration

    • authenticatorSelector

      OutOfBandRegistration authenticatorSelector(AuthenticatorSelector selector)
      Specifies the object that will take care of the selection of the authenticator to be used.

      Providing the authenticator selector is required.

      Parameters:
      selector - the AuthenticatorSelector
      Returns:
      an OutOfBandRegistration

    • pinEnroller

      OutOfBandRegistration pinEnroller(PinEnroller pinEnroller)
      Specifies the object that will take care of enrolling the PIN of the authenticator. It must be provided only if a PIN authenticator must be registered.

      Providing at least one of the BiometricUserVerifier, PinEnroller, DevicePasscodeUserVerifier, PasswordEnroller or FingerprintUserVerifier is required.

      Parameters:
      pinEnroller - the PinEnroller
      Returns:
      an OutOfBandRegistration

    • passwordEnroller

      OutOfBandRegistration passwordEnroller(PasswordEnroller passwordEnroller)
      Specifies the object that will take care of enrolling the password of the authenticator. It must be provided only if a password authenticator must be registered.

      Providing at least one of the BiometricUserVerifier, PinEnroller, DevicePasscodeUserVerifier, PasswordEnroller or FingerprintUserVerifier is required.

      Parameters:
      passwordEnroller - the PasswordEnroller
      Returns:
      an OutOfBandRegistration

    • fingerprintUserVerifier

      OutOfBandRegistration fingerprintUserVerifier(FingerprintUserVerifier userVerifier)
      Specifies the object that will take care of the fingerprint user verification. It must be provided only if a fingerprint authenticator must be registered.

      Providing at least one of the BiometricUserVerifier, PinEnroller, DevicePasscodeUserVerifier, PasswordEnroller or FingerprintUserVerifier is required.

      Parameters:
      userVerifier - the FingerprintUserVerifier
      Returns:
      an OutOfBandRegistration

    • biometricUserVerifier

      OutOfBandRegistration biometricUserVerifier(BiometricUserVerifier userVerifier)
      Specifies the object that will take care of the biometric user verification. It must be provided only if a biometric authenticator must be registered.

      Providing at least one of the BiometricUserVerifier, PinEnroller, DevicePasscodeUserVerifier, PasswordEnroller or FingerprintUserVerifier is required.

      Parameters:
      userVerifier - the BiometricUserVerifier
      Returns:
      an OutOfBandRegistration

    • devicePasscodeUserVerifier

      OutOfBandRegistration devicePasscodeUserVerifier(DevicePasscodeUserVerifier userVerifier)
      Specifies the object that will take care of the device passcode user verification. It must be provided only if a device passcode authenticator must be registered.

      Providing at least one of the BiometricUserVerifier, PinEnroller, DevicePasscodeUserVerifier, PasswordEnroller or FingerprintUserVerifier is required.

      Parameters:
      userVerifier - the DevicePasscodeUserVerifier
      Returns:
      a OutOfBandRegistration

    • onSuccess

      OutOfBandRegistration onSuccess(Runnable onSuccess)
      Specifies the object that will be invoked if the registration completed successfully. This object will be invoked in the main/UI thread.

      Providing the object handling the success is required.

      Parameters:
      onSuccess - the object invoked on successful registration.
      Returns:
      an OutOfBandRegistration

    • onError

      OutOfBandRegistration onError(Consumer<OperationError> errorConsumer)
      Specifies the object that will be invoked if the registration failed. The specified object will receive an OperationError. This object will be invoked in the main/UI thread.

      Providing the object handling the error is required.

      Parameters:
      errorConsumer - the consumer of an OperationError
      Returns:
      an OutOfBandRegistration

    • execute

      void execute()
      Executes the out-of-band registration. Note that in the case of out-of-band registration, this method can only be invoked once. When invoked more than once, an IllegalStateException will be thrown.
      Specified by:
      execute in interface Operation