Biometric authentication enables your users to leverage their devices' built-in biometric authenticators such as FaceID and TouchID for quick and seamless login experiences.
Biometrics
Configuration
Stytch's Biometrics product supports iOS 13.0+ and Android 6+. We only support Class 3 biometric sensors on Android.
Important: If you are testing biometrics on an iOS simulator or Android emulator, please ensure you are using one of the following versions: iOS 13 or 14, Android 11 or below. This should not be an issue on physical devices.
Methods
The SDK provides methods that can be used to authenticate users with biometric factors. Biometric factors must first be added to an existing user, and then later used as a primary or secondary authentication factor. To call these methods, Biometrics must be enabled in the SDK Configuration page of the Stytch dashboard.
Register
If an active session is present, this method will add a biometric registration for the current user. The user will later be able to start a new session with biometrics or use biometrics as an additional authentication factor.
Method parameters
Options* object
Configuration options.
prompt* string
cancelButtonText string
allowDeviceCredentials string
allowFallbackToCleartext string
sessionDurationMinutes string
import React, { useCallback } from 'react';
import { useStytch, useStytchSession } from '@stytch/react-native';
export const Register = () => {
const stytchClient = useStytch();
const { session } = useStytchSession();
const registerBiometrics = useCallback(() => {
if (session) {
stytchClient.biometrics.register({
prompt: 'Register Your Biometric Factor',
});
}
}, [stytchClient]);
return (
<View>
<TouchableOpacity onPress={registerBiometrics}>
<Text>Register with Biometrics</Text>
</TouchableOpacity>
</View>
);
};Authenticate
If a valid biometric registration exists, this method confirms the current device owner via the device's built-in biometric reader and returns a session object by either starting a new session or adding a biometric factor to an existing session.
Method parameters
Options* object
Configuration options.
prompt* string
session_duration_minutes* int
cancelButtonText string
allowDeviceCredentials string
import React, { useCallback } from 'react';
import { useStytch } from '@stytch/react-native';
export const Authenticate = () => {
const stytchClient = useStytch();
const authenticateBiometrics = useCallback(() => {
stytchClient.biometrics.authenticate({
prompt: 'Login with Biometrics',
sessionDurationMinutes: 60,
});
}, [stytchClient]);
return (
<View>
<TouchableOpacity onPress={authenticateBiometrics}>
<Text>Authenticate with Biometrics</Text>
</TouchableOpacity>
</View>
);
};Keystore available
Indicates whether or not the Keystore is available on the device. This will always return true for iOS devices. A percentage of Android devices will return false. To learn more about the implications of the Android Keystore being unavailable, read our Android Keystore resource.
import React, { useCallback, useMemo } from 'react';
import { useStytch, useStytchSession } from '@stytch/react-native';
export const Register = () => {
const stytchClient = useStytch();
const { session } = useStytchSession();
const isKeystoreAvailable = useMemo(async () => {
if (stytchClient) {
return await stytchClient.biometrics.isKeystoreAvailable();
} else {
return false;
}
}, [stytchClient]);
const registerBiometrics = useCallback(() => {
if (session) {
stytchClient.biometrics.register({
prompt: 'Register Your Biometric Factor',
});
}
}, [stytchClient]);
return isKeystoreAvailable ? (
<View>
<TouchableOpacity onPress={registerBiometrics}>
<Text>Register with Biometrics</Text>
</TouchableOpacity>
</View>
) : null;
};Registration available
Indicates if there is an existing biometric registration on device. This method can be used to determine whether or not to show biometric login or registration options.
import React, { useCallback, useMemo } from 'react';
import { useStytch } from '@stytch/react-native';
export const Authenticate = () => {
const stytchClient = useStytch();
const isBiometricsAvailable = useMemo(async () => {
if (stytchClient) {
return await stytchClient.biometrics.isRegistrationAvailable();
} else {
return false;
}
}, [stytchClient]);
const authenticateBiometrics = useCallback(() => {
stytchClient.biometrics.authenticate({
prompt: 'Login with Biometrics',
sessionDurationMinutes: 60,
});
}, [stytchClient]);
return isBiometricsAvailable ? (
<View>
<TouchableOpacity onPress={authenticateBiometrics}>
<Text>Authenticate with Biometrics</Text>
</TouchableOpacity>
</View>
) : null;
};Remove registration
Clears the existing biometric registration stored on device. This method is useful for removing a user from a given device.
import React, { useCallback, useMemo } from 'react';
import { useStytch } from '@stytch/react-native';
export const RemoveRegistration = () => {
const stytchClient = useStytch();
const isBiometricsAvailable = useMemo(async () => {
if (stytchClient) {
return await stytchClient.biometrics.isRegistrationAvailable();
} else {
return false;
}
}, [stytchClient]);
const removeBiometricsRegistration = useCallback(() => {
stytchClient.biometrics.removeRegistration();
}, [stytchClient]);
return isBiometricsAvailable ? (
<View>
<TouchableOpacity onPress={removeBiometricsRegistration}>
<Text>Delete Biometric Factor</Text>
</TouchableOpacity>
</View>
) : null;
};Get sensor
Checks if biometric sensors are available on the device. This method can be used to determine whether or not to show biometric registration options.
Method parameters
allowDeviceCredentials string
import React, { useCallback, useMemo } from 'react';
import { useStytch } from '@stytch/react-native';
export const Register = () => {
const stytchClient = useStytch();
const isSensorAvailable = useMemo(async () => {
if (stytchClient) {
try {
await stytchClient.biometrics.getSensor();
return true;
} catch {
return false;
}
} else {
return false;
}
}, [stytchClient]);
const registerBiometrics = useCallback(() => {
stytchClient.biometrics.register({
prompt: 'Register with Biometrics',
});
}, [stytchClient]);
return isSensorAvailable ? (
<View>
<TouchableOpacity onPress={registerBiometrics}>
<Text>Register with Biometrics</Text>
</TouchableOpacity>
</View>
) : null;
};Errors
biometrics_sensor_error
There was an error with the biometric sensor on the device. This usually means that the biometric sensor is currently unavailable for use.
device_credentials_not_allowed
This means that allowDeviceCredentials was set to false in register(), but allowDeviceCredentials was set to true in authenticate(). Consider changing these parameters to be the same.
device_hardware_error
The device's hardware does not support biometrics. This might be because the hardware is unavailable for use, or there is a security vulnerability with the hardware.
internal_error
An internal error has occurred. Please contact Stytch if this occurs.
key_invalidated
The biometrics enrollment on the device has changed, so biometric authentication cannot use the current registration. Try deleting the registration and authenticating again.
no_biometrics_enrolled
No biometric factor is enrolled on the device. Consider encouraging the user to enroll in biometrics on their device.
no_biometrics_registration
No valid biometrics registration exists on the device. Please use the register method to create a new biometric registration.
session_expired
There is currently no valid session token. Consider encouraging the user to log in.
user_cancellation
The user canceled the biometric prompt. Consider providing other methods of authentication, and a way for the user to return to the biometric prompt.
user_locked_out
The user has been locked out from authentication using biometrics due to too many failed attempts. Consider providing other methods of authentication.