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

iOS

let configuration = BiomAuthConfig()

Keyless.authenticate(
    configuration: configuration,
    onCompletion: { result in
        switch result {
        case .success(let success):
            print("Authentication success")
        case .failure(let error):
            break
        }
    })

Android 4.6

val configuration = AuthenticationConfiguration.builder.build()

Keyless.authenticate(
    authenticationConfiguration = 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}")
        }
    }
)

iOS 4.6

let configuration = Keyless.AuthenticationConfiguration.builder.build()

Keyless.authenticate(
    authenticationConfiguration: configuration,
    onCompletion: { result in
        switch result {
        case .success(let success):
            print("Authentication success")
        case .failure(let error):
            break
        }
    })

Flutter

import 'package:keyless_flutter_sdk/keyless.dart';
import 'package:keyless_flutter_sdk/models/configurations/authentication_configuration.dart';

final configuration = BiomAuthConfig();

try {
  final result = await Keyless.instance.authenticate(configuration);
  print("Authentication success");
} catch (error) {
  print("Authentication failure");
}

React Native

import Keyless, { BiomAuthConfig } from '@react-native-keyless/sdk';

const authenticateUser = async () => {
  const configuration = new BiomAuthConfig();

  const result = await Keyless.authenticate(configuration);

  result.fold({
    onSuccess: (data) => {
      console.log('Authentication success', data);
    },
    onFailure: (error) => {
      console.error('Authentication failure:', error);
    },
  });
};

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.

Android

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

iOS

public struct BiomAuthConfig: AuthConfig {
    public let cameraDelaySeconds: Int
    public let jwtSigningInfo: JwtSigningInfo?
    public let livenessConfiguration: Keyless.LivenessConfiguration
    public let livenessEnvironmentAware: Bool
    public let operationInfo: Keyless.OperationInfo?
    public let shouldRemovePin: Bool
    public let shouldRetrieveTemporaryState: Bool
    public let shouldRetrieveSecret: Bool
    public let shouldDeleteSecret: Bool
    public let showSuccessFeedback: Bool
}

Android 4.6

interface AuthenticationConfigurationBuilder {

    fun retrievingBackup(): AuthenticationConfigurationBuilder

    fun retrievingSecret(): AuthenticationConfigurationBuilder

    fun deletingSecret(): AuthenticationConfigurationBuilder

    fun retrievingTemporaryState(): AuthenticationConfigurationBuilder

    fun withDelay(cameraDelaySeconds: Int): 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(enabled: Boolean = true): AuthenticationConfigurationBuilder

    fun build(): AuthenticationConfiguration
}

iOS 4.6

public class Builder {

    public func retrievingBackup() -> Builder

    public func retrievingSecret() -> Builder

    public func deletingSecret() -> Builder

    public func retrievingTemporaryState() -> Builder

    public func revokingDevice(id: String) -> Builder

    public func withDelay(seconds: Int) -> 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(_ enabled: Bool) -> Builder

    public func build() -> AuthenticationConfiguration
}

Flutter

class BiomAuthConfig extends AuthConfig {
    final LivenessConfiguration? livenessConfiguration;
    final int? livenessTimeout;
    final int? cameraDelaySeconds;
    final bool? shouldRetrieveTemporaryState;
    final String? b64NewDeviceData;
    final String? b64OldDeviceData;
    final String? deviceToRevoke;
    final bool? shouldRetrieveSecret;
    final bool? shouldRemovePin;
    final JwtSigningInfo? jwtSigningInfo;
    final DynamicLinkingInfo? dynamicLinkingInfo;
    final OperationInfo? operationInfo;
    final bool? showScreenSuccessFlow;
}

React Native

class BiomAuthConfig {
  public readonly shouldRemovePin: boolean;
  public readonly cameraDelaySeconds: number;
  public readonly showSuccessFeedback: boolean;
  public readonly shouldRetrieveSecret: boolean;
  public readonly shouldDeleteSecret: boolean;
  public readonly shouldRetrieveTemporaryState: boolean;
  public readonly jwtSigningInfo: JwtSigningInfo | null;
  public readonly dynamicLinkingInfo: DynamicLinkingInfo | null;
  public readonly livenessConfiguration: LivenessConfiguration;
  public readonly deviceToRevoke: string | null;
  public readonly operationInfo: OperationInfo | null;
}

The successAnimationEnabled and later showScreenSuccessFlow field has been renamed to showSuccessFeedback, triggering a breaking change. Moreover the success animation is now shown by default.

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 customSecret: String? = null,
    val signedJwt: String? = null,
    val temporaryState: String? = null
) : KeylessSdkSuccess()

iOS

public struct AuthenticationSuccess {
    public let customSecret: String?
    public let signedJwt: String?
    public let temporaryState: String?
}

Flutter

class AuthenticationSuccess {
    final String? customSecret;
    final String? signedJwt;
    final String? temporaryState;
}

React Native

class AuthenticationSuccess {
  customSecret: string | null;
  signedJwt: string | null;
  userInfo: string | null;
  temporaryState: string | null;
}

Backup data

Backup data is no longer recommended to perform account recovery and the feature has been removed from Android and iOS SDKs. Use the temporary state instead. 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.

Furthermore, such a custom secret can be deleted using the shouldDeleteSecret parameter.

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 livenessEnvironmentAware that is by default se to true to enhance liveness detection. This parameters helps to ensure the user is in a suitable setting for verification.

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.

Temporary State

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