Biometry Setup

Edit on Github Send Feedback v2.1.1

PowerAuth SDK provides an abstraction on top of the base biometry (on Android) and Touch and Face ID (on iOS) support. While the authentication / data signing itself is nicely and transparently embedded in the PowerAuthAuthentication object used in regular request signing, other biometry-related processes require their own API.

Check Biometry Status

You have to check for biometry on three levels:

System Availability: If a biometric scanner (for example Touch ID on iOS or Fingerprint reader on Android) is present on the system/device.
Activation Availability: If biometry factor data are available for given activation.
Application Availability: If the user decided to use biometry for the given app. (optional)

PowerAuth SDK provides code for the first two of these checks.

To check if you can use biometry on the system, use the following code:

const biometryStatus = await powerAuth.getBiometryInfo();

// Is biometric authentication is supported on the system?
// Note that the property contains "false" on iOS if biometry is not enrolled or if it has been locked down. 
// To distinguish between availability and lockdown you can use `biometryType` and `canAuthenticate`.
const isAvailable = biometryStatus.isAvailable;

// Type of biometry supported on the system.
// For example "FINGERPRINT" if Fingerprint scanner/TouchID is present on the device
const biometryType = biometryStatus.biometryType;

// Status of biometric authentication availability.
// For example "NOT_ENROLLED". 
const authenticateStatus = biometryStatus.canAuthenticate;

To check if a given activation has biometry factor-related data available, use the following code:

// Does activation have biometric factor-related data in place?
const hasBiometryFactor = await powerAuth.hasBiometryFactor();

The last check (Application Availability) is fully under your control. By keeping the biometry settings flag, for example, a boolean in NSUserDefaults/SharedPreferences, you are able to show expected user biometry status (in a disabled state, though) even in the case biometry is not enabled or when no finger or face is enrolled on the device.

Enable Biometry

In case an activation does not yet have biometry-related factor data, and you would like to enable it, the device must first retrieve the original private key from the secure vault for the purpose of key derivation. As a result, you have to use a successful 2FA with a password to enable biometry support.

Use the following code to enable biometric authentication:

const password = "1234";
try {
    // Establish biometric data using provided password
    await powerAuth.addBiometryFactor(password, "Add biometry", "Allow biometry factor");
    // success
} catch (e) {
    //failed
}

Disable Biometry

You can remove biometry related factor data by simply removing the related key locally, using this one-liner:

// Remove biometric data
const result =  await powerAuth.removeBiometryFactor();

Fetch Biometry Credentials In Advance

You can acquire biometry credentials in advance in case that business processes require computing two or more different PowerAuth biometry signatures in one interaction with the user. To achieve this, the application must acquire the custom-created PowerAuthAuthentication object first and then use it for the required signature calculations. It’s recommended to keep this instance referenced only for a limited time, required for all future signature calculations.

Be aware, that you must not execute the next HTTP request signed with the same credentials when the previous one fails with the 401 HTTP status code. If you do, then you risk blocking the user’s activation on the server.

In order to obtain biometry credentials for the future sig nature calculation, call the following code:

// Authenticate user with biometry and obtain PowerAuthAuthentication credentials for future signature calculation.
const auth = new PowerAuthAuthentication();
auth.usePossession = true;
auth.userPassword = null;
auth.useBiometry = true;
auth.biometryTitle = "Grouped authentication";
auth.biometryMessage = "One biometric authentication will be used for 2 operations.";
    
try {
    await powerAuth.groupedBiometricAuthentication(auth, async (reusableAuth) => {
        try {
            const r1 = await powerAuth.requestSignature(reusableAuth, "POST", "/operation/test", "{jsonbody: \"test1\"}");
            console.log(`r1 success`);
            const r2 = await powerAuth.requestSignature(reusableAuth, "POST", "/operation/test2", "{jsonbody: \"test2\"}");
            console.log(`r2 success`);
            // success
        } catch (e) {
            // reusableAuth usage failed    
        }
    });
} catch(e) {
    // failed to create grouped biometric authentication
}

By default, the biometry factor-related key is NOT invalidated after the biometry enrolled in the system is changed. For example, if the user adds or removes the finger or enrolls with a new face, then the biometry factor-related key is still available for the signing operation. To change this behavior, you have to initialize the SDK in the native layer.

Be aware that the configuration below is effective only for the new keys. So, if your application is already using the biometry factor-related key with a different configuration, then the configuration change doesn’t change the existing key. You have to disable and enable biometry to apply the change.

iOS

On iOS, you have to provide PowerAuthKeychainConfiguration object with linkBiometricItemsToCurrentSet parameter set to YES and use that configuration for the PowerAuth object configuration:

// Get the React Native bridge module
PowerAuth *pa = [bridge moduleForClass:PowerAuth.class];
// Prepare your PA config
PowerAuthConfiguration *config = [[PowerAuthConfiguration alloc] init];
// ...

// Prepare PA2KeychainConfiguration
// Set YES to 'linkBiometricItemsToCurrentSet' property.
PowerAuthKeychainConfiguration *keychainConfiguration = [[PowerAuthKeychainConfiguration alloc] init];
keychainConfiguration.linkBiometricItemsToCurrentSet = YES;

// Init shared PowerAuthSDK instance
[pa configureWithConfig:config keychainConfig:keychainConfiguration clientConfig:nil];

Android

On Android, you have to provide PowerAuthKeychainConfiguration object with linkBiometricItemsToCurrentSet parameter set to true and use that configuration for the PowerAuthRNPackage object configuration:

for (ReactPackage pkg : this.getReactNativeHost().getReactInstanceManager().getPackages()) {
    if (pkg instanceof PowerAuthRNPackage) {
        try {
            String instanceId = "your-app-activation";
            PowerAuthSDK.Builder builder = new PowerAuthSDK.Builder(
              new PowerAuthConfiguration.Builder(instanceId, "https://your-powerauth-endpoint.com/", "APPLICATION_KEY", "APPLICATION_SECRET", "KEY_SERVER_MPK").build()
            );
            PowerAuthKeychainConfiguration.Builder keychainConfiguration = new PowerAuthKeychainConfiguration.Builder();
            keychainConfiguration.linkBiometricItemsToCurrentSet(true);
            builder.keychainConfiguration(keychainConfiguration.build());
            ((PowerAuthRNPackage) pkg).configure(instanceId, builder);
        } catch (Exception e) {
            // error
        }
    }
}