Biometric Authentication

Starting in Mobile SDK 11.0, you can configure your app to use the device system biometric authentication to log in. For example, when the app exceeds its timeout period in the background, the login screen appears upon the user’s return to the app. This behavior gives the appearance that the user is logged out, even if the user’s login session hasn’t expired. The user can then log in using their username and password or their device’s biometric authentication if they enabled that option.

Alternatively, you can configure your app to require a passcode after login to achieve a similar effect. This feature is presented as a lock screen, while the biometric authentication introduced in Mobile SDK 11.0 presents a login screen. See also:

To configure biometric authentication, go to your org’s external client app or connected app.

  1. Add a custom attribute to your external client app or connected app with the key ENABLE_BIOMETRIC_AUTHENTICATION.
  2. To change the timeout period, add the BIOMETRIC_AUTHENTICATION_TIMEOUT key. You can adjust its value to the number of minutes that you want the app to be backgrounded for before it locks. If you choose not to add this key, the default value is set for 15 minutes.

In an external client app, enter each custom attribute value in double quotes. Setup validation rejects a value that isn’t quoted.

The user’s authentication token doesn’t refresh while the app is locked. We recommend that admins enable a session timeout in the external client app or connected app and set the Lock App After attribute to the same value.

To manage biometric opt-in from within the app, use SalesforceSDKManager to get the BiometricAuthenticationManager instance. You can use this instance to:

  • Check whether the user has opted in to biometric authentication.
  • Prompt the user to opt in or out of biometric authentication and update the SDK with their response.
  • Check whether the app is locked.
  • Lock the app immediately.
  • Disable the native biometric unlock button entirely.

To opt the user in to biometric authentication, you can use the Mobile SDK-provided prompts or create your own.

Starting in Mobile SDK 14.0, automaticPresentation on BiometricAuthenticationManager handles two flows on iOS and Android.

  1. After a successful login, if the user hasn’t opted in to biometric authentication, Mobile SDK presents the opt-in dialog.
  2. When the app locks after the timeout, if the user has opted in, Mobile SDK presents the native biometric prompt.

automaticPresentation defaults to true. The value isn’t saved. It returns to true when the app process restarts.

To turn automatic presentation off, set the property to false before login.

iOS (Swift)

Android (Kotlin)

Leave automaticPresentation at its default, and Mobile SDK presents the opt-in dialog after login and the biometric prompt when the app locks.

When automaticPresentation is false, call presentOptInDialog after login.

On Android, presentOptInDialog() takes no arguments. Mobile SDK shows the dialog on its own screen. Mobile SDK 14.0 removes the FragmentManager parameter that this method took in Mobile SDK 13.x.

Android (Kotlin)

iOS (Swift)

When automatic presentation is off and the user has opted in, the native button on the login screen still starts the biometric prompt.

If you choose to create a custom prompt, implement one of these lines to pass the user’s response to Mobile SDK.

Android (Kotlin)

iOS (Swift)

If the user enables biometric authentication, a native button is added to the login screen so that they can trigger the OS prompt.

To create a custom button within the app’s web view, you can use an API found in BiometricAuthenticationManager to disable the native button. Then, configure the button to redirect to mobilesdk://biometric/authentication/prompt. Mobile SDK automatically ignores this redirect and presents the native OS prompt.