The Native Biometric Authentication ASM can optionally be included in your app. This ASM authenticates the user during FIDO operations. It uses the biometric authentication available on the device (fingerprint, face, and iris on Android, Touch ID or Face ID on iOS).

For Android, there are two types of authentication methods: strong and weak. Native Biometric ASM works with strong authentication methods. Regardless of the authentication method registered on the device, this ASM will be visible on the list of authenticators. However, an attempt to register the Native Biometric ASM using only the weak method authentication will fail.
The Android Compatibility Definition Document defines the requirements for each type of biometric authentication methods.

Dependencies

To integrate this ASM, first add the Common ASM to your application’s module build.gradle file. See Dependencies for more information about the Common ASM Android dependencies.

Next, add the Biometric ASM artifact and its dependencies. After you added this, the build.gradle file should look like this:

dependencies {
     // CommonASM and its dependencies
     api files(‘path to library
     /FIDOUAFNativeBiometricAuthenticationASM.aar’)
     api files(‘path to library/BiometricSensorSDK.aar’)
     api "androidx.appcompat:appcompat:1.3.0"
     api "androidx.biometric:biometric:1.1.0@aar"
}

Permission

The following Android permissions will automatically be added to your binary:

  • android.permission.USE_FINGERPRINT: to access the fingerprint sensor for devices with Android SDK 28 and earlier.
  • android.permission.USE_BIOMETRIC: to access the biometric sensors (such as fingerprint, face, and iris) for devices with Android SDK 29 and later.

Descriptor and metadata

Add the following line to the descriptorclass array in your res/raw/asmdescriptors.json file:

com.vasco.fido.uaf.asm.presence.NativeBiometricAuthenticationASMDescriptor

See Embedding an authenticator for more details.

This ASM is delivered with the following metadata files for Android:

  • BD51#000F (secure hardware protected devices with ECDSA)
  • BD51#0011 (software protected devices with ECDSA)

Customization

You can omit the customization of the ASM—this is an optional feature of the FIDO Authentication Solution!

You can use the Android XML system to customize the ASM.

To facilitate the customization, you can use the default resources from the package (FIDO UAF SDK /Android/Native Biometric Authentication ASM/Values Values).

Native Biometric Authentication ASM—Registration on Android shows the customized registration screen on an Android device.

Native Biometric Authentication ASM—Registration on Android

Strings

The following raw string values can be customized via the strings.xml file:

Native Biometric Authentication ASM—Customization Strings
Key Default text Description
vds_asm_native_biometry_text_title Biometric Authenticator Title
vds_asm_native_biometry_text_description You will be authenticated with your biometry during sensitive operations. Description
vds_asm_native_biometry_text_title_registration Biometric Authenticator Title text for registration
vds_asm_native_biometry_text_subtitle_registration Authentication required Subtitle text for registration
vds_asm_native_biometry_text_description_registration Use your biometric scanner to authenticate and finalize the registration process. Description text for registration
vds_asm_native_biometry_text_title_authentication Biometric Authenticator Title text for authentication
vds_asm_native_biometry_text_subtitle_authentication Authentication required Subtitle text for authentication
vds_asm_native_biometry_text_description_authentication Use your biometric scanner to authenticate. Description text for authentication
vds_asm_native_biometry_text_cancel Cancel Text for the cancel button

Colors

The following colors in #argb and #rgb hex format can be customized via the colors.xml file.

Native Biometric Authentication ASM—Customization Colors
Key Default text Description
vds_asm_native_biometry_text_color #ff000000 Color of the title text and dialog buttons
vds_asm_native_biometry_text_error_color #ffff0000 Text color in case of error
vds_asm_native_biometry_background_color #ffffffff Background color

Icon

You can customize the icon that is displayed when the user has to choose between authenticators. It depends on the following resource string:

  • vds_asm_biometry_icon_drawable_name

The string value (by default vds_asm_native_biometry_icon) corresponds to the name of a drawable resource, usually located in the drawable part of the Android resources system (e.g. res/drawable/vds_asm_native_biometry_icon.png).

Biometric Icon—Example

Key deletion

Some conditions can lead to the deletion of the authenticator key; this renders it unusable for any user until the key is registered again.

The authentication key will be deleted if:

  • the user adds a biometric template (fingerprint, face, or iris), or
  • the user removes a biometric template from their device's biometric configuration.

In these cases, the user will have to register the authenticator again. After each biometric template has been removed one by one from the configuration, the key is also deleted.

The key deletion feature relies on the hardware implementation of security measures; thus the behavior might vary between devices from different vendors.

Devices running on the Android platform will also trigger key deletion when:

  • a user disables their lock screen by changing the setting to None, Swipe, or another mode which does not authenticate the user.
  • the user's lock screen is forcibly reset (e.g. by the device administrator).

After that, the biometric authenticator has to be registered to be used again.

To enable or disable this feature, set the vds_asm_native_biometry_invalidate_when_changed Boolean resource accordingly. If not provided, it is set to true by default.


values/bool.xml
<bool name="vds_asm_native_biometry_invalidate_when_changed">true</bool>

Dependencies

To integrate this ASM, add the following dependencies to your app:

  • All the Common ASM iOS dependencies as listed in Dependencies.
  • FIDOUAFNativeBiometricAuthenticationASMResources.bundle (linked framework and libraries)
  • FIDOUAFNativeBiometricAuthenticationASM.xcframework (linked framework and libraries)
  • MSSBiometricSensor.xcframework (linked framework and libraries)

Initialization and metadata

To integrate biometric authentication with C++

  • According to your requirements (i.e. use Touch ID or Face ID authenticators independently or at the same time), add the following lines to AppDelegate in the didFinishLaunchingWithOptions: method:

#import <FIDOUAFNativeBiometricAuthenticationASM/
FIDONativeBiometricAuthenticationASMInstanceCreator.hpp>

asmcore::ASMFactory::addAuthenticator
(FIDONativeBiometricAuthenticationASMInstanceCreator::createTouchIDInstance());

asmcore::ASMFactory::addAuthenticator
(FIDONativeBiometricAuthenticationASMInstanceCreator::createFaceIDInstance());

See Embedding an authenticator for more details.

This ASM is delivered with the following metadata files for iOS:

  • Touch ID

    • BD51#0012 (secure hardware protected devices with ECDSA)

  • Face ID

    • BD51#0014 (secure hardware protected devices with ECDSA)

To integrate biometric authentication with Swift/Objective-C

  • According to your requirements (i.e. use Touch ID or Face ID authenticators independently or at the same time), add the following lines to AppDelegate in the didFinishLaunchingWithOptions: method:

FIDOUAFNativeBiometricAuthenticationASM

// Add Touch ID authenticator to ASM
FIDOBiometricASM.registerTouchIDAuthenticator()

// Add Face ID authenticator to ASM
FIDOBiometricASM.registerFaceIDAuthenticator()

See Embedding an authenticator for more details.

This ASM is delivered with the following metadata files for iOS:

  • Touch ID

    • BD51#0012 (secure hardware protected devices with ECDSA)

  • Face ID

    • BD51#0014 (secure hardware protected devices with ECDSA)

Touch ID customization

You can omit the customization of the ASM—this is an optional feature of the FIDO Authentication Solution!

You can use the iOS Localizable.strings to customize the ASM. Native Biometric Authentication ASM—Touch ID Registration shows the customized password registration screen on an iOS device.

Native Biometric Authentication ASM—Touch ID Registration

Customization keys

The following keys are available for the customization of this authenticator:

Native Biometric Authentication ASM—Customization Keys
Key Default text Description
vds_asm_native_biometric_fingerprint_text_title Fingerprint Authenticator Title
vds_asm_native_biometric_fingerprint_text_description You will be authenticated with your fingerprint during sensitive operations. Description
vds_asm_native_biometric_fingerprint_text_title_registration Use your fingerprint scanner to authenticate and finalize the registration process. Title text for registration
vds_asm_native_biometric_fingerprint_text_title_authentication Use your fingerprint scanner to authenticate. Title text for authentication
vds_asm_native_biometric_fingerprint_text_error_failure The authentication has failed. Text displayed in case of authentication failure
vds_asm_native_biometric_fingerprint_text_os_lockout Fingerprint scanner locked by system. Text displayed when system lock the fingerprint scanner
vds_asm_native_biometric_fingerprint_text_error_failure_button OK Text displayed on the validation button in case of authentication failure

Icon

You can customize the icon that is displayed when the user has to choose between authenticators. It depends on the following resource string:

  • vds_asm_native_biometric_fingerprint_icon

The string value (by default vds_asm_touch_id_icon) corresponds to the name of a drawable resource, usually located in the binary (e.g. vds_asm_touch_id_icon.png).

Biometric Touch ID Icon—Example

Face ID customization

You can omit the customization of the ASM—this is an optional feature of the FIDO Authentication Solution!

You can use the iOS Localizable.strings to customize the ASM. Native Biometric Authentication ASM—Face ID Registration shows the customized password registration screen on an iOS device.

Native Biometric Authentication ASM—Face ID Registration

Customization keys

The following keys are available for the customization of this authenticator:

Native Biometric Authentication ASM—Customization Keys
Key Default text Description
vds_asm_native_biometric_face_text_title Face Authenticator (Face ID) Title
vds_asm_native_biometric_face_text_description You will be authenticated with your face during sensitive operations. Description
vds_asm_native_biometric_face_text_error_failure The authentication has failed. Text displayed in case of authentication failure
vds_asm_native_biometric_face_text_error_failure_button OK Text displayed on the validation button in case of authentication failure

Icon

You can customize the icon that is displayed when the user has to choose between authenticators. It depends on the following resource string:

  • vds_asm_native_biometric_face_icon

The string value (by default vds_asm_face_id_icon) corresponds to the name of a drawable resource, usually located in the binary (e.g. vds_asm_face_id_icon.png).

Biometric Face ID Icon—Example

Key deletion

Some conditions can lead to the deletion of the authenticator key; this renders it unusable for any user until the key is registered again. If the user adds a biometric template to their device's biometric configuration, the authentication key will be deleted and the user will have to register the authenticator again.

This feature works in the same way for FaceID entries: changes in the set of registered faces will be detected and will also trigger the key deletion.

To enable or disable this feature, set the BiometricInvalidateWhenChanged Boolean property in the project property list accordingly. If not provided, it is set to true by default.