Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Integrate Keyless capabilities into your application.
We recommend skimming through the Integration Flows page for a brief overview of the system before starting to code.
Understand what Keyless does
Learn about the core elements in the Keyless Protocol.
Understand how Keyless exists into your existing or new app.
More on how to user our out-of-box authenticator.
The Keyless Privacy Policy.
Live operational status of the Keyless infra.
Nothing to remember. Nothing to steal. You are the key.
Keyless is building a privacy-first biometric authentication and identity management platform that eliminates the need for businesses to centrally store and manage passwords, sensitive cryptographic keys, and other authentication data, without compromising on convenience and privacy for their users.
The Keyless protocol implements secure biometric authentication using state-of-the-art secure multi-party computation techniques. The protocol involves the user’s mobile device, which interacts with a set of nodes in the Keyless network. Each node stores cryptographically protected shares of the user’s biometric data and of the user’s authentication key. These shares enable users to perform authentication without storing any biometric template on their devices, and to generate authentication tokens on demand.
The Keyless protocol is composed of two main phases: enrollment, and authentication.
During the enrollment phase, users register themselves and their mobile device with the Keyless network. This includes storing an encrypted authentication key and one-way processed biometric data in a distributed form on Keyless nodes using threshold secret sharing.
During authentication, Keyless first authenticates the user’s device, and then computes and sends a one-way transformed biometric sample. The sample is transformed locally on the user’s device, and is matched against the one-way transformed template sent to the Keyless nodes during enrollment. Because none of the nodes is able to decrypt the biometric template or the authentication sample, matching is performed using a secure multi-party computation protocol.
At the end of the authentication process, the nodes learn whether the biometric authentication sample matches the template. This indicates that, with high probability, the two biometric datapoints are from the same person. Additionally, a match reveals a different encrypted shares of the authentication key to each node, which forwards them to the user’s mobile device.
Once the device has received enough shares, it can use the authentication key to construct the user’s authentication token.
Check out our whitepaper for a technical overview of the Keyless protocol
Learn how the Keyless components interacts with your app.
The following document illustrates how the Keyless SDK component can be integrated in an application to enable biometric authentication. In particular, this document focuses on how all the Keyless software components interact with an environment composed of a Mobile Application and a Backend serving the application.
In order to authenticate with Keyless, a user must first enroll his biometric template. Enrollment with Keyless consists of registering the user’s biometric features on the Keyless network in a privacy-preserving manner through the Keyless SDK, which exposes a specific API for this scope.
The Keyless SDK can be used for two different scenarios:
User requests access on a Web Application
User requests access on a Mobile Application
While these are the two most common examples, customer use cases may fall into slightly different categories, and given the simplicity of how the Keyless SDK can be integrated, we can easily adapt the following flow to solve specific situations.
In this example the user is trying to get access to a resource / request an operation for which strong authentication is required through a Web Application. At this point, the Customer Backend sends a push notification to the customer app in order to request the user to identify himself with Keyless. After Biometric Authentication is successful, the flow goes back to the Customer Backend, which leverages the APIs exposed by the Keyless Backend to perform additional security checks.
Once the Keyless Backend confirms the authentication was successful, the User is informed.
In this flow, no Web App is involved in the process, as the user is requiring access to a resource / trying to perform an operation directly on the Mobile App. As we can see, the interaction with the Keyless components is performed in exactly the same way.
As mentioned, the package Keyless offers is composed of two main blocks:
SDK
Confirmation API Service
The Keyless SDK supports both Android and iOS, and exposes the APIs to interact with the Keyless Privacy-Preserving Network in order to:
Enroll a user
Authenticate
De-Enroll
Perform account recovery / restore (Backup)
The Keyless Delivery Team will provide the customer with the needed API keys. The SDK package can be downloaded as a Maven (Android) or CocoaPods artifact.
The Keyless Backend offers Cloud APIs which can be used to perform security checks through Backend-to-Backend calls. Specifically, it is possible to interrogate the Keyless Backend after the SDK returns an OK response for an Authentication attempt.
Keyless Backend is available as a SaaS service.
For any questions or comments about the integration flows please reach out to info@keyless.io.
Frequently Asked Questions.
The Keyless Authentication App is a standalone mobile app that enables users to seamlessly use their mobile devices to authenticate on websites, services, and external providers. See the Keyless Authentication App Offering for more details.
The Keyless network comprises of different server nodes which store the encrypted secret key and biometric information of the users. They interact with the user devices to compute the ‘closeness’ between stored biometric templates and the authentication samples of the users.
The user interacts with the Keyless nodes to perform operations including enrollment of themselves and their device(s) to the network, and authentication to the system.
The user device along with each of the Keyless nodes runs secure multi-party computations, storing long-lived secrets (including user’s cryptographic keys and other sensitive information) only as encrypted shares on the Keyless nodes. The encryption of the shares is performed on the user device before being sent to these nodes.
The apps can either choose the set of nodes from the network randomly or based on enterprise policies. The policies can be pre-defined before the instantiation of the protocol. If needed, the policies can also be updated and correspondingly the user can interact and send the encrypted shares to the new set of nodes in the network after the policy update.
The seed value and the biometric template are shared using Shamir’s Secret Sharing among the Keyless nodes. The secret sharing scheme is chosen so that
each of the secrets is split into several pieces. A number of these pieces is required to reconstruct the secret. Each share is encrypted and then stored on one node. No information is disclosed if one has access to less than the required number of shares.
The Keyless protocol specifies the cryptographic operations carried out on the user device such as secret sharing and encryption of seed and the biometric template along with the different mechanisms for interaction between the user device(s) and the Keyless network nodes.
Keyless secures user data, keys, and identities without the use of passwords and enables users, customers, and workforce to seamlessly and securely authenticate to online services, websites, and providers. Keyless provides the convenience of a unified experience across multiple devices where the user can use their biometrics for authentication and, optionally, key management.
Usability, security, and privacy. Keyless protocol allows a user to authenticate using facial features from any of the user’s devices, without having to remember any passwords or PINs, and interacting with systems like digital payments and online banking. It is designed to support several biometric modalities (e.g., fingerprints, iris, retinal scans, and behavioral biometrics), which will be included in the future.
The user keys and data, including the biometrics used for biometric authentication, are stored on Keyless server nodes in a secret-shared and encrypted fashion. The user device, together with their biometrics, is the only way to legitimately access secret keys and biometric information. Nobody else can access the user information or biometrics, not even the Keyless network.
This approach does not contain the typical central honeypot with user information that could be stolen during a data breach.
In order to attempt to spoof the system using compromised user-biometrics, the attacker also needs access to the enrolled trusted device of user. The Keyless Network checks if it the device is enrolled and is authenticated every time the user tries to authenticate themselves to the system. So, the spoof attempt needs to be performed before the stolen device is revoked by the user. Additionally, Keyless uses liveness detection techniques to detect and blocks spoofing attempts.
This is to mitigate a common and major attack vector where the adversary tries to attack the system from their own device. The adversary can not use any device that has not been enrolled to authenticate to the network, the device needs to be enrolled first and authenticated every time the user tries to interact using the enrolled device with the Keyless network. The device effectively acts as a two-factor authentication token.
To perform a Denial-of-Service attack, the attacker needs to perform such an attack on all the Keyless nodes simultaneously however such an attack is extremely difficult because of the distributed nature of the Keyless network. As long as a threshold number of servers are available, the availability of the Keyless network is ensured.
Currently, Keyless supports face recognition. However, the protocol is designed to allow several biometric modalities including fingerprints, iris scan, and retinal scan.
This is to mitigate a common and major attack vector where the adversary tries to attack the system from their own device. The adversary can not use any device that has not been enrolled to authenticate to the network, the device needs to be enrolled first and authenticated every time the user tries to interact using the enrolled device with the Keyless network. The device effectively acts as a two-factor authentication token.
Keyless automatically updates the user’s biometric template over time to account for natural changes in the user physiology and appearance. The Keyless network accepts updates to the user template only after successful authentication.
Keyless captures the facial features and extracts embeddings from the captured face using a neural network, the extracted embeddings are used for seed and key generation. The biometrics are as reliable as the capture and extraction of features are.
Keyless supports modern liveness detection techniques to detect that a picture is in front of the camera, and rejects the authentication attempt. These techniques seek to allow a biometric system to determine whether the biometric data used for authentication is from a living person, rather than from a photo, a mask, or a video. Liveness detection can be passive or active.
With passive liveness detection, a face recognition system uses minute face movements due to breathing and natural changes in expression to determine that the biometric data being extracted is from a live individual rather than a photo or a mask.
Active liveness detection involves a challenge-response mechanism: the authentication system asks the user to perform a randomized set of actions (e.g., look up, look left, blink twice), and checks whether the user has performed these actions correctly. These mechanisms prevent the use of pre-recorded videos of the legitimate user for the purpose of circumventing an authentication system.
Yes, Keyless conforms to the GDPR principles of lawfulness, purpose limitation, data minimization, accuracy, storage limitation, integrity, confidentiality and accountability. The user knows the flow of all his information in the system and so Keyless is transparent and lawful. The user biometric data is encrypted and shared among all the servers, the servers do not (and cannot) use the encrypted shares for any other purpose except storing meeting the second principle. The user stores no more information than what needs to be stored. The information stored in the system is updated by the user, its accuracy and updates are all controlled by the user and Keyless does not process or utilize the stored information in anyway. The different cryptographic tools used in the Keyless protocol ensure that the data remains confidential and is available to the user at all times.
Keyless uses secure multi-party computation to match the template with the authentication sample. Specifically, the Keyless protocol implements “comparison” between encrypted biometrics, and the secure multiparty computation together with biometric extraction is optimized to work in tens of milliseconds.
Biometric matching is performed on our nodes, rather than on a device that is potentially in the hands of the adversary. There are several security issues associated with local authentication: (1) the authentication result cannot be trusted in the network, and therefore cannot be trusted by the network, for instance, to release shares of cryptographic keys; and (2) if the device is physically in the hands of the adversary, it is possible to bypass authentication by editing the content of the device’s memory. Keyless addresses these and other issues by performing matching in the network, rather than locally on the user’s device.
Yes, the user can use multiple devices while enrolling just once. They can interact with the Keyless network from any one of the devices to perform operations including authentication, updating the biometric template, recovery etc. They can also revoke any of their devices anytime they wish.
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 info@keyless.io.
Android 6.0 (API level 23) and above
Gradle 6.5+
Android Gradle Plugin 4.0.0+
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:
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):
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
):
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.
Add the following to the dependencies
block of your project build.gradle
file, typically app/build.gradle
.
Make sure you have the following options in the android
block of the same file
Step 1: Create a Podfile if you don’t already have one
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.
Step 3: Add the KeylessSDK pod to your Podfile
Step 4: Add the following at the bottom of the same file
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.
Now all the dependencies should be set. To start using the Keyless SDK you just need to configure it.
First initialize the Keyless SDK in your Application
class:
Make sure to add your application to you Manifest
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:
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:).
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:
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.
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:
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.
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)
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.
Learn about the interaction between Keyless components
The diagrams below show how the Keyless SDK, which runs within your mobile app on the user’s device, interacts with your application server and with the Keyless network.
To enroll, your mobile app invokes the enroll
method from the Keyless SDK. With this method, the mobile device assists the user while capturing the biometric signal with the camera (Step 1). It then interacts with the Keyless network to generate a new user identifier (Keyless ID), which is then returned to your mobile app (Step 2).
Authentication involves your application server, your mobile app, and the Keyless network, as depicted in Figure 2.
This process starts when the user performs an action that requires authentication using your mobile app (Step 1 in Figure 2). To this end, your app provides the details of this action to your application server, which generates a challenge. The challenge is sent to the mobile app, which uses the Keyless SDK to compute the corresponding authentication token using the authenticate
method (Step 2).
At this point, the Keyless SDK authenticates the user. First, it captures the user’s biometrics using the mobile device’s camera (Step 3). Then, it connects to the Keyless network, and runs a secure multi-party computation protocol that authenticates the user and generates the authentication token in response to the challenge provided in Step 2. This is shown in Figure 2 as Step 4.
The Keyless SDK returns the authentication token to the mobile app. The app sends the token to your application server, which verifies it. If the authentication token is valid, the application server completes the transaction and notifies your mobile app (Step 6).
Account deletion is similar to authentication. First, your mobile application performs authentication steps 1-6, with which it authenticates and notifies your application server that the user wants to delete the account. Next, your mobile app invokes the deEnroll
method from the Keyless SDK. This method issues a deletion request to the Keyless network (Step 7). The request removes all data associated with the user from Keyless.
Keyless SDK provides three officially-supported configurations for the liveness detection (antispoofing component), listed below from the lowest to the highest level of security:
PASSIVE_STANDALONE_MEDIUM
PASSIVE_STANDALONE_HIGH
PASSIVE_STANDALONE_HIGHEST
PASSIVE_STANDALONE_MEDIUM is intended for testing purposes only. We recommend to use PASSIVE_STANDALONE_HIGH or PASSIVE_STANDALONE_HIGHEST in production.
Generally speaking, increasing the security level will increase the ability of the system to reject spoof attempts (true positive rate, or TPR). A higher security level will also increase the genuine reject rate (false positive rate, or FPR) and the time required by the anti-spoofing module to make a decision.
For most production scenarios, Keyless recommends the use of PASSIVE_STANDALONE_HIGH
. This setting offers a good tradeoff between TPR, FPR, and time-to-decision. For scenarios that require a higher security level, we recommend increasing this setting to PASSIVE_STANDALONE_HIGHEST
.
To customize the liveness detection you simply have to call .withLivenessSettings(livenessConfiguration, livenessTimeout)
when initializing any configuration.
During the de-enrollment process, a user’s face is processed and compared to the one which was previously stored during the enrollment process, similar to authentication process. If it is successful, user will be de-enrolled and their account will be removed from the Keyless network.
This operation is irreversible, therefore we suggest to display a pop-up to confirm the operation before proceeding with the de-enrollment.
Using withLivenessSettings
you can specify the liveness security level with LivenessConfiguration
and a timeout
to perform the liveness.
Using withDelay
you can specify the delay (in seconds) before the liveness starts. This will not prevent the camera from starting, it will just delay the liveness analysis start.
Enrollment creates a Keyless account. You can think of "enrollment" as a "register/signup" process. During the enrollment Keyless ties the user's face biometrics to the Keyless account.
For the enrolment, a full face image is required and the process cannot be completed if any occlusion is present, e.g. a face mask.
You can customize the enrollment with optional methods from the EnrollmentConfiguration
builder. The full EnrollmentConfiguration
is available below:
Depending on the builder methods you enable, Keyless will populate the corresponding fields in the EnrollmentSuccess
result reported below. Not all builder methods produce a result as output that is why you have less fields in output than the number of methods of the builder.
it is possible to protect with the user's face biometrics a "secret" that you provide as input.
Depending on your application logic, you can choose to use different secrets.
Your custom secret could be a secret that you have provided to the app from the backend, the seed of an OTP protocol, or anything else. If you only need to know just the result of the authentication (success/failed), you can provide any constant value as token.
Keyless accepts only ASCII strings as custom token.
Using the savingSecret
method you can specify an ASCII string to store securely with Keyless. You can retrieve the secret later on after a successful authentication.
Keyless can generate backup data useful to recover an account.
You are responsible to store the backup data securely.
To retrieve the backup data use retrievingBackup
method. Once the enrollment succeeds you can read the backup data in the EnrollmentSuccess
result.
To recover and account you can enroll with backup data that you retrieved and stored in the past. To recover an account use withBackup
passing as parameter the backup data.
Using withLivenessSettings
you can specify the liveness security level choosing the options from LivenessConfiguration
.
You can also specify a timeout
(in seconds) to cancel the enrollment if the liveness takes longer than the timeout.
withOperationInfo
specifies an operation identifier and payload stored on the Keyless backend if the enrollment succeeds.
Each operation id must be unique, you will get an error if you re-use the same operation id.
Using withDelay
you can specify the delay (in seconds) to delay the liveness start. The camera preview appears but the liveness processing waits for the specified delay before starting.
Only available to some customers. If you are not eligible you will get an error.
Using withEnrollmentSelfie
you can retrieve the image from which Keyless computes the biometrics of the user. The image can be found in the EnrollmentSuccess
result.
If you enrolled users from a different source than the mobile SDK (e.g. Keyless Agent), you need to sync the mobile SDK with the state returned by the Keyless Agent.
To synch the mobile SDK enroll providing the "temporary state" or "shared state". Specify withTemporaryState
in the EnrollemntConfiguration builder.
The UI is the UI for the authentication even if you called an EnollmentCondifuration. This is expected since from the user perspective the enrollment was already performed previously.
If the biometrics match, Keyless authenticates the user.
You can customize the authentication with optional methods from the AuthenticationConfiguration
builder.
The full AuthenticationConfiguration
is available below:
Depending on the builder methods you enable, Keyless will populate the corresponding fields in the AuthenticationSuccess
result reported below. Not all builder methods produce a result as output that is why you have less fields in output than the number of methods of the builder.
If you add the method to the builder Keyless will populate the field customSecret
in the AuthenticationSuccess
result.
Keyless can generate backup data useful to recover an account.
You are responsible to store the backup data securely.
To retrieve the backup data use retrievingBackup
method. Once the enrollment succeeds you can read the backup data in the EnrollmentSuccess
result.
To recover and account you can enroll with backup data that you retrieved and stored in the past. To recover an account use withBackup
passing as parameter the backup data.
You can find the backup
as outpu in the AuthenticationSuccess
result.
Using withLivenessSettings
you can specify the liveness security level choosing the options from LivenessConfiguration
.
You can also specify a timeout
(in seconds) to cancel the enrollment if the liveness takes longer than the timeout.
withOperationInfo
specifies an operation identifier and payload stored on the Keyless backend if the enrollment succeeds.
Each operation id must be unique, you will get an error if you re-use the same operation id.
Using the withMessageToSign
method it is possible to specify a message (string
) that will be signed by the user signing key.
If the authentication is successful, you will find the signedJwt
in the AuthenticationSuccess
.
The signedJwt
is a jwt verifiable using the user signing public key returned by the getUserSigningPublicKey
api.
Using withDelay
you can specify the delay (in seconds) to delay the liveness start. The camera preview appears but the liveness processing waits for the specified delay before starting.
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 Keylss SDK will also display a map of key value pairs to users. 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
.
We do NOT perform any validation of your custom payload. You are responsible for the payload displayed to users.
We expect a payload that conforms to the following structure:
Using withSuccessAnimation
you can specify whether the Keyless SDK should display a checkmark indicating a successful authentication to the user.
addingNewDevice
confirmingNewDevice
revokingDevice
The Keyless SDK "caches" the enrolled user locally on the device.
The Keyless SDK offers a way to check if you are in this situation: you can use the validateUserAndDeviceActive
API. This will validate that both the user and the device are still "active" (i.e. they exist) in the Keyless backend.
You may want to call validateUserAndDeviceActive
before an authentication to avoid going through the user biometric extraction if the user has been deleted.
To retrieve the user identifier you can use the Keyless.getUserId()
api
The device is identified by means of its public signing key. To retrieve the device identifier you can use the Keyless.getDevicePublicSigningKey()
api:
Sometimes it may be useful to reset the Keyless SDK to a clean state.
Note: this will not de-enoll the user from the Keyless backend or deactivate the device from the Keyless backend.
After the reset the Keyless SDK local data will be deleted. You can use the Keyless.reset()
api to reset the Keyless SDK:
Details on how to query our backend for stored operations are available on .
Authentication authenticates the user. You can think of "authentication" as a "signin" process. During the authentication Keyless compares the user's face biometrics with the one previously computed during the .
Some methods are the same of the builder since those methods can be called both during enrollment and authentication.
If you saved a custom secret during , you can retrieve it using retrievingSecret
method.
Details on how to query our backend for stored operations are available on .
The following builder methods are coverdered in the section:
There are some use cases where it is possible to and . The Keyless SDK will not be notified about such deletions. For this reason if you try to authenticate a user or a device that have been deleted from server API you will get an error.
Each functionality exposed by the KeylessSDK may return an error; there're three classes of errors
Internal errors Triggered by Keyless internals.
Integration errors Triggered by a KeylessSDK integration misconfiguration.
User errors Triggered by some wrong user behavior.
Each error comes with a code and a description, useful to troubleshoot and resolve errors.
While the first two classes errors may be useful while integrating the SDK, the last one may require special attention.
Spoofing The user is trying to perform an operation placing a picture or a video in front of the camera.
Timeout The operation timed out
Mask detected The user is trying to perform an operation wearing a mask or there's other kind of occlusion that hides the face.
User cancelled The user manually cancelled the operation.
Face not matching The face of the user trying to perform an operation is different from the face of the user who is enrolled.
No network connection The device is offline.
User lockout The user is temporarily locked out of Keyless after too many failed authentication attempts.
Backups allow you to save and restore the user's Keyless account. This is useful to give the users the ability to restore their account if the app is deleted.
After each authentication it is possible to fetch the backupData
and the backupKey
and push them into your backup system. It could be Google Drive, iCloud or your cloud.
Each backup is encrypted with aes-gcm
using the backupKey
as symmetric key.
The backupData
and backupKey
are required to restore an account with Keyless. Save the Keyless backup info in a secure data store
It is possible to restore the user account providing the backupData
and the backupKey
to the Keyless SDK.
Using the withBackup
method it is possible to pass the object required to restore a backup.
The Keyless SDK can be customised in order to provide a more familiar UX when integrated in any custom app.
It is possible to customize the following colors:
Background color The background color of the enrollment screen.
Foreground color The color of the texts.
Primary color The color of the animated circle during the authentication.
Secondary color The color of the spinning dots during the enrollment.
It is possible to customize the following texts:
We suggest to not use more than three lines of text.
step 0 (information screen before enrollment)
title
description
prerequisitesHeader
prerequisiteAloneInPhoto
prerequisiteDirectLook
prerequisiteWellLitArea
continueCta
step 1
text 1 Showed before the user face is framed.
step1Success
message Showed after the user face is framed with a successful animation.
step 2
text 1 Showed after the user face has been framed and the progress is between 0% and 33%.
text 2 Showed after the user face has been framed and the progress is between 34% and 66%.
text 3 Showed after the user face has been framed and the progress is between 67% and 100%.
step 3
text 1 Showed when the enrollment has been successfully completed.
We suggest to not use more than two lines of text.
step 1
text 1 Showed before the user face is framed.
step 2
text 1 Showed after the user face has been framed.
step 3
text 1
Showed when the authentication has been successfully completed.
It is possible to customize the font face (iOS only) and size for two kinds of fonts: regular and small.
You can show your custom logo during Enrollment, Authentication and de-enrollment. It will be shown in the upper-right corner; any custom logo can be used, it will be resized but not stretched.
logo positioning may overlap with custom text depending on your custom text
Add your own image .png
in your /res/drawable
folder to set it using Keyless.UI.Logo.bitmap
property.
Add your own image to the app bundle and set it using Keyless.UI.Logo
property.
When a user is enrolled, device encryption and user signing keys are generated. These keys are accessible to the integrator and can be used for different purposes.
Return the device encryption key that could be used to encrypt a message which could be decrypted using the decryptWithDeviceKey(cipherText)
method.
This could be used for when a server wants to send data to the device that should not be accessible to any other device or intermediate services. The keyless SDK can decrypt data without biometric authentication.
Get public key: Keyless.getDeviceEncryptionPublicKey()
Decrypt data using private key: Keyless.decryptWithDeviceKey()
Return the user signing public key to verify the signature of a signed message. The message to sign could be provided to the authentication configuration using the withMessageToSign(message)
This could be used for non-repudiation and validation of transactions. The SDK can create an electronic signature on behalf of the user. This requires biometric authentication, as signing can only happen together with a biometric authentication attempt.
Get public key:
Android: Keyless.getUserPublicSigningKey(accountId)
iOS: Keyless.getUserSigningPublicKey(accountId)
Sign using private key: Keyless.authenticate()
Example
Before version 4.3.0 the "customToken" was saved by default during enrollment and retrieved by default during authentication.
Your custom token could be a secret that you have provided to the app from the backend, the seed of an OTP protocol, or anything else. If you only need to know just the result of the authentication (success/failed), you can provide any constant value as token.
The "customToken" is from now on referred to as "secret".
Starting from version 4.3.0 we require you to explicitly state that you want to save/retrieve a secret when enrolling/authenticating with Keyless.
From version 4.3.0 use savingSecret
instead of withCustomToken
.
From version 4.3.0 you need to add retrievingSecret
to the AuthenticationConfiguration
builder if you with to retrieve the secret you saved during enrollment.
Also to retrieve the secret upon successful authentication you must use result.customSecret
instead of the no longer supported result.customToken
.
Use Keyless to authenticate many users on a shared, non-trusted device.
Different Keyless users can use their Keyless account(s) on the same device.
The user is identified by user information stored in a "blob": UserInfo
. You can see the UserInfo
blob as a snapshot of the Keyless SDK for the current user.
You can decide to populate the Keyless SDK with the UserInfo
that you retrieved in the past from the Keyless SDK.
You are responsible to store the UserInfo
securely in your application or elsewhere in a custom vault.
You can retrieve the UserInfo
either during the enrollment or during the authentication by adding the retrievingUserInfo
parameter to the EnrollmentConfiguration
or the AuthenticationConfiguration
builders.
The EnrollmentSuccess
or the AuthenticationSuccess
will contain an optional parameter userInfo
that is a valid json containing the Keyless SDK snapshot for the current user.
Below you can find an example on how to retrieve the user information during an authentication:
To swap from a user to another you can set the user information using the setUserInfo(userInfo:String)
. After this call the SDK will be configured to perform all operations on the provided user extracted from the userInfo
json string provided as parameter.
If you never call setUserInfo
the Keyless SDK behaves as if there is only one default user.
Below is an example to set the user information from a UserInfo
blob that you retrieved in the past from the Keyless SDK:
Using Multiple devices with one Keyless account
This process enables Keyless users to add and use multiple devices to their Keyless account, without the need to go through the enrollment process with each new device.
A Keyless device is identified by an ID (a signing key) and it contains any additional info specified
during the enrollment in the withDeviceInfo
method;
when adding a a new device in the setupNewDevice
method;
Let's call the device you want to add the "new device" and any device already enrolled in the Keyless network "old device".
The old device must be enrolled with Keyless.
The new device must not be enrolled with Keyless.
The first step starts with the new device; the Keyless SDK will generate and encrypt the required data to add the new device to the Keyless network. In this step it is also possible to pass any additional info you want to associate to the device (similar to the withDeviceInfo
method in the enrollment).
Grab the KeylessNewDeviceData
object containing the new device data.
You should now share the newDeviceData
with your "old device". In fact, it is your "old device" that will add the "new device" to the Keyless network.
The second step needs to be performed on the "old device" and it will require an authentication passing the newDeviceData
.
This informs your "old device" to add your "new device" to the KeylessNetwork.
Using .addingNewDevice
in the AuthenticationConfiguration
will output some encrypted data: oldDeviceData
. The integretor is responsible to pass this oldDeviceData
to your "new device". You can see this oldDeviceData
as a confirmation blob necessary to complete the new device registration.
The third and last step is performed on the "new device". Authenticating providing the oldDeviceData
from the previous step will finalize the "new device" registration with the Keyless network.
It is possible to revoke any device for a given identifier. Revoking a device will make it impossible for the user to authenticate. Devices' identifiers are returned by the Keyless.getDevicesList
method.
The Keyless Agent serves as an on-premises backend service, providing APIs that accept user frames as input and generate Enrollment data necessary for initializing new Keyless Users. It is designed to be installed within the Customer's infrastructure.
This agent offers seamless registration of new users and integrates seamlessly with existing onboarding flows, ensuring a smooth and efficient user experience.
The following guide is solely focused on the Onboarding process with the Keyless Agent.
Steps
IdV collects Selfie Frame and Document data (included document picture)
IdV performs document check + face comparison (between Selfie frame and Document picture)
IdV returns the Selfie frame to the Customer backend
Customer backend interacts with the Keyless Agent to enroll a new user
Customer backend retrieves and store the KeylessClientState (needed to initialize the Keyless Mobile SDK)
Keyless allows to defer the actual user activation to a later time (optional) using the “commit” API
Use a PIN to perform specific operations when biometric authentication is not necessary
In some use-cases you may want to use an alternative authentication mechanism bypassing the biometric recognition (facial recognition). For those particular use-cases you can use the PIN as authentication mechanism.
Keyless requires at least one authentication mechanism to be present so you cannot enroll a user without any authentication mechanism and it is not possible to remove the authentication mechanism if it is the only one available for a specific user.
The possible authentication mechanism are:
biometrics (user face embeddings)
pin (secure code)
For retro-compatibility: if no authentication mechanism is specified biometric will be used by default.
To use the PIN you only need to add the PIN parameter to the builder configuration as shown in what follows.
As for enrollment, to use the PIN for authentication specify the dedicated builder parameter:
To de-enroll you user using the PIN authentication mechanism specify the dedicated builder parameter:
Note: de-enrolling with PIN means de-enrolling the user, as a consquence the user biometrics will be deleted as well. If you do not want to de-enroll the user but still remove the PIN authentication mechanism please employ the PIN utilities.
To change the PIN use the Keyless.changePin
API:
To remove the PIN and keep the user enrolled use the Keyless.removePin
API:
For instructions on how to install and setup the SDK please refer to
PIN and biometrics authentication mechanisms are not equivalent in terms of feature they unlock. At the moment PIN authentication mechanism only supports
You cannot enroll with the PIN and the biometrics in the same enroll (for example also using in the same EnrollmentConfiguration
) to enroll several authentication mechanism you need to call the Keyless.enroll
twice, each time with the authentication mechanism you want to enable.
Recall At the moment PIN authentication mechanism only supports
This API allows for backend-to-backend communication between your backend and the Keyless servers.
All defined API Endpoints require the following Header set to
X-Api-Key: <SECRET_API_KEY>
All defined API Endpoints are reachable under the primary URL:
https://api.keyless.io
The following API is to be sent to the deployed instance of the Keyless Agent by sending a picture
This set of API calls allows you to make operations on various Keyless users.
This set of API calls allows you to fetch and manipulate Keyless enabled devices.
This set of API calls allows you to fetch operations on various Keyless entities.
Management Portal is a tool which helps you monitor various user activities on your system such as enrolment and authentication, as well as enabling you to de-enroll users as well as individual devices manually.
It contains a lot of aggregated statistical data which can help you analyse how is your system being accessed.
Currently, you will have to request from the Keyless team to provide credentials to you. The same applies if you forget your credentials.
In the future updates, this will be replaced by an automated flow.
Once logged in, you will see several tabs on the top bar available to you:
Overview - Displays system health status and provides various statistical data
System Log - Displays logs for all user actions, separated by action type
Users - Displays all relevant information about your end users
Devices - Displays all relevant information about your end users' devices
On the far right, there is a "Logout" button which logs you out of the portal when clicked.
Aside from that, on the bottom bar you will find:
Privacy - Link to Keyless Privacy Policy section
Support - Link to Keyless Support Center which contains all relevant integration and end user guide and Live Support
Feedback - Link to provide product feedback to us. We are always eager to hear what we could do to improve your experience!
When you visit the portal page dash.keyless.io, you will land on the login page. Here you should input your username and password combination, then click "Submit" to login.
If the username/password combination is not correct, you will not be able to login. In case you forget your credentials, please reach out to Keyless Customer Support.
Upon logging in to the portal, you will land on the Overview page. On the top of the page, you will see various information about your biometric authentication system:
System status Shows any issues in Keyless internal system
Last Update When was the last time the data on the page was updated
Generate Report Button to generate the report out of the statistical data on this page for presentation and analysis purposes
Several widgets are available for you to analyse the usage of how your biometric authentication system is being used:
Users Enrolled All-time Shows the number of users who have been enrolled into your system since you started using Keyless
Authentications All-time Shows the total number of authentications in your system since you started using Keyless
Devices Enrolled All-time Shows the number of devices which have been enrolled into your system since you started using Keyless
Authentications in last 7 days, per day Shows the number of authentications in the last 7 days for each day with a trend line
Percentage of successful authentications in the last 7 days Shows all of the authentication attempts in the last 7 days, split into successful and failed authentication attempts
Top 5 reasons for authentication failures in the last 7 days Shows the error codes for most frequent authentication errors from all failed authentication attempts in the last 7 days
Total number of users, all time Shows all users in the system split into categories of active and deleted
Percentage of successful enrolments in the last 7 days Shows all of the enrolment attempts in the last 7 days, split into successful and failed enrolment attempts
Enrolments in the last 7 days, per day Shows the number of enrolments in the last 7 days for each day with a trend line
All of the widgets mentioned here are shown in the report which you can generate at the click of a button, as explained above.
This page displays all logs for all user operations at a glance.
It consist of three sections:
Time and date filter Changing the timeframe in this filter will impact the log data shown below in the widgets and table sections. As you change the values in the “From” and “To” fields, data shown below will reflect your new chosen timeframe.
Widgets
Percentage of successful authentications in the last 7 days Shows all of the authentication attempts in the last 7 days, split into successful and failed authentication attempts
Percentage of successful enrolments in the last 7 days Shows all of the enrolment attempts in the last 7 days, split into successful and failed enrolment attempts
Top 5 reasons for authentication failures in the last 7 days Shows the error codes for most frequent authentication errors from all failed authentication attempts in the last 7 days
Table with granular system information separated in tabs per type
Authentications
Enrollments
De-enrollments
Device Additions
Device Revocations
At the bottom of the page, there is a button to “Download CSV” with all of the data in the selected timeframe, displayed in CSV format.
When you click the “Visit User Page” button on the right side of the user’s name, you will land on this page. It provides all the information about a specific user.
On the right side of the username on the page, you have the button to manually de-enroll the user. Clicking the button will provide a confirmation pop-up and de-enroll the user upon confirming the action.
Below this section there are System Log and Devices sections.
System Log provides you with a time and date picker to filter the period for which you want to see specific authentication information for this user. You can also download this data in CSV format by clicking the “Download CSV” button at the bottom of the table.
Devices section will show all devices which the user has enrolled into the system. You can also download the list of devices in CSV format as for the section above.
Similar to the "Users" section, on this screen you can see all of the devices enrolled in your system.
There is a section with widgets and a table with device information.
Widgets
Top 5 devices in the last 7 days Identifies the devices which have been most active (largest number of authentication attempts recorded) in the last 7 days
Device enrollments in the last 7 days Shows the number of device enrolments in the last 7 days for each day with a trend line
Devices Table
In the table you can see information about each device: user it belongs to, when was it enrolled and when was the last used to authenticate. You can also download this data in CSV format by clicking the “Download CSV” button at the bottom of the table.
This page shows you the overview of all the users which have been enrolled in your system.
It consists of three sections:
Search bar
You can use the search bar to find a specific user by typing in their username. This will filter out the list of users below per your query.
Widgets
Top 5 users with most authentications in the last 7 days Identifies the user which have been most active (largest number of authentication attempts recorded) in the last 7 days
Enrolments in the last 7 days Shows the number of user enrolments in the last 7 days for each day with a trend line
Users Table
See the username, enrolment time and the time of the last authentication. You can access specifics about every user by clicking the “Visit User Page” button on the right side of each user.
At the bottom of the page, there is a button to “Download CSV” with all of your user data in the CSV format.
Upon landing on the Access Control page, you will notice three different keys you can manage here:
Secret API Key Used when calling out REST API from your backend
Mobile API Key Used in your mobile app when configuring our SDK
Download Key Used for downloading packages with our SDK in your mobile development environment
The following attributes are true per key type:
"Copy" button - You can use the "Copy" buttons where available to copy your key to the clipboard.
"Revoke" button - Using this button will revoke the previously generated key. This action is not reversible, but you will be able to generate a new key.
Key Type
Generated by User
Multiple keys can be created
Can be revoked
Secret can be viewed after creation
Mobile Key
NO
NO
NO
YES
Secret Key
YES
YES
YES
NO
Download Key
YES
NO
YES
YES
Successful Response
Return all pending operations associated with the tenant sdk key
Successful Response
The operation_id is the id previously passed to the Keyless backend by the Keyless Client SDK through an operation attempt or created up-front
Successful Response
Successful Response
Successful Response
Successful Response
Image of a user's face.
Enrollment data for a user
The id of a user in keyless system.
Opaque string with client state.
Opaque string with server state.
Delete all uncommitted users created before a given timestamp
Uncommitted users deleted
Commit the uncommitted user.
The user id
Server state committed
Delete the uncommitted user with the specified userId
The user id
Uncommitted user deleted
Create an uncommitted user from a user server-state generated by the keyless agent
Uncommitted user created