feat: implement biometric authentication support with configurable policies

Author: subhankarmaiti

A0Auth0.podspec

@@ -16,7 +16,7 @@ Pod::Spec.new do |s|
   s.source_files = 'ios/**/*.{h,m,mm,swift}'
   s.requires_arc = true
 
-  s.dependency 'Auth0', '2.14'
+  s.dependency 'Auth0', '2.16'
 
   install_modules_dependencies(s)
 end

EXAMPLES.md

@@ -13,6 +13,13 @@
     - [Set global headers during initialization](#set-global-headers-during-initialization)
     - [Using custom headers with Auth0Provider component](#using-custom-headers-with-auth0provider-component)
     - [Set request-specific headers](#set-request-specific-headers)
+- [Biometric Authentication](#biometric-authentication)
+  - [Biometric Policy Types](#biometric-policy-types)
+  - [Using with Auth0Provider (Hooks)](#using-with-auth0provider-hooks)
+  - [Using with Auth0 Class](#using-with-auth0-class)
+  - [Platform-Specific Behavior](#platform-specific-behavior)
+  - [Additional Configuration Options](#additional-configuration-options)
+  - [Migration from Previous Behavior](#migration-from-previous-behavior)
 - [Management API (Users)](#management-api-users)
   - [Patch user with user_metadata](#patch-user-with-user_metadata)
   - [Get full user profile](#get-full-user-profile)
@@ -253,6 +260,128 @@ auth0.auth
   .catch(console.error);
 ```
 
+## Biometric Authentication
+
+> **Platform Support:** Native only (iOS/Android)
+
+Configure biometric authentication to protect credential access. The SDK supports four biometric policies that control when biometric prompts are shown.
+
+### Biometric Policy Types
+
+- **`BiometricPolicy.default`**: System-managed behavior. Reuses the same `LAContext` on iOS, allowing the system to optimize prompt frequency. May skip the biometric prompt if authentication was recently successful.
+
+- **`BiometricPolicy.always`**: Always requires biometric authentication on every credential access. Creates a fresh `LAContext` on iOS and uses the "Always" policy on Android to ensure a new prompt is shown.
+
+- **`BiometricPolicy.session`**: Requires biometric authentication only once per session. After successful authentication, credentials can be accessed without prompting for the specified timeout duration.
+
+- **`BiometricPolicy.appLifecycle`**: Similar to session policy, but persists for the app's lifecycle. Session remains valid until the app restarts or `clearCredentials()` is called. Default timeout is 1 hour (3600 seconds).
+
+### Using with Auth0Provider (Hooks)
+
+```jsx
+import { Auth0Provider, BiometricPolicy } from 'react-native-auth0';
+
+function App() {
+  return (
+    <Auth0Provider
+      domain="YOUR_AUTH0_DOMAIN"
+      clientId="YOUR_CLIENT_ID"
+      localAuthenticationOptions={{
+        title: 'Authenticate to access credentials',
+        // Option 1: Default policy (system-managed, backward compatible)
+        biometricPolicy: BiometricPolicy.default,
+
+        // Option 2: Always require biometric authentication
+        // biometricPolicy: BiometricPolicy.always,
+
+        // Option 3: Session-based (5 minutes)
+        // biometricPolicy: BiometricPolicy.session,
+        // biometricTimeout: 300,
+
+        // Option 4: App lifecycle (1 hour)
+        // biometricPolicy: BiometricPolicy.appLifecycle,
+        // biometricTimeout: 3600,
+      }}
+    >
+      <YourApp />
+    </Auth0Provider>
+  );
+}
+```
+
+### Using with Auth0 Class
+
+```js
+import Auth0, { BiometricPolicy } from 'react-native-auth0';
+
+const auth0 = new Auth0({
+  domain: 'YOUR_AUTH0_DOMAIN',
+  clientId: 'YOUR_AUTH0_CLIENT_ID',
+  localAuthenticationOptions: {
+    title: 'Authenticate to access credentials',
+    biometricPolicy: BiometricPolicy.session,
+    biometricTimeout: 300, // 5 minutes
+  },
+});
+
+// Get credentials - will prompt for biometric authentication based on policy
+const credentials = await auth0.credentialsManager.getCredentials();
+```
+
+### Platform-Specific Behavior
+
+#### Android
+
+- `BiometricPolicy.default` and `BiometricPolicy.always` both map to the Android SDK's "Always" policy
+- Uses `BiometricPrompt` for authentication
+- Session state is stored in memory and cleared on app restart
+
+#### iOS
+
+- `BiometricPolicy.default` reuses the same `LAContext`, allowing the system to manage prompt frequency
+- `BiometricPolicy.always`, `session`, and `appLifecycle` create a fresh `LAContext` to ensure reliable prompts
+- Uses Face ID or Touch ID based on device capabilities
+- Session state is thread-safe and managed in memory
+
+### Additional Configuration Options
+
+You can combine biometric policies with other authentication options:
+
+```js
+import Auth0, {
+  BiometricPolicy,
+  LocalAuthenticationLevel,
+  LocalAuthenticationStrategy,
+} from 'react-native-auth0';
+
+const auth0 = new Auth0({
+  domain: 'YOUR_AUTH0_DOMAIN',
+  clientId: 'YOUR_AUTH0_CLIENT_ID',
+  localAuthenticationOptions: {
+    title: 'Authenticate',
+    subtitle: 'Please authenticate to continue', // Android only
+    description: 'We need to verify your identity', // Android only
+    cancelTitle: 'Cancel',
+    fallbackTitle: 'Use Passcode', // iOS only
+
+    // Biometric policy
+    biometricPolicy: BiometricPolicy.session,
+    biometricTimeout: 300,
+
+    // iOS: Choose authentication policy
+    evaluationPolicy: LocalAuthenticationStrategy.deviceOwnerWithBiometrics,
+
+    // Android: Set authentication strength
+    authenticationLevel: LocalAuthenticationLevel.strong,
+    deviceCredentialFallback: true, // Allow PIN/pattern/password fallback
+  },
+});
+```
+
+### Migration from Previous Behavior
+
+If you were not explicitly configuring biometric authentication before, the new `BiometricPolicy.default` maintains backward-compatible behavior. To enforce stricter biometric requirements, switch to `BiometricPolicy.always`.
+
 ## Management API (Users)
 
 ### Patch user with user_metadata

android/build.gradle

@@ -96,7 +96,7 @@ dependencies {
   implementation "com.facebook.react:react-android"
   implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
   implementation "androidx.browser:browser:1.2.0"
-  implementation 'com.auth0.android:auth0:3.11.0'
+  implementation 'com.auth0.android:auth0:3.12.0'
 }
 
 if (isNewArchitectureEnabled()) {

android/src/main/java/com/auth0/react/LocalAuthenticationOptionsParser.kt

@@ -1,6 +1,7 @@
 package com.auth0.react
 
 import com.auth0.android.authentication.storage.AuthenticationLevel
+import com.auth0.android.authentication.storage.BiometricPolicy
 import com.auth0.android.authentication.storage.LocalAuthenticationOptions
 import com.facebook.react.bridge.ReadableMap
 
@@ -11,16 +12,18 @@ object LocalAuthenticationOptionsParser {
     private const val CANCEL_TITLE_KEY = "cancel"
     private const val AUTHENTICATION_LEVEL_KEY = "authenticationLevel"
     private const val DEVICE_CREDENTIAL_FALLBACK_KEY = "deviceCredentialFallback"
+    private const val BIOMETRIC_POLICY_KEY = "biometricPolicy"
+    private const val BIOMETRIC_TIMEOUT_KEY = "biometricTimeout"
 
     fun fromMap(map: ReadableMap): LocalAuthenticationOptions {
         val title = map.getString(TITLE_KEY)
             ?: throw IllegalArgumentException("LocalAuthenticationOptionsParser: fromMap: The 'title' field is required")
-        
+
         val subtitle = map.getString(SUBTITLE_KEY)
         val description = map.getString(DESCRIPTION_KEY)
         val cancelTitle = map.getString(CANCEL_TITLE_KEY)
         val deviceCredentialFallback = map.getBoolean(DEVICE_CREDENTIAL_FALLBACK_KEY)
-        
+
         val builder = LocalAuthenticationOptions.Builder()
             .setTitle(title)
             .setSubTitle(subtitle)
@@ -33,9 +36,22 @@ object LocalAuthenticationOptionsParser {
             val level = getAuthenticationLevelFromInt(map.getInt(AUTHENTICATION_LEVEL_KEY))
             builder.setAuthenticationLevel(level)
         }
-        
+
         cancelTitle?.let { builder.setNegativeButtonText(it) }
-        
+
+        // Parse biometric policy
+        if (map.hasKey(BIOMETRIC_POLICY_KEY)) {
+            val policyString = map.getString(BIOMETRIC_POLICY_KEY)
+            val timeout = if (map.hasKey(BIOMETRIC_TIMEOUT_KEY)) {
+                map.getInt(BIOMETRIC_TIMEOUT_KEY)
+            } else {
+                3600 // Default 1 hour
+            }
+
+            val policy = getBiometricPolicyFromString(policyString, timeout)
+            builder.setPolicy(policy)
+        }
+
         return builder.build()
     }
 
@@ -46,5 +62,14 @@ object LocalAuthenticationOptionsParser {
             else -> AuthenticationLevel.DEVICE_CREDENTIAL
         }
     }
+
+    private fun getBiometricPolicyFromString(policy: String?, timeout: Int): BiometricPolicy {
+        return when (policy) {
+            "default", "always" -> BiometricPolicy.Always  // Map both 'default' and 'always' to Always
+            "session" -> BiometricPolicy.Session(timeout)
+            "appLifecycle" -> BiometricPolicy.AppLifecycle(timeout)
+            else -> BiometricPolicy.Always  // Default to Always
+        }
+    }
 }
 

example/ios/Podfile.lock

@@ -1,6 +1,6 @@
 PODS:
   - A0Auth0 (5.2.1):
-    - Auth0 (= 2.14)
+    - Auth0 (= 2.16)
     - boost
     - DoubleConversion
     - fast_float
@@ -28,7 +28,7 @@ PODS:
     - ReactCommon/turbomodule/core
     - SocketRocket
     - Yoga
-  - Auth0 (2.14.0):
+  - Auth0 (2.16.0):
     - JWTDecode (= 3.3.0)
     - SimpleKeychain (= 1.3.0)
   - boost (1.84.0)
@@ -2778,8 +2778,8 @@ EXTERNAL SOURCES:
     :path: "../node_modules/react-native/ReactCommon/yoga"
 
 SPEC CHECKSUMS:
-  A0Auth0: 9253099fae9372f663f89abbf5d02a6b36faf45c
-  Auth0: 022dda235af8a664a4faf9e7b60b063b5bc08373
+  A0Auth0: 936bf2484d314ca9ae7c3285bcc53ebe92b5e1cd
+  Auth0: 6db7cf0801a5201b3c6c376f07b8dfecfac21ebe
   boost: 7e761d76ca2ce687f7cc98e698152abd03a18f90
   DoubleConversion: cb417026b2400c8f53ae97020b2be961b59470cb
   fast_float: b32c788ed9c6a8c584d114d0047beda9664e7cc6

example/src/navigation/HooksDemoNavigator.tsx

@@ -1,5 +1,11 @@
 import React from 'react';
-import { Auth0Provider, useAuth0 } from 'react-native-auth0';
+import {
+  Auth0Provider,
+  useAuth0,
+  BiometricPolicy,
+  LocalAuthenticationStrategy,
+  LocalAuthenticationLevel,
+} from 'react-native-auth0';
 import AuthStackNavigator from './AuthStackNavigator';
 import MainTabNavigator from './MainTabNavigator';
 import { ActivityIndicator, View, StyleSheet } from 'react-native';
@@ -31,10 +37,45 @@ const AppContent = () => {
 /**
  * This component wraps the entire Hooks-based demo flow with the Auth0Provider,
  * making the authentication context available to all its child screens.
+ *
+ * Biometric Policy Examples:
+ * - BiometricPolicy.default: System-managed, may skip prompt if recently authenticated
+ * - BiometricPolicy.always: Always shows biometric prompt on every credential access
+ * - BiometricPolicy.session: Shows prompt once, then caches for specified timeout
+ * - BiometricPolicy.appLifecycle: Shows prompt once per app lifecycle
+ *
+ * Uncomment different policies below to test them.
  */
 const HooksDemoNavigator = () => {
   return (
-    <Auth0Provider domain={AUTH0_DOMAIN} clientId={AUTH0_CLIENT_ID}>
+    <Auth0Provider
+      domain={AUTH0_DOMAIN}
+      clientId={AUTH0_CLIENT_ID}
+      // Example: Enable biometric authentication with different policies
+      localAuthenticationOptions={{
+        title: 'Authenticate to retreive your credentials',
+        subtitle: 'Please authenticate to continue',
+        description: 'We need to authenticate you to retrieve your credentials',
+        cancelTitle: 'Cancel',
+        evaluationPolicy: LocalAuthenticationStrategy.deviceOwnerWithBiometrics,
+        fallbackTitle: 'Use Passcode',
+        authenticationLevel: LocalAuthenticationLevel.strong,
+        deviceCredentialFallback: true,
+        // Option 1: Default policy (system-managed)
+        biometricPolicy: BiometricPolicy.default,
+
+        // Option 2: Always require biometric authentication
+        // biometricPolicy: BiometricPolicy.always,
+
+        // Option 3: Session-based (5 minutes)
+        // biometricPolicy: BiometricPolicy.session,
+        // biometricTimeout: 300,
+
+        // Option 4: App lifecycle (1 hour)
+        // biometricPolicy: BiometricPolicy.appLifecycle,
+        // biometricTimeout: 3600,
+      }}
+    >
       <AppContent />
     </Auth0Provider>
   );

ios/NativeBridge.swift

@@ -61,7 +61,15 @@ public class NativeBridge: NSObject {
                 if let evaluationPolicyInt = localAuthenticationOptions["evaluationPolicy"] as? Int {
                     evaluationPolicy = convert(policyInt: evaluationPolicyInt)
                 }
-                self.credentialsManager.enableBiometrics(withTitle: title, cancelTitle: localAuthenticationOptions["cancelTitle"] as? String, fallbackTitle: localAuthenticationOptions["fallbackTitle"] as? String, evaluationPolicy: evaluationPolicy)
+
+                // Parse biometric policy
+                var biometricPolicy = BiometricPolicy.default
+                if let policyString = localAuthenticationOptions["biometricPolicy"] as? String {
+                    let timeout = localAuthenticationOptions["biometricTimeout"] as? Int ?? 3600
+                    biometricPolicy = convert(policyString: policyString, timeout: timeout)
+                }
+
+                self.credentialsManager.enableBiometrics(withTitle: title, cancelTitle: localAuthenticationOptions["cancelTitle"] as? String, fallbackTitle: localAuthenticationOptions["fallbackTitle"] as? String, evaluationPolicy: evaluationPolicy, policy: biometricPolicy)
                 resolve(true)
                 return
             } else {
@@ -384,6 +392,21 @@ public class NativeBridge: NSObject {
         }
         return LAPolicy.deviceOwnerAuthenticationWithBiometrics
     }
+
+    func convert(policyString: String, timeout: Int) -> BiometricPolicy {
+        switch policyString {
+        case "default":
+            return .default
+        case "always":
+            return .always
+        case "session":
+            return .session(timeoutInSeconds: timeout)
+        case "appLifecycle":
+            return .appLifecycle(timeoutInSeconds: timeout)
+        default:
+            return .default
+        }
+    }
 }
 
 

src/index.ts

@@ -9,11 +9,12 @@ export { TokenType } from './types/common';
 export { Auth0Provider } from './hooks/Auth0Provider';
 export { useAuth0 } from './hooks/useAuth0';
 export * from './types';
-export type {
+export {
+  BiometricPolicy,
   LocalAuthenticationLevel,
-  LocalAuthenticationOptions,
   LocalAuthenticationStrategy,
 } from './types/platform-specific';
+export type { LocalAuthenticationOptions } from './types/platform-specific';
 
 // Re-export Auth0 as default
 export { default } from './Auth0';

src/specs/NativeA0Auth0.ts

@@ -175,4 +175,12 @@ export interface LocalAuthenticationOptions {
    * Should the user be given the option to authenticate with their device PIN, pattern, or password instead of a biometric. **Applicable for Android only.**
    */
   deviceCredentialFallback: boolean | undefined;
+  /**
+   * Controls when biometric authentication prompts are shown. **Applicable for both Android and iOS.**
+   */
+  biometricPolicy: string | undefined;
+  /**
+   * Timeout in seconds for session and appLifecycle policies. Defaults to 3600 seconds (1 hour). **Applicable for both Android and iOS.**
+   */
+  biometricTimeout: Int32 | undefined;
 }