# How to Add Face ID/Biometric Login to Your Expo+Clerk App - Part 2

> Part 2 of 2. Start with [How to Add Face ID/Biometric Login to Your Expo+Clerk App](https://clerk.com/articles/how-to-add-face-id-biometric-login-to-your-expo-clerk-app.md).

Welcome to Part 2 of our guide on adding Face ID and biometric login to your Expo and Clerk application. In Part 1, we set up the project and securely stored the user's credentials. In this part, we will implement the biometric sign-in button for returning users, manage stored credentials, and explore advanced topics like passkeys, platform differences, security best practices, and troubleshooting.

### Implement biometric sign-in

Now add the biometric sign-in button for returning users. When the sign-in screen mounts, check `hasCredentials` and `biometricType`. If both are truthy, show a biometric sign-in option alongside the password form.

> **Do not gate the biometric sign-in button on `userOwnsCredentials` on the sign-in screen.** When no user is signed in, `userOwnsCredentials` is always `false` — the hook checks the current `user` object, which is `null` on the sign-in screen. Using it here would prevent the biometric button from ever appearing. Use `hasCredentials && biometricType` instead.
>
> Reserve `userOwnsCredentials` for **authenticated screens** like a settings page, where you need to verify the stored credentials belong to the currently signed-in user.

Here is the complete sign-in screen with biometric sign-in, password fallback, and error recovery for biometric enrollment changes:

```tsx
import { useState, useCallback } from 'react'
import { View, Text, TextInput, Pressable, Alert, StyleSheet } from 'react-native'
import { useSignIn } from '@clerk/expo'
import { useLocalCredentials } from '@clerk/expo/local-credentials'
import * as LocalAuthentication from 'expo-local-authentication'

export default function SignIn() {
  const { signIn, setActive, isLoaded } = useSignIn()
  const { hasCredentials, biometricType, setCredentials, clearCredentials, authenticate } =
    useLocalCredentials()

  const [email, setEmail] = useState('')
  const [password, setPassword] = useState('')
  const [error, setError] = useState('')
  const [loading, setLoading] = useState(false)

  // biometricType can be null until the hook resolves the device's biometric
  // type, so fall back to a generic label.
  const biometricLabel =
    biometricType === 'face-recognition'
      ? 'Face ID'
      : biometricType === 'fingerprint'
        ? 'fingerprint'
        : 'biometrics'

  // --- Biometric sign-in ---
  const handleBiometricSignIn = useCallback(async () => {
    setLoading(true)
    setError('')

    try {
      const result = await authenticate()

      if (result.status === 'complete') {
        await setActive({ session: result.createdSessionId })
      }
    } catch (err) {
      // Biometric enrollment may have changed (new fingerprint added,
      // Face ID reset). The password stored in expo-secure-store becomes
      // inaccessible, but hasCredentials remains true because the
      // identifier key is stored without biometric protection.
      // Clear both keys to reset state.
      await clearCredentials()
      setError(
        'Your biometric settings have changed. Please sign in with your password to re-enable biometric login.',
      )
    } finally {
      setLoading(false)
    }
  }, [authenticate, clearCredentials, setActive])

  // --- Password sign-in ---
  const handlePasswordSignIn = async () => {
    if (!isLoaded || !signIn) return
    setLoading(true)
    setError('')

    try {
      const result = await signIn.create({
        identifier: email,
        password,
      })

      if (result.status === 'complete') {
        // Check biometric availability before activating session
        const hasHardware = await LocalAuthentication.hasHardwareAsync()
        const isEnrolled = await LocalAuthentication.isEnrolledAsync()

        if (hasHardware && isEnrolled && !hasCredentials) {
          Alert.alert(
            'Enable Biometric Login',
            `Sign in faster next time with ${biometricLabel}?`,
            [
              {
                text: 'Not Now',
                style: 'cancel',
                onPress: () => setActive({ session: result.createdSessionId }),
              },
              {
                text: 'Enable',
                onPress: async () => {
                  try {
                    await setCredentials({ identifier: email, password })
                  } catch {
                    // User cancelled or biometrics unavailable
                  }
                  await setActive({ session: result.createdSessionId })
                },
              },
            ],
            { cancelable: false },
          )
        } else {
          await setActive({ session: result.createdSessionId })
        }
      }
    } catch (err: any) {
      setError(err.errors?.[0]?.message || 'Sign-in failed. Check your credentials.')
    } finally {
      setLoading(false)
    }
  }

  return (
    <View style={styles.container}>
      <Text style={styles.title}>Sign In</Text>

      {error ? <Text style={styles.error}>{error}</Text> : null}

      {/* Biometric sign-in button — shown for returning users */}
      {hasCredentials && biometricType ? (
        <Pressable
          style={[styles.biometricButton, loading && styles.buttonDisabled]}
          onPress={handleBiometricSignIn}
          disabled={loading}
        >
          <Text style={styles.biometricButtonText}>Sign in with {biometricLabel}</Text>
        </Pressable>
      ) : null}

      {hasCredentials && biometricType ? (
        <Text style={styles.divider}>or sign in with password</Text>
      ) : null}

      <TextInput
        style={styles.input}
        placeholder="Email"
        value={email}
        onChangeText={setEmail}
        autoCapitalize="none"
        keyboardType="email-address"
      />

      <TextInput
        style={styles.input}
        placeholder="Password"
        value={password}
        onChangeText={setPassword}
        secureTextEntry
      />

      <Pressable
        style={[styles.button, loading && styles.buttonDisabled]}
        onPress={handlePasswordSignIn}
        disabled={loading}
      >
        <Text style={styles.buttonText}>{loading ? 'Signing in...' : 'Sign In with Password'}</Text>
      </Pressable>
    </View>
  )
}

const styles = StyleSheet.create({
  container: { flex: 1, justifyContent: 'center', padding: 24 },
  title: {
    fontSize: 28,
    fontWeight: 'bold',
    marginBottom: 24,
    textAlign: 'center',
  },
  error: { color: '#ef4444', marginBottom: 12, textAlign: 'center' },
  biometricButton: {
    backgroundColor: '#1d4ed8',
    borderRadius: 8,
    padding: 16,
    alignItems: 'center',
    marginBottom: 8,
  },
  biometricButtonText: { color: '#fff', fontSize: 16, fontWeight: '600' },
  divider: {
    textAlign: 'center',
    color: '#9ca3af',
    marginVertical: 16,
    fontSize: 14,
  },
  input: {
    borderWidth: 1,
    borderColor: '#d1d5db',
    borderRadius: 8,
    padding: 14,
    marginBottom: 12,
    fontSize: 16,
  },
  button: {
    backgroundColor: '#6c47ff',
    borderRadius: 8,
    padding: 14,
    alignItems: 'center',
    marginTop: 4,
  },
  buttonDisabled: { opacity: 0.6 },
  buttonText: { color: '#fff', fontSize: 16, fontWeight: '600' },
})
```

Key implementation details:

- **`authenticate()` throws on biometric enrollment changes.** When a user adds a new fingerprint or resets Face ID, the biometric-protected password becomes inaccessible. The `authenticate()` function detects the missing password and throws an error. The `catch` block calls `clearCredentials()` to clean up the orphaned identifier key, then shows the password form.
- **`hasCredentials` persists after enrollment changes.** The identifier and password are stored under separate keys. The identifier is stored without biometric protection, so `hasCredentials` remains `true` even when the password is invalidated. Without the `clearCredentials()` call in the catch block, the app would enter an infinite loop: biometric button appears → `authenticate()` throws → biometric button still appears.
- **Password form is always available.** Biometrics are a convenience layer, not a replacement for password sign-in. The password form is shown below the biometric button so users always have a fallback.

### Manage stored credentials

Create a biometric settings component for the authenticated area. This component lets signed-in users enable or disable biometric login.

> **Sign-out behavior:** Clerk does **not** automatically clear local credentials when `signOut()` is called. This is intentional — credentials persist so the user can use biometric sign-in on their next visit without re-entering their password. Do **not** call `clearCredentials()` in your sign-out handler.
>
> **Where to use `userOwnsCredentials` vs `hasCredentials`:**
>
> - **Sign-in screen (unauthenticated):** Use `hasCredentials` + `biometricType` to gate the biometric button. `userOwnsCredentials` is always `false` here.
> - **Settings screen (authenticated):** Use `userOwnsCredentials` to verify the stored credentials belong to the current user before allowing management operations.
>
> Expose `clearCredentials()` as an explicit user action in a settings screen, not as an automatic side effect of sign-out.

```tsx
import { useState } from 'react'
import {
  View,
  Text,
  TextInput,
  Switch,
  Pressable,
  Modal,
  Alert,
  StyleSheet,
  KeyboardAvoidingView,
  Platform,
} from 'react-native'
import { useUser } from '@clerk/expo'
import { useLocalCredentials } from '@clerk/expo/local-credentials'

export default function BiometricSettings() {
  const { user } = useUser()
  const { hasCredentials, userOwnsCredentials, biometricType, setCredentials, clearCredentials } =
    useLocalCredentials()

  const [loading, setLoading] = useState(false)
  const [showPasswordModal, setShowPasswordModal] = useState(false)
  const [password, setPassword] = useState('')

  if (!biometricType) {
    return (
      <View style={styles.container}>
        <Text style={styles.label}>Biometric login is not available on this device.</Text>
      </View>
    )
  }

  const biometricLabel = biometricType === 'face-recognition' ? 'Face ID' : 'Fingerprint'

  // Stored credentials belong to a different user
  if (hasCredentials && !userOwnsCredentials) {
    return (
      <View style={styles.container}>
        <Text style={styles.label}>
          Biometric login is configured for a different account on this device.
        </Text>
        <Pressable
          style={styles.clearButton}
          onPress={async () => {
            await clearCredentials()
          }}
        >
          <Text style={styles.clearButtonText}>Remove and set up for this account</Text>
        </Pressable>
      </View>
    )
  }

  const handleToggle = async (enabled: boolean) => {
    if (enabled) {
      setPassword('')
      setShowPasswordModal(true)
    } else {
      setLoading(true)
      try {
        await clearCredentials()
      } catch {
        Alert.alert('Error', 'Could not disable biometric login.')
      } finally {
        setLoading(false)
      }
    }
  }

  const handleSubmitPassword = async () => {
    if (!password) return

    setShowPasswordModal(false)
    setLoading(true)
    try {
      await setCredentials({
        identifier: user?.primaryEmailAddress?.emailAddress || '',
        password,
      })
    } catch {
      Alert.alert('Error', 'Could not enable biometric login. Verify your biometric settings.')
    } finally {
      setPassword('')
      setLoading(false)
    }
  }

  const handleCancelModal = () => {
    setPassword('')
    setShowPasswordModal(false)
  }

  return (
    <View style={styles.container}>
      <View style={styles.row}>
        <Text style={styles.label}>Sign in with {biometricLabel}</Text>
        <Switch value={userOwnsCredentials} onValueChange={handleToggle} disabled={loading} />
      </View>
      <Text style={styles.description}>
        {userOwnsCredentials
          ? `${biometricLabel} login is enabled. You can sign in without typing your password.`
          : `Enable ${biometricLabel} to sign in faster on this device.`}
      </Text>

      <Modal
        visible={showPasswordModal}
        transparent
        animationType="fade"
        onRequestClose={handleCancelModal}
      >
        <KeyboardAvoidingView
          behavior={Platform.OS === 'ios' ? 'padding' : 'height'}
          style={styles.modalOverlay}
        >
          <View style={styles.modalContent}>
            <Text style={styles.modalTitle}>Enable Biometric Login</Text>
            <Text style={styles.modalMessage}>
              Enter your password to enable {biometricLabel} login:
            </Text>
            <TextInput
              style={styles.modalInput}
              placeholder="Password"
              secureTextEntry
              autoFocus
              value={password}
              onChangeText={setPassword}
              onSubmitEditing={handleSubmitPassword}
            />
            <View style={styles.modalButtons}>
              <Pressable style={styles.modalButton} onPress={handleCancelModal}>
                <Text style={styles.modalCancelText}>Cancel</Text>
              </Pressable>
              <Pressable
                style={[
                  styles.modalButton,
                  styles.modalSubmitButton,
                  !password && styles.modalSubmitButtonDisabled,
                ]}
                onPress={handleSubmitPassword}
                disabled={!password}
              >
                <Text style={styles.modalSubmitText}>Enable</Text>
              </Pressable>
            </View>
          </View>
        </KeyboardAvoidingView>
      </Modal>
    </View>
  )
}

const styles = StyleSheet.create({
  container: { padding: 16 },
  row: {
    flexDirection: 'row',
    justifyContent: 'space-between',
    alignItems: 'center',
    marginBottom: 8,
  },
  label: { fontSize: 16, fontWeight: '500' },
  description: { fontSize: 14, color: '#6b7280' },
  clearButton: {
    marginTop: 12,
    padding: 12,
    backgroundColor: '#fee2e2',
    borderRadius: 8,
    alignItems: 'center',
  },
  clearButtonText: { color: '#dc2626', fontWeight: '500' },
  modalOverlay: {
    flex: 1,
    backgroundColor: 'rgba(0, 0, 0, 0.5)',
    justifyContent: 'center',
    alignItems: 'center',
  },
  modalContent: {
    backgroundColor: '#fff',
    borderRadius: 14,
    padding: 24,
    width: '85%',
    maxWidth: 340,
  },
  modalTitle: {
    fontSize: 17,
    fontWeight: '600',
    textAlign: 'center',
  },
  modalMessage: {
    fontSize: 14,
    color: '#6b7280',
    textAlign: 'center',
    marginTop: 8,
    marginBottom: 16,
  },
  modalInput: {
    borderWidth: 1,
    borderColor: '#d1d5db',
    borderRadius: 8,
    padding: 14,
    fontSize: 16,
  },
  modalButtons: {
    flexDirection: 'row',
    marginTop: 16,
    gap: 12,
  },
  modalButton: {
    flex: 1,
    paddingVertical: 12,
    borderRadius: 8,
    alignItems: 'center',
  },
  modalCancelText: { fontSize: 16, color: '#6c47ff' },
  modalSubmitButton: { backgroundColor: '#6c47ff' },
  modalSubmitButtonDisabled: { opacity: 0.5 },
  modalSubmitText: { fontSize: 16, color: '#fff', fontWeight: '600' },
})
```

This settings component uses `userOwnsCredentials` to gate the toggle — unlike the sign-in screen, this is an authenticated context where the hook can verify credential ownership. The multi-user check (`hasCredentials && !userOwnsCredentials`) handles shared-device scenarios where one user's credentials are stored but a different user is signed in.

The password prompt uses a custom `Modal` with a `TextInput` (`secureTextEntry`) instead of `Alert.prompt`, which is iOS-only. The `Modal` approach works identically on both iOS and Android. `KeyboardAvoidingView` prevents the keyboard from covering the input, using `behavior="padding"` on iOS and `behavior="height"` on Android. The `onRequestClose` prop handles the Android hardware back button.

## Adding passkey support with Clerk

> Passkeys in Expo are provided by the [`@clerk/expo-passkeys`](https://github.com/clerk/javascript/tree/main/packages/expo-passkeys) package. This section is a conceptual overview of the architecture and API; for complete, copy-paste setup and the authoritative list of supported Expo SDK versions, follow Clerk's [Expo passkeys guide](https://clerk.com/docs/reference/expo/passkeys.md).

Passkeys are an alternative to password-based biometric login. Instead of storing a password locally, passkeys use asymmetric cryptography — no password is ever created or transmitted.

### How passkeys work in Clerk's Expo SDK

Install the `@clerk/expo-passkeys` package. It ships the native module and registers as an optional peer dependency of `@clerk/expo`:

```bash
npx expo install @clerk/expo-passkeys
```

Import the `passkeys` object from the `@clerk/expo/passkeys` subpath and pass it to your `ClerkProvider`:

```tsx
import { passkeys } from '@clerk/expo/passkeys'
;<ClerkProvider
  publishableKey={publishableKey}
  tokenCache={tokenCache}
  __experimental_passkeys={passkeys}
>
  {/* App content */}
</ClerkProvider>
```

iOS passkeys require an Apple Developer account with associated domains (`webcredentials`) configured. Android passkeys require a physical device — emulators do not reliably support the Credential Manager API. Both platforms require a development build.

### Passkey API overview

Registration creates a new passkey bound to the user's account:

```tsx
// Registration — requires an authenticated user
// Requires @clerk/expo-passkeys and a development build
const { isLoaded, isSignedIn, user } = useUser()

if (!isLoaded || !isSignedIn) return

try {
  await user.createPasskey()
  // Passkey registered and bound to the user's account
} catch (err) {
  // User cancelled or platform error
}
```

Authentication uses the passkey to sign in without a password:

```tsx
// Authentication — from the sign-in screen
// Requires @clerk/expo-passkeys and a development build
const { isLoaded, signIn } = useSignIn()

if (!isLoaded || !signIn) return

try {
  await signIn.passkey({ flow: 'discoverable' })

  // signIn.passkey() updates the sign-in in place. Read its status, then
  // finalize to activate the session and route the user.
  if (signIn.status === 'complete') {
    await signIn.finalize({
      navigate: async ({ session }) => {
        // Navigate to your protected route now that the session is active
      },
    })
  }
} catch (err) {
  // User cancelled or no passkey registered
}
```

Each Clerk account supports up to 10 passkeys. Passkeys can be renamed with `passkey.update({ name })` or deleted with `passkey.delete()`.

### Full setup and further reading

For complete step-by-step configuration — associated domains, `app.json` plugins, and the registration and sign-in screens — follow Clerk's [Expo passkeys reference](https://clerk.com/docs/reference/expo/passkeys.md) and the [custom passkey flow guide](https://clerk.com/docs/guides/development/custom-flows/authentication/passkeys.md). Clerk's native `AuthView` component (beta, introduced in Core 3) may also streamline passkey sign-in in future releases; monitor the [Clerk changelog](https://clerk.com/changelog.md) for updates.

## Handling platform differences

### iOS-specific considerations

**Face ID vs. Touch ID detection:** The `biometricType` value from `useLocalCredentials()` returns `'face-recognition'` for Face ID and `'fingerprint'` for Touch ID. Use this to show the appropriate label in your UI.

**`NSFaceIDUsageDescription` is mandatory.** If this key is missing from `Info.plist`, the app crashes when requesting Face ID access, and Apple rejects the App Store submission. Write a clear, specific string: "Allow [App Name] to use Face ID for quick sign-in to your account."

**Simulator testing:** In the iOS Simulator, go to **Features → Face ID → Enrolled** to enable Face ID. Simulate scans with:

- **Matching Face** (keyboard shortcut: Cmd+Opt+M) — successful authentication
- **Non-matching Face** (keyboard shortcut: Cmd+Opt+N) — failed authentication

**Max attempt fallback:** After five failed biometric attempts, iOS automatically falls back to the device passcode. This is OS-level behavior that cannot be overridden by the app.

### Android-specific considerations

**Biometric strength classes:** Android categorizes biometrics into three classes:

- **Class 3 (BIOMETRIC\_STRONG)** — fingerprint, some face recognition (secure hardware required)
- **Class 2 (BIOMETRIC\_WEAK)** — some face recognition (software-based)
- **Class 1** — convenience only, not suitable for authentication

`expo-secure-store` with `requireAuthentication: true` requires **Class 3 (BIOMETRIC\_STRONG)** biometrics. This means Android face unlock on many devices — including some Samsung Galaxy models — will not work with credential storage because their face recognition is Class 2. Fingerprint always works.

> **Known Samsung issue:** On Samsung Galaxy devices running Android 14, `expo-secure-store` with `requireAuthentication` throws `ERR_SECURESTORE_AUTH_NOT_CONFIGURED` when only face recognition is enrolled (no fingerprint). If your users report this issue, inform them that fingerprint enrollment is required for biometric login on affected devices.

**`cancelLabel` requirement:** When using `authenticateAsync()` from `expo-local-authentication` with `disableDeviceFallback: true`, you **must** provide a `cancelLabel` or Android crashes. This is a known platform issue.

**Data persistence:** Android deletes `expo-secure-store` data when the app is uninstalled. iOS Keychain data persists across uninstalls. This means an iOS user may see a biometric login option after reinstalling, while an Android user will need to re-enroll.

### [Cross-platform](https://clerk.com/glossary.md#cross-platform-development) biometric label utility

Use this utility to display the appropriate biometric label and icon across platforms:

```tsx
import { Platform } from 'react-native'
import * as LocalAuthentication from 'expo-local-authentication'

type BiometricInfo = {
  available: boolean
  label: string
  type: 'face-recognition' | 'fingerprint' | 'iris' | 'none'
}

export async function getBiometricInfo(): Promise<BiometricInfo> {
  const hasHardware = await LocalAuthentication.hasHardwareAsync()
  const isEnrolled = await LocalAuthentication.isEnrolledAsync()

  if (!hasHardware || !isEnrolled) {
    return { available: false, label: 'Biometrics', type: 'none' }
  }

  const types = await LocalAuthentication.supportedAuthenticationTypesAsync()

  if (types.includes(LocalAuthentication.AuthenticationType.FACIAL_RECOGNITION)) {
    return {
      available: true,
      label: Platform.OS === 'ios' ? 'Face ID' : 'Face Unlock',
      type: 'face-recognition',
    }
  }

  if (types.includes(LocalAuthentication.AuthenticationType.FINGERPRINT)) {
    return {
      available: true,
      label: Platform.OS === 'ios' ? 'Touch ID' : 'Fingerprint',
      type: 'fingerprint',
    }
  }

  if (types.includes(LocalAuthentication.AuthenticationType.IRIS)) {
    return { available: true, label: 'Iris Scan', type: 'iris' }
  }

  return { available: false, label: 'Biometrics', type: 'none' }
}
```

## Comparing authentication providers for biometric login

Clerk is not the only authentication provider for Expo apps. Here is how the major providers compare for biometric login support.

### Clerk

Clerk provides first-class biometric support through the [`useLocalCredentials()`](https://clerk.com/docs/guides/development/local-credentials.md) hook — a single import that handles credential storage, biometric verification, and sign-in. Passkey support is available through `@clerk/expo-passkeys` on current Expo SDKs (53 through 56). No custom native bridging is required.

### Auth0

Auth0's `react-native-auth0` SDK (v5+) includes built-in biometric credential management through `LocalAuthenticationOptions` on the `Auth0Provider`. It offers four `BiometricPolicy` modes: `default`, `always`, `session`, and `appLifecycle`. Passkeys are in Early Access for native iOS and Android but are not explicitly supported in the React Native SDK. Passkeys require a custom domain.

### Stytch

Stytch offers first-class `biometrics.register()` and `biometrics.authenticate()` methods in their React Native SDK, plus WebAuthn passkey support via `webauthn.register()` and `webauthn.authenticate()`. A dedicated Expo SDK is available (`@stytch/react-native-expo`). Stytch requires iOS 13+ and Android 6+ (Class 3 biometrics only).

### Firebase

Firebase has no dedicated biometric or passkey API. Biometric login must be implemented manually by wrapping Firebase session tokens with `expo-local-authentication` and `expo-secure-store`. A passkey feature request has been [open since July 2023](https://github.com/firebase/firebase-ios-sdk/issues/11548) with no implementation.

### Supabase

Supabase has no native biometric or passkey API. The same manual approach as Firebase is required — biometrics as a client-side gate over session tokens. Supabase uses `AsyncStorage` by default, which is unencrypted and unsuitable for credential storage. Passkey support has [126+ upvotes](https://github.com/orgs/supabase/discussions/8677) and was reported as "being planned" as of January 2026.

### AWS Cognito

AWS Amplify's React Native SDK supports TOTP and SMS [MFA](https://clerk.com/glossary.md#multi-factor-authentication-mfa), but the official docs state: "WebAuthn registration and authentication are not currently supported on React Native." Biometric gating requires manual implementation with `expo-local-authentication`.

### Provider comparison

| Feature                |     Clerk    |     Auth0    | Stytch |  Firebase  |  Supabase  | AWS Cognito |
| ---------------------- | :----------: | :----------: | :----: | :--------: | :--------: | :---------: |
| Built-in biometric API |      Yes     |      Yes     |   Yes  |     No     |     No     |      No     |
| Passkey support (RN)   | Experimental | Early Access |   Yes  |     No     |     No     |      No     |
| Expo SDK               |      Yes     |      Yes     |   Yes  |  Community |     Yes    |     Yes     |
| Setup complexity       |      Low     |    Medium    | Medium | High (DIY) | High (DIY) |  High (DIY) |
| Dev build required     |      Yes     |      Yes     |   Yes  |     Yes    |     No     |      No     |

## Security best practices

### Secure credential storage

Clerk's `useLocalCredentials()` stores credentials in `expo-secure-store`, which uses the iOS Keychain and Android EncryptedSharedPreferences backed by the hardware Keystore. Never store credentials in `AsyncStorage` — it is [unencrypted and accessible without authentication](https://reactnative.dev/docs/security).

Clerk's approach uses the platform's cryptographic binding, not a simple boolean gate. The [OWASP Mobile Application Security Testing Guide (MASTG)](https://mas.owasp.org/MASTG/) warns that "event-bound" biometric checks (a boolean true/false from `authenticateAsync`) are bypassable. By storing the password behind `requireAuthentication: true` in `expo-secure-store`, the credential is cryptographically tied to a successful biometric verification — the operating system enforces this at the hardware level.

### Handling biometric enrollment changes

When a user adds a new fingerprint or resets Face ID, credentials stored with biometric protection become inaccessible:

- **iOS:** The Keychain item protected with `biometryCurrentSet` is silently invalidated when biometric enrollment changes. `SecItemCopyMatching` returns `errSecItemNotFound`, and `expo-secure-store` returns `null`.
- **Android:** The Android Keystore throws `KeyPermanentlyInvalidatedException` internally. `expo-secure-store` catches this in `getItemImpl` and returns `null`.

At the Clerk API level, `authenticate()` detects the missing password and **throws an error** rather than returning `null`. Your code must use **try/catch** (not null-checks), call `clearCredentials()` to clean up, prompt for password sign-in, and then call `setCredentials()` to re-store credentials under the new biometric enrollment. See the [complete sign-in screen code](#implement-biometric-sign-in) for the full implementation pattern.

### Fallback authentication

Always provide a password sign-in fallback. Biometrics can be unavailable for many reasons:

- No biometric hardware on the device
- Biometrics not enrolled in device settings
- User denied Face ID permission (iOS)
- Biometric enrollment changed (credentials invalidated)
- Hardware damage

Show the password form by default, with biometric sign-in as the enhanced option — not the only option.

### Data persistence asymmetry

- **iOS:** Keychain data persists after app uninstall. A returning user may see the biometric login option after reinstalling.
- **Android:** EncryptedSharedPreferences data is deleted on app uninstall. The user must re-enroll biometric login after reinstalling.

Handle both cases gracefully. On iOS, if `hasCredentials` is `true` but the stored password no longer matches the user's current password (they changed it), `authenticate()` will throw a Clerk API error. Catch it, clear credentials, and prompt for password sign-in.

## Troubleshooting common issues

### "FaceID is available but has not been configured"

**Cause:** Running in Expo Go instead of a development build, or the `NSFaceIDUsageDescription` key is missing from `Info.plist`.

**Fix:** Create a development build with `npx expo run:ios`. Verify that the `expo-local-authentication` plugin is in `app.json` with a `faceIDPermission` string.

### Biometric prompt not appearing

**Causes:**

1. Biometrics not enrolled in device or simulator settings
2. `NSFaceIDUsageDescription` missing from config
3. User previously denied Face ID permission — `hasHardwareAsync()` returns `false` after denial on iOS
4. Proguard optimization in Android production builds can break the biometric prompt

**Fix:** Check enrollment (simulator: Features → Face ID → Enrolled). Verify plugin config. For iOS permission denial, the user must re-enable in device Settings. For Android production builds, add Proguard keep rules for `androidx.biometric`.

### Credentials not persisting across app restarts

**Causes:**

1. `expo-secure-store` not properly installed — run `npx expo install expo-secure-store` and rebuild
2. Android: data deleted on app uninstall (this is expected behavior, not a bug)
3. Biometric enrollment changed, invalidating stored credentials

**Fix:** Verify installation, rebuild with `npx expo run:ios` or `npx expo run:android`. Handle invalidation gracefully with the try/catch pattern shown in the [biometric sign-in section](#implement-biometric-sign-in).

### Android crash with disableDeviceFallback

**Cause:** When using `authenticateAsync({ disableDeviceFallback: true })` from `expo-local-authentication`, Android requires a `cancelLabel` string. Omitting it causes a crash.

**Fix:** Always provide `cancelLabel` when disabling the device fallback:

```tsx
await LocalAuthentication.authenticateAsync({
  disableDeviceFallback: true,
  cancelLabel: 'Cancel',
  promptMessage: 'Verify your identity',
})
```

### Samsung face recognition not working with SecureStore

**Cause:** Samsung face recognition is classified as BIOMETRIC\_WEAK (Class 2). `expo-secure-store` with `requireAuthentication: true` requires BIOMETRIC\_STRONG (Class 3).

**Fix:** Inform users that fingerprint enrollment is required for biometric login on affected Samsung devices. You can detect this by checking if `authenticateAsync` succeeds but `setCredentials` fails.

### Android emulator fingerprint enrollment

To enroll fingerprints in the Android emulator:

1. Open the emulator's **Settings → Security → Fingerprint**
2. Follow the enrollment flow (use the extended controls fingerprint button)
3. Alternatively, use ADB: `adb -e emu finger touch 1`

Note that passkeys do **not** work in the Android emulator — a physical device is required.

## Conclusion

In this part, we completed the biometric login implementation by adding the sign-in button for returning users and providing a settings interface to manage stored credentials. We also explored passkey support, platform-specific considerations, and security best practices to ensure a robust and user-friendly authentication experience.

## Frequently asked questions

## FAQ

### Can I use both biometric login and passkeys in the same app?

Yes — they're complementary. Offer passkeys as the primary passwordless method and `useLocalCredentials` biometric login as a convenience for password users. `@clerk/expo-passkeys` supports Expo SDK 53 through 56 and requires a development build.

### What happens if a user's biometric enrollment changes?

When a user adds a new fingerprint or resets Face ID, the stored credentials become inaccessible. The app should catch this error, clear the stored credentials, and prompt the user to sign in with their password to re-enable biometric login.

## In this series

1. [How to Add Face ID/Biometric Login to Your Expo+Clerk App](https://clerk.com/articles/how-to-add-face-id-biometric-login-to-your-expo-clerk-app.md)
2. **How to Add Face ID/Biometric Login to Your Expo+Clerk App - Part 2** (you are here)