Get Started
Strategies
Integrate
Customize
Webhooks
Client App SDKs
Deploy on your Cloud
Security Concerns
Biometric login
Overview
Authgear supports enabling biometric login in the native mobile application. To set this up, you will need to
- 1.Enable biometric login in your application.
- 2.Sign up or log in a user in your mobile application, use the mobile SDK to enable biometric login.
Enable biometric login in your application
Portal
authgear.yaml
- 1.In the portal, go to "Biometric Authentication".
- 2.Turn on "Enable biometric authentication".
- 3.Click "Save".
1
authentication:
2
identities:
3
...
4
# Add biometric along with the other enabled identities
5
- biometric
6
identity:
7
biometric:
8
# Enable listing biometric login in user setting page, default false
9
list_enabled: true
Copied!
Enable biometric login in mobile SDK
In the following section, we will show you how to use biometric login in the SDK. In the SDK code snippet,
authgear is referring to the configured Authgear container.- Check if the current device supports biometric login before calling any biometric API.
iOS
Android
React Native
Flutter
1
// check if current device supports biometric login
2
var supported = false
3
do {
4
try authgear.checkBiometricSupported()
5
supported = true
6
} catch {}
7
​
8
if supported {
9
// biometric login is supported
10
}
Copied!
1
boolean supported = false;
2
try {
3
// biometric login is supported SDK_INT >= 23 (Marshmallow)
4
if (Build.VERSION.SDK_INT >= 23) {
5
// check if current device supports biometric login
6
authgear.checkBiometricSupported(
7
this.getApplication(),
8
ALLOWED
9
);
10
supported = true;
11
}
12
} catch (Exception e) {}
13
if (supported) {
14
// biometric login is supported
15
}
Copied!
1
// We will need the options for the other biometric api
2
const biometricOptions = {
3
ios: {
4
localizedReason: 'Use biometric to authenticate',
5
constraint: 'biometryCurrentSet' as const,
6
},
7
android: {
8
title: 'Biometric Authentication',
9
subtitle: 'Biometric authentication',
10
description: 'Use biometric to authenticate',
11
negativeButtonText: 'Cancel',
12
constraint: ['BIOMETRIC_STRONG' as const],
13
invalidatedByBiometricEnrollment: true,
14
},
15
};
16
// check if current device supports biometric login
17
authgear
18
.checkBiometricSupported(biometricOptions)
19
.then(() => {
20
// biometric login is supported
21
})
22
.catch(() => {
23
// biometric login is not supported
24
});
Copied!
1
// We will need the options for the other biometric api
2
final ios = BiometricOptionsIOS(
3
localizedReason: "Use biometric to authenticate",
4
constraint: BiometricAccessConstraintIOS.biometryAny,
5
);
6
final android = BiometricOptionsAndroid(
7
title: "Biometric Authentication",
8
subtitle: "Biometric authentication",
9
description: "Use biometric to authenticate",
10
negativeButtonText: "Cancel",
11
constraint: [BiometricAccessConstraintAndroid.biometricStrong],
12
invalidatedByBiometricEnrollment: false,
13
);
14
​
15
try {
16
// check if current device supports biometric login
17
await authgear.checkBiometricSupported(ios: ios, android: android);
18
// biometric login is supported
19
} catch (e) {
20
// biometric login is not supported
21
}
Copied!
- Enable biometric login for logged in user
iOS
Android
React Native
Flutter
1
// provide localizedReason for requesting authentication
2
// which displays in the authentication dialog presented to the user
3
authgear.enableBiometric(
4
localizedReason: "REPLACE_WITH_LOCALIZED_REASON",
5
constraint: .biometryCurrentSet
6
) { result in
7
if case let .failure(error) = result {
8
// failed to enable biometric with error
9
} else {
10
// enabled biometric successfully
11
}
12
}
Copied!
1
// We will need the options for the other biometric api
2
BiometricOptions biometricOptions = new BiometricOptions(
3
activity, // FragmentActivity
4
"Biometric authentication", // title
5
"Biometric authentication", // subtitle
6
"Use biometric to authenticate", // description
7
"Cancel", // negativeButtonText
8
ALLOWED, // allowedAuthenticators
9
true // invalidatedByBiometricEnrollment
10
);
11
authgear.enableBiometric(
12
biometricOptions,
13
new OnEnableBiometricListener() {
14
@Override
15
public void onEnabled() {
16
// enabled biometric login successfully
17
}
18
​
19
@Override
20
public void onFailed(Throwable throwable) {
21
// failed to enable biometric with error
22
}
23
}
24
);
Copied!
1
authgear
2
.enableBiometric(biometricOptions)
3
.then(() => {
4
// enabled biometric login successfully
5
})
6
.catch((err) => {
7
// failed to enable biometric with error
8
});
Copied!
1
try {
2
await authgear.enableBiometric(ios: ios, android: android);
3
// enabled biometric login successfully
4
} catch (e) {
5
// failed to enable biometric with error
6
}
Copied!
- Check if the current device enabled biometric login, we should check this before asking the user to log in with biometric credentials
iOS
Android
React Native
Flutter
1
var enabled = (try? authgear.isBiometricEnabled()) ?? false
Copied!
1
boolean enabled = false;
2
try {
3
enabled = authgear.isBiometricEnabled();
4
} catch (Exception e) {}
Copied!
1
authgear
2
.isBiometricEnabled()
3
.then((enabled) => {
4
// show if biometric login is enabled
5
})
6
.catch(() => {
7
// failed to check the enabled status
8
});
Copied!
1
try {
2
final enabled = await authgear.isBiometricEnabled();
3
// show if biometric login is enabled
4
} catch (e) {
5
// failed to check the enabled status
6
}
Copied!
- Login with biometric credentials
iOS
Android
React Native
Flutter
1
authgear.authenticateBiometric { result in
2
switch result {
3
case let .success(authResult):
4
let userInfo = authResult.userInfo
5
// logged in successfully
6
case let .failure(error):
7
// failed to login
8
}
9
}
Copied!
1
authgear.authenticateBiometric(
2
biometricOptions,
3
new OnAuthenticateBiometricListener() {
4
@Override
5
public void onAuthenticated(UserInfo userInfo) {
6
// logged in successfully
7
}
8
​
9
@Override
10
public void onAuthenticationFailed(Throwable throwable) {
11
// failed to login
12
}
13
}
14
);
Copied!
1
authgear
2
.authenticateBiometric(biometricOptions)
3
.then(({userInfo}) => {
4
// logged in successfully
5
})
6
.catch((e) => {
7
// failed to login
8
});
Copied!
1
try {
2
final userInfo = await authgear.authenticateBiometric(ios: ios, android: android);
3
// logged in successfully
4
} catch (e) {
5
// failed to login
6
}
Copied!
- Disable biometric login in the current device
iOS
Android
React Native
Flutter
1
do {
2
try authgear.disableBiometric()
3
// disabled biometric login successfully
4
} catch {
5
// failed to disable biometric login
6
}
Copied!
1
try {
2
authgear.disableBiometric();
3
// disabled biometric login successfully
4
} catch (Exception e) {
5
// failed to disable biometric login
6
}
Copied!
1
authgear
2
.disableBiometric()
3
.then(() => {
4
// disabled biometric login successfully
5
})
6
.catch((err) => {
7
// failed to disable biometric login
8
});
Copied!
1
try {
2
await authgear.disableBiometric();
3
// disabled biometric login successfully
4
} catch (e) {
5
// failed to disable biometric login
6
}
Copied!
- Error handling
iOS
Android
React Native
Flutter
1
if let authgearError = error as? AuthgearError {
2
switch authgearError {
3
case .cancel:
4
// user cancel
5
case .biometricPrivateKeyNotFound:
6
// biometric info has changed. e.g. Touch ID or Face ID has changed.
7
// user have to set up biometric authentication again
8
case .biometricNotSupportedOrPermissionDenied:
9
// user has denied the permission of using Face ID
10
case .biometricNoPasscode:
11
// device does not have passcode set up
12
case .biometricNoEnrollment:
13
// device does not have Face ID or Touch ID set up
14
case .biometricLockout:
15
// the biometric is locked out due to too many failed attempts
16
default:
17
// other error
18
// you may consider showing a generic error message to the user
19
}
20
}
Copied!
1
import com.oursky.authgear.BiometricLockoutException;
2
import com.oursky.authgear.BiometricNoEnrollmentException;
3
import com.oursky.authgear.BiometricNoPasscodeException;
4
import com.oursky.authgear.BiometricNotSupportedOrPermissionDeniedException;
5
import com.oursky.authgear.BiometricPrivateKeyNotFoundException;
6
import com.oursky.authgear.CancelException;
7
​
8
​
9
if (e instanceof CancelException) {
10
// user cancel
11
} else if (e instanceof BiometricPrivateKeyNotFoundException) {
12
// biometric info has changed
13
// user have to set up biometric authentication again
14
} else if (e instanceof BiometricNoEnrollmentException) {
15
// device does not have biometric set up
16
} else if (e instanceof BiometricNotSupportedOrPermissionDeniedException) {
17
// biometric is not supported in the current device
18
// or user has denied the permission of using biometric
19
} else if (e instanceof BiometricNoPasscodeException) {
20
// device does not have unlock credential set up
21
} else if (e instanceof BiometricLockoutException) {
22
// the biometric is locked out due to too many failed attempts
23
} else {
24
// other error
25
// you may consider showing a generic error message to the user
26
}
Copied!
1
import {
2
CancelError,
3
BiometricPrivateKeyNotFoundError,
4
BiometricNotSupportedOrPermissionDeniedError,
5
BiometricNoEnrollmentError,
6
BiometricNoPasscodeError,
7
BiometricLockoutError,
8
} from '@authgear/react-native'
9
​
10
if (e instanceof CancelError) {
11
// user cancel
12
} else if (e instanceof BiometricPrivateKeyNotFoundError) {
13
// biometric info has changed. e.g. Touch ID or Face ID has changed.
14
// user have to set up biometric authentication again
15
} else if (e instanceof BiometricNoEnrollmentError) {
16
// device does not have biometric set up
17
// e.g. have not set up Face ID or Touch ID in the device
18
} else if (e instanceof BiometricNotSupportedOrPermissionDeniedError) {
19
// biometric is not supported in the current device
20
// or user has denied the permission of using Face ID
21
} else if (e instanceof BiometricNoPasscodeError) {
22
// device does not have unlock credential or passcode set up
23
} else if (e instanceof BiometricLockoutError) {
24
// the biometric is locked out due to too many failed attempts
25
} else {
26
// other error
27
// you may consider showing a generic error message to the user
28
}
Copied!
1
try {
2
// ...
3
} on CancelException catch (e) {
4
// user cancel
5
} on BiometricPrivateKeyNotFoundException catch (e) {
6
// biometric info has changed. e.g. Touch ID or Face ID has changed.
7
// user have to set up biometric authentication again
8
} on BiometricNoEnrollmentException catch (e) {
9
// device does not have biometric set up
10
// e.g. have not set up Face ID or Touch ID in the device
11
} on BiometricNotSupportedOrPermissionDeniedException catch (e) {
12
// biometric is not supported in the current device
13
// or user has denied the permission of using Face ID
14
} on BiometricNoPasscodeException catch (e) {
15
// device does not have unlock credential or passcode set up
16
} on BiometricLockoutException catch (e) {
17
// the biometric is locked out due to too many failed attempts
18
} catch (e) {
19
// other error
20
// you may consider showing a generic error message to the user
21
}
Copied!
Last modified 10d ago