Getting started

Let's get started!

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

Since Keyless has more advanced features than just a simple authentication product, the guide is split into multiple functional sections with more details, with proper code snippets and examples for both iOS and Android.

For any questions or comments (at any time) during the integration phase please reach out to your primary Keyless contact or to [e-mail].

Prerequisites

Android

Android 6.0 (API level 23) and above

Gradle 6.5+

Android Gradle Plugin 4.0.0+

AndroidX

To allow Keyless to handle the result of registerForActivityResult, you must call Keyless from an Activity implementing ActivityResultCaller. Your best option is to extend any androidX activity that implements the interface for you, for example let your Activity extend the generic ComponentActivity or the more widespread AppCompatActivity

If you use Progurad add the following rules:

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

iOS

Install the following:

• Xcode 10.1 or later

• CocoaPods 1.4.0 or later

• Make sure that your project meets the following requirements:

  • Your project must target iOS 13 or later.

  • Swift projects must use Swift 4.0 or later.

• Set up a physical iOS device for running your app.

• Enable Camera permissions: add the Privacy - Camera Usage Description key in your project’s Info.plist by adding the following (in XCode under Project > Info):

<key>NSCameraUsageDescription</key>
<string>Keyless needs access to your camera to enroll and authenticate you. Keyless cannot be used without your camera. Please allow camera permissions.</string>

• Background processing. Enable the Background processing mode under Signing & Capabilities/Background Modes. Then, add the following in your project’s Info.plit (in XCode, under the key Permitted background task scheduler identifiers):

  <key>NSCameraUsageDescription</key>
  <key>BGTaskSchedulerPermittedIdentifiers</key>
  <array>
      <string>YOUR APP IDENTIFIER</string>
  </array>

Installation

Android - Gradle

Add the following within the repositories section of the settings.gradle file of your Android application.

Replace the YOUR_CLOUDSMITH_TOKEN text with the CloudSmith token for partners 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/"
        }
    }
}

Add the following to the dependencies block of your project build.gradle file, typically app/build.gradle.

app/build.gradle

dependencies {
  // ...
  
  implementation 'io.keyless:keyless-android-sdk:+'
}

Make sure you have the following options in the android block of the same file

app/build.gradle

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

iOS - Cocoapods

Step 1: Create a Podfile if you don’t already have one

$ cd your-project-directory
$ pod init

Step 2: Setup Cocoapods to use your Cloudsmith credentials, by running the following commands and replacing YOUR_CLOUDSMITH_TOKEN with the Cloudsmith token for partners provided you by Keyless.

git config --global credential.helper store
echo "https://token:[e-mail]" >> ~/.git-credentials

Step 3: Add the KeylessSDK pod to your Podfile

# This is the Keyless repository for partners
source 'https://dl.cloudsmith.io/basic/keyless/partners/cocoapods/index.git'

target 'MyApp' do
    use_frameworks!

    # Add the Keyless pod
    pod 'KeylessSDK'
end

Step 4: Add the following at the bottom of the same file

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['ENABLE_BITCODE'] = 'NO'
    end
  end
end

Step 5: Install the pods. If pod prompts you for authentication insert the string token as your username and then fill in YOUR_CLOUDSMITH_TOKEN as the password.

$ pod install

Analyzing dependencies
Cloning spec repo `cloudsmith-basic-keyless-partners-cocoapods-index` from `https://dl.cloudsmith.io/basic/keyless/partners/cocoapods/index.git`
Username for 'https://dl.cloudsmith.io': token
Password for 'https://dl.cloudsmith.io': YOUR_CLOUDSMITH_TOKEN

Configuration

Now all the dependencies should be set. To start using the Keyless SDK you just need to configure it.

Android

First initialize the Keyless SDK in your Application class:

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

Make sure to add your application to you Manifest

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

Then 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 aSetupConfiguration as parameter. You should listen to the result as follows:

val setupConfiguration = SetupConfiguration.builder
  .withApiKey("apiKey")
  .withHosts(listOf("host"))
  .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
        }
    }
}

iOS

All you need to do to configure the Keyless SDK, is to create an instance object of Keyless.SetupConfiguration and pass it to the Keyless.configure method, typically this in done in your app’s application(:didFinishLaunchingWithOptions: method:).

let setupConfiguration = Keyless.SetupConfiguration.builder
  .withApiKey("apiKey")
  .withHosts(["host"])
  .build()

if let error = Keyless.configure(configuration: setupConfiguration) {
  print("Keyless.Configure failed with error: \(error)")
}

SetupConfiguration parameters

It is possible to specify configuration parameters using the SetupConfiguration builder. In addition to the apiKey (.withApiKey()) and hosts (.withHosts) above, you can also specify the following optional configuration parameters:

Logging enabled

Using the withLoggingEnabled() method it is possible to activate the logging on Keyless analytics tool. These logs do not include any sensitive data from your users. Keyless SDK logs predefined events to help monitor your app usage.

Logging is disabled by default.

Lockout policy

This is a feature will block users for a given amount of time if there are too many failed authentication attempts.

After a number (lockoutAttemptsThreshold) of failed authentication attempts the user will be locked out.

The user will remain locked out for the specified lockoutDuration.

The attempts are reset after the specified lockoutAttemptsResetAfter time.

Account lockoutDuration must be greater than or equal to the value of lockoutAttemptsResetAfter or the lockoutDuration will be reset by the other timer.

You can specify it using the following api:

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 the following api: withTamperedDeviceCheck(). If you enable this check and the phone is tampered the Keyless SDK will return an error and avoid performing any operation.

Enrollment circuits

To speed up enrollment you can specify a different number of enrollment circuits (there is a default to 5 enrollment circuits). You do not need to change that but in case it is needed there is a dedicated api: withNumberOfEnrollmentCircuits(numberOfEnrollmentCircuits: Int)

Networking module

The SDK exposes an API to specify which function shall be called to perform network requests. You can specify a custom "networking module" adding withNetworkingModule from the SetupConfigurationBuilder. Your implementation of the networking module must conform to the interface below.

Android

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

iOS

public protocol KLNetworkingModule {     
    func sendHTTPRequest (
        host: String,
        url : String,
        method: String,
        headers : [String: String],
        body : String) -> KLHTTPResponse
}

public struct KLHTTPResponse {
    var errorCode: Int
    var httpCode: Int
    var responseBody : String
    public init(errorCode: Int, httpCode: Int, responseBody: String) {
        self.errorCode = errorCode
        self.httpCode = httpCode
        self.responseBody = responseBody
    }
}