1️⃣ Getting started

In this short guide, you will learn how to integrate the Keyless SDK in your Android or iOS mobile application, and enroll and authenticate users through the Keyless platform.

Before jumping into your code editor, make sure that you're familiar with the various components of the authentication system, and common biometic authentication flows.

Prerequisites

Make sure you have both required API keys, and the list of productions hosts from your Keyless contact:

  • YOUR_CLOUDSMITH_TOKEN to download the SDK from cloudsmith repository

  • KEYLESS_API_KEY to configure the mobile SDK

  • KEYLESS_HOSTS a list of node URLs. Urls in KEYLESS_HOSTS must NOT contain any trailing slashes /.

Review the Keyless SDK requirements:

Installation

  1. To allow Keyless to handle the result of registerForActivityResult, you must call Keyless from an Activity implementing ActivityResultCaller.

    Extend any androidX activity that implements the interface for you, for example let your Activity extend the generic ComponentActivity or the more widespread AppCompatActivity.

  2. If you use Proguard, add the following rules to your Proguard configuration file:

    # Keyless Proguard
-keep class io.keyless.sdk.** {*;}
-keepclassmembers class io.keyless.sdk.** {*;}

  3. In the the repositories section of the settings.gradle file of your Android application, add the following snippet, replacing YOUR_CLOUDSMITH_TOKEN with the CloudSmith token provided to you by Keyless.

    dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven {
            url "https://dl.cloudsmith.io/YOUR_CLOUDSMITH_TOKEN/keyless/partners/maven/"
        }
    }
}

  4. In the dependencies block of your project build.gradle file, typically app/build.gradle, add:

    dependencies {
// ...

implementation 'io.keyless:keyless-android-sdk:+'
}

  5. In the android block of your project build.gradle file, typically app/build.gradle, make sure you have the following options:

    android {
    // ...

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }

    // add the following only if you're using Kotlin
    kotlinOptions {
        jvmTarget = "1.8"
    }
}

Essential configuration

There is some essential configuration to do before you can use the Keyless SDK.

  1. Initialize the Keyless SDK in your Application class:

    // MainApplication
override fun onCreate() {
    super.onCreate()
    // Initialize Keyless
    Keyless.initialize(this)
}

  2. Add your application to the Manifest

    <application
    ...
    android:name=".MainApplication"
    ...
</application>

  3. Configure the Keyless SDK from your MainActivity, ViewModel or any class you use to communicate with Keyless. Note that configure is asynchronous so wait for the completion callback before calling the next Keyless APIs

    The configure method requires a SetupConfig as parameter, as well as the KEYLESS_API_KEY and KEYLESS_HOSTS you received from Keyless. You should listen to the result as follows:

    val setupConfig = SetupConfig(
        apiKey = "KEYLESS_API_KEY",
        hosts = listOf("KEYLESS_HOSTS")
    )

 Keyless.configure(setupConfig) { result ->
    when (result) {
        is Keyless.KeylessResult.Success -> {
            Log.d("KeylessSDK", "configure success")
            // Keyless is ready, you can now call
            // enroll/authenticate/deEnroll ...
        }
        is Keyless.KeylessResult.Failure ->{
            Log.d("KeylessSDK", "configure error")
            // Inspect result.error for more info
         }
     }
 }

Additional configuration

As well as the essential configuration parameters, you can also specify the optional configuration parameters detailed in the following sections. You can inspect the Config class to see optional parameters (or the builder to see exposed methods)

Logging

Logging is disabled by default.

Please note logs do not include any Personally Identifiable Information (PII).

Keyless allows you to:

  1. enable logging to the Keyless infrastructure - keylessLogsConfiguration

  2. collect logging for you own analytics without sending them to the Keyless infrastructure - customLogsConfiguration

val setup = SetupConfig(
    apiKey = "...",
    hosts = listOf(""),
    keylessLogsConfiguration = LogsConfiguration(
        enabled = true,
        logLevel = LogLevels.INFO
    ),
    customLogsConfiguration = LogsConfiguration(
        enabled = true
    )
)

Collect logs after setting up custom logging with customLogsConfiguration option:

  1. Start collecting the Keyless.customLogs flow (This must happen before a Keyless.configure() to get all Logs Events):

Keyless.customLogs.collect { logEvent ->
    // handle the logEvent
}

  1. Configure the SDK with the following SetupConfig:

val setup = SetupConfig(
    apiKey = "...",
    hosts = listOf(""),
    customLogsConfiguration = LogsConfiguration(
        enabled = true,
        logLevel = LogLevels.INFO // This is optional and defaults to INFO
    )
)

Logging Levels

You may set different logging levels to provide more or less information in logs.

The available levels are the following:

  • INFO (default)

  • DEBUG

  • TRACE

The TRACE level provides the following additional data:

  • userId

  • devicePublicSigningKey

  • coreLogHistory (used for detailed debugging)

Liveness Lockout policy

Since version 5.0.0 of the SDK the lockout policy is no longer processed on the client for security reasons. The lockout policy is applied only during authentication and can be confiured server side.

Tampered device check

Keyless provides a tampered device check that can be enabled within the Mobile SDK configurations. This service looks for signs of rooting, or jailbreaking, whereby a smartphone or tablet may have been tampered with in order to gain greater administrative control over it, a tactic used by malicious actors. You can enable the check by:

  • Calling the withTamperedDeviceCheck() on the SetupConfigurationBuilder if using the legacy SetupConfiguration.

  • Setting withDevicePrivileges to true if using the new SetupConfig.

If you enable this check, and the SDK detects that the phone was tampered with, the Keyless SDK will return an error and prevent the user from authenticating. As ever, we advise clients that no security measure is perfect and we can't guarantee 100% detection success rate. Therefore we recommend taking advice or carry out further research on how else to harden the security of your own app if this is a particular concern.

Enrollment circuits

To speed up enrollment you can use the numberOfEnrollmentCircuits to upload less than the default of five circuits upon enrollment. The remainder (50 - numberOfEnrollmentCircuits) are uploaded asynchronously.

Shared circuits

This is the target desired number of circuits kept on the server. To set this number use the numberOfSharedCircuits.

Networking module

If you need to perform network requests on behalf of Keyless SDK, you can implement the KLNetworkingModule interface. Set the networkingModule parameter with an instance of the KLNetworkingModule:

public interface KLNetworkingModule {
    public fun sendHTTPRequest(
        baseUrl: String,
        path: String,
        method: String,
        headers: Map<String, String>,
        body: String
    ): KLHTTPResponse

    public data class KLHTTPResponse(
        val errorCode: Int,
        val httpCode: Int,
        val responseBody: String
    )
}

Last updated

Was this helpful?