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.

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

Check out the guide on using Keyless to authenticate with Auth0, or read on for detailed information on the authentication builder methods.

Authentication builder methods

You can customize the authentication process with optional methods from the AuthenticationConfiguration builder:

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.

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 the retrievingSecret method.

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

Backup data

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

To create the backup data use the retrievingBackup method. Once authentication succeeds, copy the backup data from the AuthenticationSuccess result, and store it securely.

To recover an account, use withBackup passing as parameter the backup data you stored previously.

Liveness Settings

Using withLivenessSettings you can specify the liveness security level during authentication, 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.

More details on liveness levels in the SDK Reference.

Operation info

withOperationInfo 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.

Message signing

Using the withMessageToSign method you can sign a message (string) with the user signing key.

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

Verify the signedJwt using the public key returned by the getUserSigningPublicKey api.

Authentication Delay

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

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 the Keyless SDK will also display a map of key value pairs to user. Keyless does not validate the key value pairs in any way.

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.

[
  {"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