8.8 released—CSS Media Query support, SF Symbols and much more...
Learn more

View on GitHub

@nativescript/biometrics

Contents

Intro

A plugin that allows you to authenticate users with biometrics, such as fingerprints, facial recognition, etc.

Note This plugin replaces @nativescript/fingerprint-auth.

Installation

cli
npm install @nativescript/biometrics

Note This plugin replaces @nativescript/fingerprint-auth.

Use the @nativescript/biometrics plugin

Check if the device supports biometrics authentification

To check if the device supports biometrics authentication, call the available() method on a BiometricAuth instance.

ts
import {
  BiometricAuth,
  BiometricIDAvailableResult,
} from '@nativescript/biometrics'

var biometricAuth = new BiometricAuth()

biometricAuth.available().then((result: BiometricIDAvailableResult) => {
  console.log(`Biometric ID available? ${result.any}`)
  console.log(`Touch? ${result.touch}`)
  console.log(`Face? ${result.face}`)
  console.log(`Biometrics? ${result.biometrics}`)
})

Biometrics authentification support on Android

  • It's only supported on API 23+.
  • In some devices, the OS does not consider face recognition secure enough and as a result, your app cannot use it for biometric authentication. This is the case with many Samsung devices. For example, Samsung Galaxy S10 ha Consequently, if the device has Face Recognition enabled and face scan saved, available() returns { any: true, biometrics: false }.

Face ID authentification support on iOS

  • It is only supported in iOS 11+.

  • To allow Face ID support in your app, provide the reason of supporting it as the value of the NSFaceIDUsageDescription key in the app/App_Resources/ios/Info.plist file:

xml
<key>NSFaceIDUsageDescription</key>
<string>For easy authentication with our app.</string>
  • On a simulator, to enroll a face and test Face ID authentification, use the Features->Face ID menu items.

Verify user biometrics

To verify user biometrics, call the verifyBiometric() method and pass it a VerifyBiometricOptions object.

Note: iOS > verifyBiometric() will fail on IOS simulator unless the pinfallBack option is used.

typescript
biometricAuth
  .verifyBiometric({
    title: 'Android title', // optional title (used only on Android)
    message: 'Scan your finger', // optional (used on both platforms) - for FaceID on iOS see the notes about NSFaceIDUsageDescription
    fallbackMessage: 'Enter your PIN', // this will be the text to show for the "fallback" button on the biometric prompt
    pinFallback: true, // allow fall back to pin/password
  })
  .then((result?: BiometricResult) => {
    if (result.code === ERROR_CODES.SUCCESS) {
      console.log('Biometric ID OK')
    }
  })
  .catch((err) => console.log(`Biometric ID NOT OK: ${JSON.stringify(err)}`))

Detect change in enrolled fingerprints (iOS)

For iOS 9+ you can check if enrolled fingerprints have changed since the last time you checked it. It's recommended you add this check to counter hacker attacks on your app. For more details, see this article.

To check if enrolled fingerprints have changed, call the didBiometricDatabaseChange() method. If it returns true, you probably want to re-authenticate your user before accepting valid fingerprints again.

typescript
biometricAuth.available().then((avail) => {
  if (!avail) {
    return
  }
  biometricAuth.didBiometricDatabaseChange().then((changed) => {
    if (changed) {
      // re-auth the user by asking for his credentials before allowing a fingerprint scan again
    } else {
      // call the fingerprint scanner
    }
  })
})

Biometrics and cryptography

To combine biometrics authentification with cryptography, for more secure data protection, set the secret and keyName options when you call verifyBiometric().

If you do not pass the pinFallback or keyName options to the verifyBiometric() method, the plugin will automatically:

  1. create a secure key
  2. prompts the user to authenticate for a face/fingerprint
  3. attempts to use the key to encrypt some text.

That automatic key generation, however, is not foolproof.

Encrypting/Decrypting with biometrics authentication

The best practice is to use the options to encrypt some secret that is validated independently.

Encrypting your secret

To encrypt some sensitive string, pass the secret and keyNameoptions to the verifyBiometric() method. Set the sensitive string as the secret property's value and the name of the key to access that secret as the value of the keyName property.

typescript
biometricAuth
  .verifyBiometric({
    title: 'Enter your password',
    message: 'Scan your finger', // optional
    pinFallback: false, // do not allow pinFallback to enable crypto operations
    keyName: 'MySecretKeyName', // The name of the key that will be created/used
    secret: 'The Secret I want encrypted',
  })
  .then((result) => {
    const encryptedText = result.encrypted // The text encrypted with a key named "MySecretKeyName" (Android Only)
    const IV = result.iv // the  initialization vector used to encrypt (Android Only)

    // For IOS the secret is stored in the keycain
  })
  .catch((err) =>
    this.set('status', `Biometric ID NOT OK: " + ${JSON.stringify(err)}`)
  )

For Android, the encrypted and initialization vector is then stored in your app and used each time when signing in the user with verifyBiometric():

Decrypting your secret

typescript
biometricAuth
  .verifyBiometric({
    title: 'Enter your password',
    message: 'Scan yer finger', // optional
    keyName: 'MySecretKeyName', // The name of the key that will be created/used
    pinFallback: false, // do not allow pinFallback to enable crypto operations
    android: {
      decryptText: 'The encrypted text retrieved previously',
      iv: 'The IV retrieved previously',
    },
    ios: { fetchSecret: true }, // Tell IOS to fetch the secret
  })
  .then((result) => {
    const decryptedText = result.decrypted // The unencrypted secret
    verifyMySecret(decryptedText) // verify the secret by some means, e.g. a call to a back end server.
  })
  .catch((err) =>
    this.set('status', `Biometric ID NOT OK: " + ${JSON.stringify(err)}`)
  )

Fallback to Pin

To allow biometrics authentification to fallback on lock screen credentials, set pinFallback to true. Note that thissetting also disables cryptography.

typescript
biometricAuth
  .verifyBiometric({
    title: 'Enter your password',
    message: 'Scan yer finger', // optional
    fallbackMessage: 'Enter PIN', // optional
    pinFallback: true,
    ios: { customFallback: false }, // passing true here will show the fallback message and allow you to handle this in a custom manner.
  })
  .then((result) => {
    console.log('Fingerprint/ PIN was OK')
  })
  .catch((err) =>
    this.set('status', `Biometric ID NOT OK: " + ${JSON.stringify(err)}`)
  )

API

BiometricAuth Class

NameReturn TypeDescription
available()Promise<BiometricIDAvailableResult>Checks if biometric authentification is supported on the device. See BiometricIDAvailableResult for more details.
didBiometricDatabaseChange(options?: VerifyBiometricOptions)Promise<boolean>Checks if there is a change in a biometric of the user.
verifyBiometric(options: VerifyBiometricOptions)Promise<BiometricResult>Verifies the biometrics auth using the specified VerifyBiometricOptions object.
close()voidCloses Face/Fingerprint prompt. If pinFallBack is true, close() does not have effect on Android.
deleteKey(keyName?: string)voidDeletes the specified key.

BiometricIDAvailableResult interface

NameTypeDescription
anybooleantrue if no biometric authentification is available on android but device has pin/pattern/password set.
touchbooleanOptional: iOS only
facebooleanOptional: iOS only
biometricsbooleanOptional: (Android only) indicates if Face/Fingerprint is available.

VerifyBiometricOptions interface

NameTypeDescription
titlestringOptional: (Android only)The title for the the fingerprint screen. Defaults to whatever the device default is.
subTitlestringOptional : (Android only) Subtitle in the fingerprint screen. Defaults to ''
messagestringOptional: Description of the finngerprint screen. Defaults to 'Scan your finger' on iOS and on Android is likely 'Enter your device password to continue'.
confirmbooleanOptional : (Android only) The confirm button after biometrics have been verified in the fingerprint screen. Defaults to false.
fallbackMessagestringOptional: Button label when scanning the fingerprint fails. Defaults to 'Enter password'.
On Android:
- when pinFallback= true this will be the text displayed on the pin dialog.
- When pinFallback = false this will be the Negative button text on the Biometric Prompt.
pinFallbackbooleanOptional: Allow Fallback to Pin - note that if true no cryptographic operations will happen and Face ID is not available on Android.
keyNamestringOptional: Name of the key to use for crypto operations. Will be created if it you don't provide it. It's not used if pinFallback = true.
androidAndroidOptionsOptional: Android-specific options.
iosIOSOptionsOptional: iOS-specific options.

IOSOptions interface

NameTypeDescription
customFallbackbooleanOptional: Indicates whether to allow a custom fallback from biometrics.
fetchSecretbooleanOptional: Indicates whether to attempt to fetch secret from the specified key.

AndroidOptions interface

NameTypeDescription
decryptTextstringIf set and pinFallback is true, and keyName is set then this string will be decrypted via the Biometric controlled Key.
If set and pinFallback is true, and keyName is set then this string will be decrypted via the Biometric controlled Key.
ivstringOptional: Retrieved from the result of an encryption.
validityDurationnumberOptional: The period, in seconds, for which operations on the key are valid without triggering a biometric prompt.

BiometricResult interface

NameTypeDescription
codeERROR_CODES
messagestring
encryptedstringOptional
decryptedstringOptional
ivstringOptional

ERROR_CODES Enum

typescript
enum ERROR_CODES {
  PASSWORD_FALLBACK_SELECTED = -3, // historically this is what iOS uses, so using that as well
  SUCCESS = 0,
  DEVELOPER_ERROR = 10,
  NOT_AVAILABLE = 20,
  NOT_CONFIGURED = 30,
  NOT_RECOGNIZED = 40,
  RECOVERABLE_ERROR = 50,
  USER_CANCELLED = 60,
  UNEXPECTED_ERROR = 70,
}

License

Apache License Version 2.0