Authentication

Authentication authenticates the user. You can think of "authentication" as a "signin" process. During the authentication Keyless compares the user's face biometrics with the one previously computed during the enrollment.

If the biometrics match, Keyless authenticates the user.

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

Authentication builder methods

You can customize the authentication with optional methods from the AuthenticationConfiguration builder.

Some methods are the same of the EnrollmentConfiguration builder since those methods can be called both during enrollment and authentication.

The full AuthenticationConfiguration is available below:

interface AuthenticationConfigurationBuilder {

    fun addingNewDevice(b64NewDeviceData: String): AuthenticationConfigurationBuilder
    
    fun confirmingNewDevice(oldDeviceData: String): AuthenticationConfigurationBuilder
    
    fun retrievingBackup(): AuthenticationConfigurationBuilder

    fun retrievingSecret(): AuthenticationConfigurationBuilder
    
    fun revokingDevice(deviceId: String): AuthenticationConfigurationBuilder
    
    fun withDelay(cameraDelaySeconds: Int): AuthenticationConfigurationBuilder
 
     fun withDynamicLinking(payload: String): AuthenticationConfigurationBuilder
     
     fun withLivenessSettings(
        livenessConfiguration: LivenessSettings.LivenessConfiguration,
        livenessTimeout: Int
    ): AuthenticationConfigurationBuilder
    
    fun withMessageToSign(message: String): AuthenticationConfigurationBuilder
    
    fun withOperationInfo(
        operationId: String,
        payload: String? = null,
        externalUserId: String? = null
    ): AuthenticationConfigurationBuilder
    
    fun withPin(pin: String): AuthenticationConfigurationBuilder
    
    fun withSuccessAnimation(): AuthenticationConfigurationBuilder

    fun build(): AuthenticationConfiguration
}

Authentication success result

Depending on the builder methods you enable, Keyless will populate the corresponding fields in the AuthenticationSuccess result reported below. Not all builder methods produce a result as output that is why you have less fields in output than the number of methods of the builder.

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

Custom Secret

If you saved a custom secret during enrollment, you can retrieve it using retrievingSecret method.

If you add the method to the builder Keyless will populate the field customSecret in the AuthenticationSuccess result.

Backup Retrieval and Recovery

Keyless can generate backup data useful to recover an account.

You are responsible to store the backup data securely.

To retrieve the backup data use retrievingBackup method. Once the enrollment succeeds you can read the backup data in the EnrollmentSuccess result.

To recover and account you can enroll with backup data that you retrieved and stored in the past. To recover an account use withBackup passing as parameter the backup data.

You can find the backup as output in the AuthenticationSuccess result.

Liveness Settings

Using withLivenessSettings you can specify the liveness security level choosing the options from LivenessConfiguration.

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

Operation info

withOperationInfo specifies an operation identifier and payload stored on the Keyless backend if the enrollment succeeds.

Each operation id must be unique, you will get an error if you reuse the same operation id.

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

Message signing

Using the withMessageToSign method it is possible to specify a message (string) that will be signed by the user signing key.

If the authentication is successful, you will find the signedJwt in the AuthenticationSuccess.

The signedJwt is a jwt verifiable using the user signing public key returned by the getUserSigningPublicKey api.

Authentication Delay

Using withDelay you can specify the delay (in seconds) to delay the liveness start. The camera preview appears but the liveness processing waits for the specified delay before starting.

Dynamic linking

Displays a custom payload to the user and signs it before returning the signed JWT. The signed JWT is the same used in the message signing builder method.

If the authentication is successful, you will find the signedJwt in the AuthenticationSuccess.

With this method Keylss SDK will also display a map of key value pairs to users. Keys are used as labels while values populate the fields of a form with dynamic linking information shown to the users. The same payload is added as body of the returned signedJwt.

We do NOT perform any validation of your custom payload. You are responsible for the payload displayed to users.

We expect a payload that conforms to the following structure:

[
  {"labelToDisplay1":"textValueToDisplay1"},
  {"key2":"value2"},
  {"key3":"value3"},
]

Success Animation

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

Multidevice

The following builder methods are coverdered in the multidevice section:

  • addingNewDevice

  • confirmingNewDevice

  • revokingDevice

Last updated