3️⃣ Authentication

Authentication is the biometric equivalent of "signing-in". During authentication Keyless compares the user's facial biometrics with the ones computed during enrollment.

If the biometrics match, Keyless authenticates the user.

val configuration = BiomAuthConfig()

Keyless.authenticate(
    configuration = configuration,
    onCompletion = { result ->
        when (result) {
            is Keyless.KeylessResult.Success -> Log.d("KeylessSDK ", "Authentication success")
            is Keyless.KeylessResult.Failure -> Log.d("KeylessSDK ", "Authentication failure - error code ${result.error.code}")
        }
    }
)

Authentication configuration

You can configure the authentication process with optional parameters in your BiomAuthConfig() instance or using the builder pattern methods from the AuthenticationConfiguration builder.

public data class BiomAuthConfig(
    public val cameraDelaySeconds: Int = 0,
    public val jwtSigningInfo: JwtSigningInfo?,
    public val livenessConfiguration: LivenessSettings.LivenessConfiguration = PASSIVE_STANDALONE_HIGH,
    public val livenessTimeout: Int = 60,
    public val operationInfo: OperationInfo?,
    public val shouldRemovePin: Boolean = false,
    public val shouldRetrieveTemporaryState: Boolean = false,
    public val shouldRetrieveSecret: Boolean = false
    public val successAnimationEnabled: Boolean = false,
)

Authentication success result

Depending on the builder methods you enable, Keyless will populate the corresponding fields in the AuthenticationSuccess result reported below.

data class AuthenticationSuccess(
    val backup: KeylessBackup? = null,
    val customSecret: String? = null,
    val signedJwt: String? = null,
    val temporaryState: String? = null
) : KeylessSdkSuccess()

Backup data

Backup data is no longer recommended to perform account recovery use the temporary state. Follow the guide on account recovery.

Keyless can generate backup data that you can use to recover an account.

To create the backup data use the shouldRetrieveBackup configuration parameter. Once authentication succeeds, copy the backup data from the AuthenticationSuccess result, and store it securely.

To recover an account, use backup parameter during enrollment more in backup.

Camera Delay

Use cameraDelaySeconds to specify the delay (in seconds) between when the camera preview appears, and when the liveness processing starts.

Custom Secret

If you saved a custom secret during enrollment, you can retrieve it using the shouldRetrieveSecret parameter.

Keyless will populate the field customSecret in the AuthenticationSuccess result.

JWT Signing info

You can specify a payload to be added to a JWT signed by Keyless with the jwtSigningInfo parameter, more in JWT signing.

Liveness Settings

Using livenessConfiguration you can configure the liveness security level during enrollment. The possible liveness configuration are under LivenessSettings.LivenessConfiguration :

PASSIVE_STANDALONE_MEDIUM
PASSIVE_STANDALONE_HIGH        //recommended configuration
PASSIVE_STANDALONE_HIGHEST

You can also specify a livenessTimeout (in seconds) to cancel the enrollment if the liveness takes longer than the timeout.

More details on liveness in the dedicated liveness settings section.

Operation info

The parameter operationInfo specifies a customizable unique operation identifier and associated payload stored on the Keyless backend if the enrollment succeeds.

Details on how to query our backend for stored operations are available on Operations API.

Success Animation

Using the successAnimation you can specify whether the Keyless SDK should display a checkmark indicating a successful authentication to the user.

Temporary State

Use the shouldRetrieveTemporaryState parameter to creata a temporary state useful for the account recovery.

Last updated