Interface IBiometricAuthentication

All Known Implementing Classes:
BiometricAuthentication

public interface IBiometricAuthentication
The biometric authentication of a client session. A success is the client's own claim, a user-presence check on a device the server cannot inspect, where a modified app, a hooked runtime on a rooted or jailbroken phone or a simulator can answer "yes"; so it is a gate ON TOP of a server-verified factor, never a factor itself, and SignIn's strong-authentication policy must not count it as one.

What it is. iiziRun's Face ID, Touch ID, Optic ID or fingerprint check through cordova-plugin-fingerprint-aio, asked for just before a sensitive step, a payment or a sign-in, as an extra precaution on top of the other authentication methods (CC-IIZIRUN-BIOMETRIC-API). Got from IClientSessionGyro.getBiometricAuthentication(), never null: a client that is not iiziRun answers "not available".

What the client reports. The server asks an iiziRun client for its report when the client session is created, and the report is cached here: isReported() says whether one arrived, and the getters answer from it; before it arrives, or in a client that is not iiziRun, they answer "not available". The report is asked again with requestReport(Consumer), since a user can enroll a face or a finger at any time. The report is the client's own statement.

The check. authenticate(BiometricPrompt, Consumer) sends the prompt to the client, which shows the platform's biometric prompt and answers; the callback runs on the worker of the application session, where every other answer of the client is delivered, never on the calling thread while it waits. A check that the client does not answer in time, a client session disposed of while it waits, and a second check while one waits are answered with the errors BiometricError.TIMEOUT, BiometricError.SESSION_CLOSED and BiometricError.IN_PROGRESS; the callback is always called exactly once.

Emulation. iiziRun Developer's Settings switch "Emulate Biometric auth" (shown on a device without biometrics) makes the client answer every check with an emulated success, which the client marks as such: isEmulated() reports the switch, and the result's BiometricResult.emulated() marks the answer. An emulated answer counts as success only when the prompt allows it (BiometricPrompt.allowEmulated(boolean)) and the server is a development server; otherwise it is the error BiometricError.EMULATED.

Author:
Christopher Mindus
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static enum 
    Whether the device has a credential (passcode, PIN, pattern or password) that a prompt may let stand in for a biometric.
  • Method Summary

    Modifier and Type
    Method
    Description
    int
    Asks the user to pass the device's biometric check.
    Gets whether the device has a credential a prompt may let stand in.
    Gets the kind of biometric the device offers.
    Gets the message the plugin answered with the reason.
    Gets why no biometric check can be made.
    boolean
    Checks if the client reported that it is an iPhone or iPad app running on an Apple-silicon Mac (device.isiOSAppOnMac), where the biometric check is the Mac's Touch ID or the user's password.
    boolean
    Checks if a check of this client session waits for the client.
    boolean
    Checks if a biometric check can be made: the plugin is present and reported a biometric type, or iiziRun Developer's emulation is on and this is a development server.
    boolean
    Checks if iiziRun Developer's biometric emulation is on: the client answers every check with an emulated success.
    boolean
    Checks if the client carries the plugin (window.Fingerprint).
    boolean
    Checks if the client has reported what it can do.
    boolean
    Checks if the biometric is strong: on Android, class 3 (BIOMETRIC_STRONG, which the plugin's isAvailable with requireStrongBiometrics answers); on iOS every biometric is.
    boolean
    Checks if the client reported that it runs on a simulator or an emulator (Cordova's device.isVirtual).
    int
    Asks the client for its report again.
  • Method Details

    • isReported

      boolean isReported()
      Checks if the client has reported what it can do.
      Returns:
      true when a report arrived; false before it, after the client failed to answer within the deadline, and in a client that is not iiziRun.
    • isAvailable

      boolean isAvailable()
      Checks if a biometric check can be made: the plugin is present and reported a biometric type, or iiziRun Developer's emulation is on and this is a development server.
      Returns:
      true when authenticate(BiometricPrompt, Consumer) can be expected to prompt the user.
    • getType

      BiometricType getType()
      Gets the kind of biometric the device offers.
      Returns:
      The type: BiometricType.NONE before the report and when none is available, BiometricType.DEVICE_CREDENTIAL when only the device credential is.
    • isStrong

      boolean isStrong()
      Checks if the biometric is strong: on Android, class 3 (BIOMETRIC_STRONG, which the plugin's isAvailable with requireStrongBiometrics answers); on iOS every biometric is. A device whose only biometric is weak (class 2, face unlock on many Android phones) reports a type and false here: the plugin's prompt accepts it all the same, so a caller that wants a strong one reads this.
      Returns:
      true for a strong biometric, false when weak, not available or not reported.
    • getDeviceCredential

      Gets whether the device has a credential a prompt may let stand in.
      Returns:
      The answer, IBiometricAuthentication.DeviceCredential.UNKNOWN before the report.
    • isVirtual

      boolean isVirtual()
      Checks if the client reported that it runs on a simulator or an emulator (Cordova's device.isVirtual). The iOS Simulator and the Android emulator can answer a check (Features > Face ID > Matching Face, adb emu finger touch); the caller decides what that is worth, or refuses it with BiometricPrompt.rejectVirtual(boolean).
      Returns:
      true for a virtual device, false otherwise or before the report.
    • isAppOnMac

      boolean isAppOnMac()
      Checks if the client reported that it is an iPhone or iPad app running on an Apple-silicon Mac (device.isiOSAppOnMac), where the biometric check is the Mac's Touch ID or the user's password.
      Returns:
      true on a Mac, false otherwise or before the report.
    • isEmulated

      boolean isEmulated()
      Checks if iiziRun Developer's biometric emulation is on: the client answers every check with an emulated success.
      Returns:
      true when on, false otherwise or before the report.
    • isPluginPresent

      boolean isPluginPresent()
      Checks if the client carries the plugin (window.Fingerprint).
      Returns:
      true when present, false otherwise or before the report.
    • getUnavailableReason

      BiometricError getUnavailableReason()
      Gets why no biometric check can be made.
      Returns:
      null when one can (isAvailable()); otherwise BiometricError.NOT_IIZIRUN, BiometricError.PLUGIN_ABSENT, the plugin's own error (BIOMETRIC_NOT_ENROLLED, BIOMETRIC_HARDWARE_NOT_SUPPORTED, ...), or BiometricError.BIOMETRIC_UNAVAILABLE when the plugin answered no type without an error. Before the report: BiometricError.BIOMETRIC_UNAVAILABLE in an iiziRun client, which may still report, BiometricError.NOT_IIZIRUN in any other.
    • getUnavailableMessage

      String getUnavailableMessage()
      Gets the message the plugin answered with the reason.
      Returns:
      The message, or null when there is none.
    • requestReport

      int requestReport(Consumer<IBiometricAuthentication> callback)
      Asks the client for its report again. The callback gets this instance once the report arrived, or once the deadline passed without one (isReported() then says which, and a report that arrived earlier is kept); it runs on the worker of the application session. In a client that is not iiziRun, or when the session is disposed of, the callback is called at once with the state as it is.
      Parameters:
      callback - The callback, or null for none.
      Returns:
      The request ID, or 0 when nothing was sent.
    • authenticate

      int authenticate(BiometricPrompt prompt, Consumer<BiometricResult> callback)
      Asks the user to pass the device's biometric check. The client shows the platform's prompt with the texts of the prompt and answers; the callback gets the result exactly once, on the worker of the application session. An error the server answers itself is delivered at once: BiometricError.IN_PROGRESS while another check of this client session waits, BiometricError.SESSION_CLOSED when the session is disposed of, BiometricError.VIRTUAL_DEVICE when the prompt refuses a virtual device the client reported, BiometricError.NOT_IIZIRUN in a client that is not iiziRun. The others come from the client: a success, the plugin's error (BiometricError.BIOMETRIC_DISMISSED for a cancelled prompt, ...), BiometricError.PLUGIN_ABSENT; and the server's BiometricError.TIMEOUT when the client does not answer within the prompt's timeout.

      A success is the client's own statement: see the class comment.

      Parameters:
      prompt - What the user is shown and what the check accepts.
      callback - The callback, called exactly once.
      Returns:
      The request ID, or 0 when nothing was sent and the callback was called at once.
      Throws:
      NullPointerException - If a parameter is null.
    • isAuthenticating

      boolean isAuthenticating()
      Checks if a check of this client session waits for the client.
      Returns:
      true while one waits.