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.

Android

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}")
        }
    }
)

iOS

let configuration = Keyless.AuthenticationConfiguration.builder.build()
        
Keyless.authenticate(
    authenticationConfiguration: configuration, 
    onCompletion: { result in
        switch result {
        case .success(let success):
            print(success.token)
        case .failure(let error):
            break
        }
    })

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:

Android

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
}

iOS

public class Builder {

    public func addingNewDevice(_ newDeviceData: String) -> Builder 
    
    public func confirmingNewDevice(_ oldDeviceData: String) -> Builder
    
    public func retrievingBackup() -> Builder 
    
    public func retrievingSecret() -> Builder 
    
    public func revokingDevice(id: String) -> Builder 
    
    public func withDelay(seconds: Int) -> Builder
    
    public func withDynamicLinking(_ payload: String) -> Builder
    
    public func withLivenessSettings(
        livenessConfiguration: LivenessConfiguration, 
        livenessTimeout: Int
    ) -> Builder 
            
    public func withMessageToSign(_ message: String) -> Builder 

    public func withOperationInfo(
        id: String, 
        payload: String? = nil, 
        externalUserId: String? = nil
    ) -> Builder 

    public func withPin(_ pin: String) -> Builder 
    
    public func withSuccessAnimation() -> Builder
    
    public func 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.

Android

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

iOS

public struct AuthenticationSuccess {
        public let backup: Keyless.Backup?
        public let customSecret: String?
        public let deviceData: String?
        public let signedJwt: String?
}

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 outpu 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 enrollment 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 re-use 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