This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 51).
Expo LocalAuthenticationA library that provides functionality for implementing the Fingerprint API (Android) or FaceID and TouchID (iOS) to authenticate the user with a face or fingerprint scan.
GitHub
npm
expo-local-authentication allows you to use the Biometric Prompt (Android) or FaceID and TouchID (iOS) to authenticate the user with a fingerprint or face scan.
Installation
- npx expo install expo-local-authenticationIf you are installing this in an existing React Native app (bare workflow), start by installing expo in your project. Then, follow the additional instructions as mentioned by library's README under "Installation in bare React Native projects" section.
Configuration in app.json/app.config.js
You can configure expo-local-authentication using its built-in config plugin if you use config plugins in your project (EAS Build or npx expo run:[android|ios]). The plugin allows you to configure various properties that cannot be set at runtime and require building a new app binary to take effect.
Example app.json with config plugin
{
"expo": {
"plugins": [
[
"expo-local-authentication",
{
"faceIDPermission": "Allow $(PRODUCT_NAME) to use Face ID."
}
]
]
}
}
Configurable properties
| Name | Default | Description |
|---|---|---|
faceIDPermission | "Allow $(PRODUCT_NAME) to use Face ID" | Only for: iOS A string to set the |
Are you using this library in a bare React Native app?
Learn how to configure the native projects in the installation instructions in the expo-local-authentication repository.
API
import * as LocalAuthentication from 'expo-local-authentication';
Methods
LocalAuthentication.authenticateAsync(options)
| Name | Type |
|---|---|
| options (optional) | LocalAuthenticationOptions |
Attempts to authenticate via Fingerprint/TouchID (or FaceID if available on the device).
Note: Apple requires apps which use FaceID to provide a description of why they use this API. If you try to use FaceID on an iPhone with FaceID without providing
infoPlist.NSFaceIDUsageDescriptioninapp.json, the module will authenticate using device passcode. For more information about usage descriptions on iOS, see permissions guide.
Returns a promise which fulfils with LocalAuthenticationResult.
LocalAuthentication.getEnrolledLevelAsync()
Determine what kind of authentication is enrolled on the device.
Returns a promise which fulfils with SecurityLevel.
Note: On Android devices prior to M,
SECRETcan be returned if only the SIM lock has been enrolled, which is not the method thatauthenticateAsyncprompts.
LocalAuthentication.hasHardwareAsync()
Determine whether a face or fingerprint scanner is available on the device.
Promise<boolean>
Returns a promise which fulfils with a boolean value indicating whether a face or
fingerprint scanner is available on this device.
LocalAuthentication.isEnrolledAsync()
Determine whether the device has saved fingerprints or facial data to use for authentication.
Promise<boolean>
Returns a promise which fulfils to boolean value indicating whether the device has
saved fingerprints or facial data for authentication.
LocalAuthentication.supportedAuthenticationTypesAsync()
Determine what kinds of authentications are available on the device.
Returns a promise which fulfils to an array containing AuthenticationTypes.
Devices can support multiple authentication methods- i.e. [1,2] means the device supports both
fingerprint and facial recognition. If none are supported, this method returns an empty array.
Types
BiometricsSecurityLevel
Literal Type: string
Security level of the biometric authentication to allow.
Acceptable values are: 'weak' | 'strong'
LocalAuthenticationOptions
| Name | Type | Description |
|---|---|---|
| biometricsSecurityLevel (optional) | BiometricsSecurityLevel | Only for: Android Sets the security class of biometric authentication to allow.
Default: 'weak' |
| cancelLabel (optional) | string | Allows to customize the default |
| disableDeviceFallback (optional) | boolean | After several failed attempts the system will fallback to the device passcode. This setting
allows you to disable this option and instead handle the fallback yourself. This can be
preferable in certain custom authentication workflows. This behaviour maps to using the iOS
LAPolicyDeviceOwnerAuthenticationWithBiometrics
policy rather than the LAPolicyDeviceOwnerAuthentication
policy. Defaults to |
| fallbackLabel (optional) | string | Only for: iOS Allows to customize the default |
| promptMessage (optional) | string | A message that is shown alongside the TouchID or FaceID prompt. |
| requireConfirmation (optional) | boolean | Only for: Android Sets a hint to the system for whether to require user confirmation after authentication.
This may be ignored by the system if the user has disabled implicit authentication in Settings
or if it does not apply to a particular biometric modality. Defaults to |
LocalAuthenticationResult
Type: object shaped as below:
| Name | Type | Description |
|---|---|---|
| success | true | - |
| Name | Type | Description |
|---|---|---|
| error | string | - |
| success | false | - |
| warning (optional) | string | - |
Enums
BIOMETRIC_WEAK
SecurityLevel.BIOMETRIC_WEAK ＝ 2Indicates weak biometric authentication. For example, a 2D image-based face unlock.
There are currently no weak biometric authentication options on iOS.
BIOMETRIC_STRONG
SecurityLevel.BIOMETRIC_STRONG ＝ 3Indicates strong biometric authentication. For example, a fingerprint scan or 3D face unlock.
Permissions
Android
The following permissions are added automatically through this library's AndroidManifest.xml:
| Android Permission | Description |
|---|---|
Allows an app to use device supported biometric modalities. | |
|
iOS
The following usage description keys are used by this library:
| Info.plist Key | Description |
|---|---|
| A message that tells the user why the app is requesting the ability to authenticate with Face ID. |