The BiometricCryptoManager is a component that manages the BiometricFactor. The implementation of creating a
BiometricFactor differs for iOS and Android due to the platform's biometric API. To use a biometric factor for
authentication, it either must have been set up during a personalization process or added later by issuing a specific
API access request (see Add Factor). Please note that if the user changes the biometric patterns after
setup, the biometric factor will become invalid and can no longer be used. In this case, the personalization must be
repeated to re-enroll a biometric factor that has become invalid.
On the iOS platform, a BiometricFactor must be created and then authenticated with the biometric data of the user. The
XignSys SDK wraps the Foundation calls that are needed to display Apple's biometric authentication dialog. A
BiometricFactor can be created by invoking BiometricCryptoManager.buildCryptoObject(idmIdentifier:).
The needed identity manager identifier can be acquired from the previous flow steps result, i.e. from the
property idmIdentifier of the PersonalizationParameters or UserInformation. The returned BiometricFactor object
must then be authenticated with a call of is instance function evaluateAccessControl(localizedReason: reply:). The
authentication result is delivered on the callback function reply. The reply function has two parameters, firstly
a Bool success and secondly an optional Error. If the parameter success equals true, the previously
created BiometricFactor object has successfully been authenticated and can now be used for a personalization or
authentication.
func getBiometricFactor(
idmIdentifier: String,
onResult: @escaping (BiometricFactor?) -> Void
) throws {
let biometricCryptoManager: BiometricCryptoManager = XignSdk.shared.biometricCryptoManager
// creating a BiometricFactor object by supplying the idmIdentifier. Please
// note that the resulting object is not yet authenticated at this point.
// Passing it directly to another SDK function will result in an error.
let biometricFactor: BiometricFactor = try biometricCryptoManager.buildFactor(
idmIdentifier: idmIdentifier
)
// prompts the biometric dialog to the user for authentication
try biometricFactor.evaluateAccessControl(
// Specify a reasonable localized reason. This information is displayed
// to the user and explains, why the app asks for a biometric authentication.
localizedReason: "The reason",
reply: { (success: Bool, error: Error?) in
if (success) {
// returning the successful authenticated BiometricFactor to the caller
onResult(biometricFactor)
} else {
// return nil in case of an authentication failure
onResult(nil)
}
}
)
}
On the Android platform you need to create
a CryptoObject and
authenticate it with the user's biometrics in order to build a XignSys SDK BiometricFactor. To understand and use this
component knowledge of how to use
Android biometric dialogues is required. We advise
using the Android Biometric Jetpack library for an
easier handling on lower Android API levels. With a call of BiometricCryptoManager.buildCryptoObject(idmIdentifier:)
you can create a CryptoObject, that can be authenticated with the Android BiometricPrompt. This function is
overloaded as well to support most current Android API levels and support libraries. Furthermore, you need an identity
manager identifier that can be acquired from the previous flow steps result i.e., from the property idmIdentifier of
the PersonalizationParameters or UserInformation. The following code segment demonstrates the creation of
a BiometricFactor with the help of the Android Biometric Jetpack library.
private fun getBiometricFactor(
idmIdentifier: String,
activity: AppCompatActivity,
onResult: (BiometricFactor?) -> Unit
) {
val biometricCryptoManager = XignSdk.shared.biometricCryptoManager
// creating an CryptoObject to authenticate with the Android JetPack library
val cryptoObject = biometricCryptoManager.buildCryptoObject(BiometricPrompt::class, idmIdentifier)
// creation of the prompt information that will be shown to the user
val bioPromptInfo = BiometricPrompt.PromptInfo.Builder().run {
setTitle("Your title")
setDescription("Your description")
setNegativeButtonText("Cancel")
setConfirmationRequired(false)
build()
}
// creation of the biometric prompt object. Please note that the callback object
// AuthenticationCallback has been inlined for the sake of simplicity in this example.
val bioPrompt = BiometricPrompt(activity,
ContextCompat.getMainExecutor(activity),
object : BiometricPrompt.AuthenticationCallback() {
override fun onAuthenticationSucceeded(
result: BiometricPrompt.AuthenticationResult
) {
// creating a BiometricFactor with the AuthenticationResult
val biometricFactor = BiometricFactor(result)
// invoking the given callback function to deliver the result
onResult(biometricFactor)
}
override fun onAuthenticationError(errorCode: Int, errString: CharSequence) {
// invoking the given callback function with null in case of an error
onResult(null)
}
}
)
// displaying the prompt to the user
bioPrompt.authenticate(bioPromptInfo, cryptoObject)
}