Biometrics

@nativescript/biometrics #

Contents #

• Intro
• Installation
• Use @nativescript/biometrics
  • Check if the device supports biometrics authentification
  • Biometrics authentification support on Android
  • Face ID authentification support on iOS
  • Verify user biometrics
• API
  • BiometricAuth class
  • BiometricIDAvailableResult interface
  • IOSOptions interface
  • Android interface
  • BiometricResult interface
  • ERROR_CODES Enum
• License

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 #

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.

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:

<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.

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.

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.

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 #

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.

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 #

BiometricIDAvailableResult interface #

VerifyBiometricOptions interface #

IOSOptions interface #

AndroidOptions interface #

BiometricResult interface #

ERROR_CODES Enum #

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