Home

Awesome

Capacitor Native Biometric

Use biometrics confirm device owner presence or authenticate users. A couple of methods are provided to handle user credentials. These are securely stored using Keychain (iOS) and Keystore (Android).

Installation (Only supports Capacitor 3 and 4)

Usage

import { NativeBiometric } from "capacitor-native-biometric";

async performBiometricVerificatin(){
  const result = await NativeBiometric.isAvailable();

  if(!result.isAvailable) return;

  const isFaceID = result.biometryType == BiometryType.FACE_ID;

  const verified = await NativeBiometric.verifyIdentity({
    reason: "For easy log in",
    title: "Log in",
    subtitle: "Maybe add subtitle here?",
    description: "Maybe a description too?",
  })
    .then(() => true)
    .catch(() => false);

  if(!verified) return;

  const credentials = await NativeBiometric.getCredentials({
    server: "www.example.com",
  });
}

// Save user's credentials
NativeBiometric.setCredentials({
  username: "username",
  password: "password",
  server: "www.example.com",
}).then();

// Delete user's credentials
NativeBiometric.deleteCredentials({
  server: "www.example.com",
}).then();

Methods

MethodDefaultTypeDescription
isAvailable(options?: IsAvailableOptions)Promise<AvailableResult>Gets available biometrics
verifyIdentity(options?: BiometricOptions)Promise<void>Shows biometric prompt
setCredentials(options: SetCredentialOptions)Promise<void>Securely stores user's credentials in Keychain (iOS) or encypts them using Keystore (Android)
getCredentials(options: GetCredentialOptions)Promise<Credentials>Retrieves user's credentials if any
deleteCredentials(options: DeleteCredentialOptions)Promise<void>Removes user's credentials if any

Interfaces

IsAvailableOptions

PropertiesDefaultTypeDescription
useFallback?booleanSpecifies if the device should fallback to using passcode authentication.

AvailableResult

PropertiesDefaultTypeDescription
isAvailablebooleanSpecifies if the devices has biometric enrollment
biometryTypeBiometryTypeSpecifies the available biometric hardware on the device
errorCode?numberBiometric Auth Error Code

BiometryType - enum

PropertiesDescription
NONEThere is no biometry available
TOUCH_IDTouchID is available (iOS)
FACE_IDFaceID is available (iOS)
FINGERPRINTFingerprint is available (Android)
FACE_AUTHENTICATIONFace Authentication is available (Android)
IRIS_AUTHENTICATIONIris Authentication is available (Android)
MULTIPLEReturned when device has multiple biometric features. Currently there is no way of knowing which one is being used. (Android)

BiometricOptions

PropertiesDefaultTypeDescription
reason?"For biometric authentication"stringReason for requesting authentication in iOS. Displays in the authentication dialog presented to the user.
title?"Authenticate"stringTitle for the Android prompt
subtitle?stringSubtitle for the Android prompt
description?stringDescription for the Android prompt
negativeButtonText?"Cancel"stringText for the negative button displayed on Android
maxAttempts?1numberLimit the number of attempts a user can perform biometric authentication. (Android - Max 5)
useFallback?falsebooleanSpecifies if the device should fallback to using passcode authentication.

Biometric Auth Errors

This is a plugin specific list of error codes that can be thrown on verifyIdentity failure, or set as a part of isAvailable. It consolidates Android and iOS specific Authentication Error codes into one combined error list.

CodeDescriptionPlatform
0Unknown ErrorAndroid, iOS
1Biometrics UnavailableAndroid, iOS
2User LockoutAndroid, iOS
3Biometrics Not EnrolledAndroid, iOS
4User Temporary LockoutAndroid (Lockout for 30sec)
10Authentication FailedAndroid, iOS
11App CanceliOS
12Invalid ContextiOS
13Not InteractiveiOS
14Passcode Not SetAndroid, iOS
15System CancelAndroid, iOS
16User CancelAndroid, iOS
17User FallbackAndroid, iOS

SetCredentialOptions

PropertiesDefaultTypeDescription
usernamestringThe string used as the alias at the time of loggin in. It doesn't have to be a username. For example if you're using email to log in your users then provide the email.
passwordstringThe users' password
serverstringAny string to identify the credentials object with

GetCredentialOptions

PropertiesDefaultTypeDescription
serverstringThe string used to identify the credentials object when setting the credentials.

DeleteCredentialOptions

PropertiesDefaultTypeDescription
serverstringThe string used to identify the credentials object when setting the credentials.

Credentials

PropertiesDefaultTypeDescription
usernamestringThe username returned from getCredentials(options: GetCredentialOptions).
passwordstringThe password returned from getCredentials(options: GetCredentialOptions).

Face ID (iOS)

To use FaceID Make sure to provide a value for NSFaceIDUsageDescription, otherwise your app may crash on iOS devices with FaceID.

This value is just the reason for using FaceID. You can add something like the following example to App/info.plist:

<key>NSFaceIDUsageDescription</key>
<string>For an easier and faster log in.</string>

Biometric (Android)

To use android's BiometricPrompt api you must add the following permission to your AndroidManifest.xml:

<uses-permission android:name="android.permission.USE_BIOMETRIC">

And register the plugin by adding it to you MainActivity's onCreate (Not needed for Capacitor 3):

import com.epicshaggy.biometric.NativeBiometric;

public class MainActivity extends BridgeActivity {
  @Override
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    // Initializes the Bridge
    this.init(savedInstanceState, new ArrayList<Class<? extends Plugin>>() {{
      // Additional plugins you've installed go here
      // Ex: add(TotallyAwesomePlugin.class);
      add(NativeBiometric.class);
    }});
  }
}

Contributors

Jonthia One Click Web Studio Brian Weasner Mohamed Diarra

Want to Contribute?

Learn about contributing HERE

Notes

Hasn't been tested on Android API level 22 or lower.