Documentation Hub End User Guide

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

  • KEYLES_HOSTS a list of node URLs

as well as the following software 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:

app/build.gradle
```kotlin
dependencies {
// ...

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

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

app/build.gradle
```kotlin
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: `configure` is asynchronous so wait for the completion callback before calling the next Keyless APIs
The `configure` method requires a `SetupConfiguration` as parameter, as well as the `KEYLESS_API_KEY` and `KEYLESS_HOSTS` you received from Keyless. You should listen to the result as follows:

```kotlin
val setupConfiguration = SetupConfiguration.builder
.withApiKey("KEYLESS_API_KEY")
.withHosts(listOf("KEYLES_HOSTS"))
.build()

Keyless.configure(setupConfiguration) { 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
        }
    }
}
```

Optional configuration

As well as the essential configuration parameters, you can also specify the optional configuration parameters detailed in the following sections.

Logging enabled

Activate logging to the Keyless Management portal with the withLoggingEnabled() method. Logs do not include sensitive user data. Logging is disabled by default.

Lockout policy

The lockout policy determines how many failed login attempts (lockoutAttemptsThreshold) are allowed over a set time period (lockoutAttemptsResetAfter) before the user is locked out for the set duration (lockoutDuration).

Account lockoutDuration must be greater than or equal to the lockoutAttemptsResetAfter so that it is not reset by lockoutAttemptsResetAfter.

fun withLockoutPolicy(
    lockoutDuration: Long,                //seconds - default 300 seconds
    lockoutAttemptsResetAfter: Long,      //seconds - default 180 seconds
    lockoutAttemptsThreshold: Int         //number  - default 5 attempts
)

Tampered device check

Checking for rooted/jailbroken phones is an unreliable process but you can enable the check with withTamperedDeviceCheck(). If you enable this check, and the SDK detects that phone was tampered with, the Keyless SDK will return an error and prevent the user from authenticating.

Enrollment circuits

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

Networking module

If you need to specify a custom module to perform network requests, add withNetworkingModule from the SetupConfigurationBuilder, which must conform to the interface below.

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
    )
}
PreviousIntegration FlowsNext2️⃣ Enrollment

Last updated