Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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.
You can configure the authentication process with optional parameters in your BiomAuthConfig()
instance or using the builder pattern methods from the AuthenticationConfiguration
builder.
The successAnimationEnabled
field has been renamed to showScreenSuccessFlow
, triggering a breaking change. Moreover the success animation is now shown by default.
Depending on the builder methods you enable, Keyless will populate the corresponding fields in the AuthenticationSuccess
result reported below.
Backup data is no longer recommended to perform account recovery use the temporary state. 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.
Use cameraDelaySeconds
to specify the delay (in seconds) between when the camera preview appears, and when the liveness processing starts.
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.
You can specify a payload to be added to a JWT signed by Keyless with the jwtSigningInfo
parameter, more in JWT signing.
Using livenessConfiguration
you can configure the liveness security level during enrollment. The possible liveness configuration are under LivenessSettings.LivenessConfiguration
:
You can also specify a livenessTimeout
(in seconds) to cancel the enrollment if the liveness takes longer than the timeout.
More details on liveness in the dedicated liveness settings section.
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.
Use the shouldRetrieveTemporaryState
parameter to creata a temporary state useful for the account recovery.
Enrollment is the process of registering a new user by connecting their facial biometrics to a Keyless account. During this process, a full and unobstructed view of the user's face is required.
You can configure the enrollment process with optional parameters in your BiomEnrollConfig()
instance or using the builder pattern methods from the EnrollmentConfiguration
builder.
Depending on the builder methods you enable, Keyless will populate the corresponding fields in the EnrollmentSuccess
result reported below.
Backup data is no longer recommended to perform account recovery use the temporary state. 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
method. Once the enrollment succeeds, copy the backup data from the EnrollmentSuccess
result, and store it securely.
To recover an account, use the backup
parameter more in backup.
Use cameraDelaySeconds
to specify the delay (in seconds) between when the camera preview appears, and when the liveness processing starts.
During enrollment you can specify a custom secret to be saved and encrypted along with the user's biometric data using savingSecret
paramter. The custom secret can be anything you can save as an ASCII string, such as a secret that you have provided to the app from the backend, the seed of an OTP protocol, or anything else.
Using shouldRetrieveEnrollmentSelfie
you can retrieve the image that Keyless uses to computes the facial biometrics of the user. The image can be found in the EnrollmentSuccess
result as enrollmentSelfie
.
Specifying an iamToken
you can authenticate with your IAM System, follow the guide authenticating in auth0 with Keyless
You can specify a payload to be added to a JWT signed by Keyless with the jwtSigningInfo
parameter, more in JWT signing.
Using livenessConfiguration
you can configure the liveness security level during enrollment. The possible liveness configuration are under LivenessSettings.LivenessConfiguration
:
You can also specify a livenessTimeout
(in seconds) to cancel the enrollment if the liveness takes longer than the timeout.
More details on liveness in the dedicated liveness settings section.
The parameter operationInfo
specifies a customizable unique operation identifier and associated payload stored on the Keyless backend if the enrollment succeeds. Use this to add an extra level of confirmation in your operations.
Details on how to query our backend for stored operations are available on Operations API.
Keyless users can be enrolled via IDV-Bridge, Identity Verification Bridge. As a result of IDV-Bridge enrollment you receive a temporary state useful to register users in your app without undergoing the full enrollment flow.
Use the temporaryState
parameter to register users from a temporary state obtained through IDV-Bridge or follow the account recovery guide.
Authenticate people, not just devices
To embed privacy-preserving biometric authentication in your mobile applications:
Step 1: Understand how the Keyless components interact with your application server.
Step 2: Understand a typical biometric authentication flow and how it interacts with your application.
Step 3: Follow the getting started guide for Android or iOS.
Learn about user and device management with the Admin portal.
Learn about user and device management with the RESTful API.
Learn how the Keyless components interact with your app.
Learn how the Keyless SDK components can be integrated into a mobile application and backend server, to enable biometric authentication.
To authenticate with Keyless, a user must first enroll their biometric template. Enrollment with Keyless consists of registering the user’s biometric features in a privacy-preserving manner using the various enrollment methods from the Keyless SDK.
The most common authentications scenarios for the Keyless SDK are:
access to a web application
access on a mobile application
In this scenario the user is trying access to a resource in a web application for which strong authentication is required. The web application backend sends a push notification to the customer app to request that the user identify themselves with Keyless. After biometric authentication is successful, the flow returns to the web application backend, which leverages the APIs exposed by the Keyless backend to perform additional security checks.
Once the Keyless backend confirms that the authentication was successful, the user is allowed access to the resource.
In this scenario the user is trying access to a resource directly in the mobile application for which strong authentication is required. The mobile application sends a push notification to the customer app to request that the user identify themselves with Keyless. After biometric authentication is successful, the flow returns to the mobile application backend, which leverages the APIs exposed by the Keyless backend to perform additional security checks.
Once the Keyless backend confirms that the authentication was successful, the user is allowed access to the resource.
As mentioned, Keyless is composed of two main blocks:
Keyless SDK
Keyless backend / Confirmation API Service
The Keyless SDK supports both Android and iOS, and exposes API methods to interact with the Keyless Privacy-Preserving Network to perform the following actions:
Enroll a user
Authenticate
De-Enroll
Restore backup
The Keyless SaaS backend offers 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.
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.
During enrollment, your mobile app invokes the enroll
method from the Keyless SDK, and then:
Guides the user through capturing a biometric signal with the device camera.
Interacts with Keyless to generate a new user identifier (Keyless ID), which is then returned to your mobile app.
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.
The 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.
The Keyless SDK authenticates the user by capturing the user’s biometrics using the mobile device’s camera.
The Keyless SDK 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. 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.
Account deletion is similar to authentication. First, your mobile app performs authentication steps 1-6, then it 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 the Keyless network.
De-enrollment is biometric equivalde of an account deletion. Keyless performs an authentication to compare the user's facial biometrics with the ones computed during enrollment. If the biometrics match, the user is authenticated and their account will be removed from Keyless. This operation is irreversible.
Use cameraDelaySeconds
to specify the delay (in seconds) between when the camera preview appears, and when the liveness processing starts.
Using livenessConfiguration
you can configure the liveness security level during enrollment. The possible liveness configuration are under LivenessSettings.LivenessConfiguration
:
You can also specify a livenessTimeout
(in seconds) to cancel the enrollment if the liveness takes longer than the timeout.
More details on liveness in the dedicated liveness settings section.
The Keyless SDK "caches" the enrolled user locally on the device.
There are some use cases where it is possible to delete the user from server API and delete the device from server API. 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.
Call validateUserAndDeviceActive
before authenticating, to validate that both the user and the device are still active in the Keyless backend, to avoid asking the user for biometric data which will still not let them authenticate.
Retrieve the user identifier with Keyless.getUserId()
:
The device is identified by its public signing key. To retrieve the public signing key use Keyless.getDevicePublicSigningKey()
:
Resetting the Keyless SDK to a clean state deletes local data from the device, but does not de-enoll the user from the Keyless backend or deactivate the device from the Keyless backend:
The getRateLimitInfo
API checks whether the user is currently rate-limited and, if so, for how many seconds. This API is typically used to provide feedback to users after multiple failed authentication attempts.
The Keyless SDK uses three classes of errors, each error has a code and a description:
Internal errors: triggered by Keyless internals.
Integration errors: triggered by a KeylessSDK integration misconfiguration.
User errors: triggered by user behavior.
If you're implementing the Keyless SDK, you should handle these errors so they are not displayed to the end user. User errors are most likely to require application logic, and are explained in more detail below.
Note that many of these errors are predictions only, when writing messages for your users it's often best to assume positive intent. For example, suggest that they make sure that nothing is obstructing the camera instead of suggesting that are attempting to spoof.
The user might be placing a picture or a video in front of the camera.
The operation timed out.
The user might be wearing a mask, or there might be something hiding their face.
The user manually cancelled the operation.
The face of the user trying to perform an operation is different from the face of the user who is enrolled.
The device is offline.
The user is temporarily locked out of Keyless after too many failed authentication attempts.
Backup data is no longer the recommended approach to perform account recovery. The recommended flow is using the temporary state. Follow the guide on account recovery.
Back up your user's data so you can restore their Keyless account when necessary.
Create backups after authentication, and push them into your backup system. Each backup is encrypted with aes-gcm
using the backupKey
as symmetric key. You need both backupData
and backupKey
to restore an account with Keyless.
Restore the user account by providing backupData
and backupKey
to the withBackup
method:
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.
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
Review the Keyless SDK requirements:
The Keyless SDK uses
Android 6.0 (API level 23) and above
The Keyless SDK uses
Set up a physical iOS device for running your app and enable the following permissions:
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
):
The Keyless SDK uses
Flutter 3.0 or higher
Dart 3.0 or higher
All requirements from both Android and iOS platforms
Set up the required permissions as described in the Android and iOS tabs.
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.
If you use Proguard, add the following rules to your Proguard configuration file:
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.
In the dependencies
block of your project build.gradle
file, typically app/build.gradle
, add:
In the android
block of your project build.gradle
file, typically app/build.gradle
, make sure you have the following options:
Create a Podfile if you don’t already have one
Set up Cocoapods to use your Cloudsmith credentials, by running the following commands, replacing YOUR_CLOUDSMITH_TOKEN
with the Cloudsmith token provided you by Keyless.
Add the KeylessSDK pod to your Podfile
Add the following at the bottom of you Podfile
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.
Add the Keyless SDK repository
Add the Keyless SDK dependency to your pubspec.yaml
:
Follow the installation steps in both the Android and iOS tabs to set up the native SDKs in their respective platforms.
Run flutter pub get to download the dependencies:
There is some essential configuration to do before you can use the Keyless SDK.
Initialize the Keyless SDK in your Application
class:
Add your application to the Manifest
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:
Create an instance object of Keyless.SetupConfiguration
and pass it to the Keyless.configure
method, typically this is done in your app’s application(:didFinishLaunchingWithOptions: method:).
Initialize the Keyless SDK in your Application
class:
Add your application to the Manifest
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 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:
Create an instance object of Keyless.SetupConfiguration
and pass it to the Keyless.configure
method, typically this is done in your app’s application(:didFinishLaunchingWithOptions: method:).
Configure the Keyless SDK before using any of its features:
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 is disabled by default.
Please note logs do not include any Personally Identifiable Information (PII).
Keyless allows you to:
enable logging to the Keyless infrastructure - keylessLogsConfiguration
collect logging for you own analytics without sending them to the Keyless infrastructure - customLogsConfiguration
Collect logs after setting up custom logging with customLogsConfiguration
option:
Start collecting the Keyless.customLogs
flow (This must happen before a Keyless.configure()
to get all Logs Events):
Configure the SDK with the following SetupConfig
:
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)
Keyless has both client side (applicable to a specific device) and server side (applicable to all users and devices) lockout policies to help prevent brute force attacks.
Client side lockout is configurable in the SDK, and 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
) on that device.
Account lockoutDuration
must be greater than or equal to the lockoutAttemptsResetAfter
so that it is not reset by lockoutAttemptsResetAfter
.
Server side lockout works similarly, except applies to all authentication devices for a specific user, and is configured to lock a user out for 10 minutes after 5 failed attempts. A successful login resets the count of failed authentication attempts to zero.
Checking for rooted/jailbroken phones is an unreliable process but you can enable the check with tamperedDeviceCheck()
. 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.
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.
This is the target desired number of circuits shared between client and server. To set this number use the numberOfSharedCircuits
.
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
:
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
- for testing purposes only
PASSIVE_STANDALONE_HIGH
- for most production use (SDK default)
PASSIVE_STANDALONE_HIGHEST
- for higher security production use
Increasing the security level increases the ability of the system to reject spoof attempts (true positive rate, or TPR). A higher security level also increases 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 call .withLivenessSettings(livenessConfiguration, livenessTimeout)
when initializing any configuration.
The Keyless SDK can be customised in order to provide a more familiar UX when integrated in any custom app.
The SDK theme can be customized to be dark
, light
or system
.
Keyless will use the system defined theme by default.
It is possible to customize the following colors:
primary color This color is the one that appears most frequently across the screens and components.
onPrimary color The color used for elements that appear on top of the PrimaryColor, ensuring clear contrast and visibility.
It is possible to customize the following text:
We suggest to not use more than three lines of text.
Step0 (information screen before enrollment)
title
description
prerequisiteCenterFace
prerequisiteDirectLook
prerequisiteWellLitArea
prerequisiteRemoveEyeWear
continueCta
closeScreenButtonContentDescription (the content description of the close button for accessibility)
prerequisiteAloneInPhoto deprecated (will no longer be shown)
Step1
text1 Showed before the user face is framed.
step1Success
message Showed after the user face is framed with a successful animation.
Step2
text1 Showed after the user face has been framed and the progress is between 0% and 33%.
text2 Showed after the user face has been framed and the progress is between 34% and 66%.
text3 Showed after the user face has been framed and the progress is between 67% and 100%.
subtitle1 Showed during the entire enrollment progress
Step3
text1 Showed when the enrollment has been successfully completed.
subtitle1 Showed when the enrollment has been successfully completed
We suggest to not use more than two lines of text.
Step1
text1 Showed before the user face is framed.
Step2
text1 Showed after the user face has been framed.
Step3
text1
Showed when the authentication has been successfully completed.
It is possible to show or hide some of the Enrollment and Authentication steps above by setting to false
the following fields.
The default value for all of them is true
which means that the step is shown.
Use the following fields of a BiomEnrollConfig
:
showScreenInstructions
: affects the Step0
showScreenSuccessFaceCapture
: affects the Step1Success
showScreenSuccessFlow
: affects the Step3
Use the following fields of a BiomAuthConfig
:
showScreenSuccessFlow
: affects the Step3
It is possible to customize the font.
Android: requires an android.graphics.Typeface
object.
iOS: requires a String
, the name of the font.
The custom font must be set as soon as available, a good moment to do so is before calling Keyless.configure
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.
For a seamless SDK integration make sure to follow the section .
You can check all the prerequisites that your app must meet for a successsful SDK integration under the .
Please note releases marked as release candidate - rc
are available to select customers in advance of the official release via partners-rc
cloudsmith repo. Please note regression tests and QA activity is incomplete and we strongly advise against shipping these versions into production environments.
release candidate
Improved biometric performances
Highlights
UX: optional screens - it is now possible to opt-out the optional screens you don’t wish to show -
Enhancement: query remaining lockout time -
UX: optional screens
We understand that the experience our customers create for their end users is of the utmost importance. To provide greater flexibility, we’ve made certain screens and steps in the Authentication and Enrollment flows optional. These screens will remain visible by default, but you now have the ability to opt out of displaying those that are not relevant to your workflow. For more details, please refer to the .
Please note that the camera view and Step 2 (“Enrollment Progress”) will remain mandatory for now, as they are critical to ensuring liveness detection and security during the capture process. However, Step 2 is highly customizable in terms of text and color scheme to align with your branding.
In upcoming releases, we will also be adding sample code and “User Flow” guides to further empower integrators and designers in tailoring their user experience.
Enhancement: query remaining lockout time
Customers can configure the maximum number of errors a user can make before being locked out for a 10-minute period.
This enhancement enables customers to display the remaining lockout time to users at any given moment, improving transparency and user experience.
Bugs and Fixes
Fix (Android): Resolved a compatibility issue between the Compose Material library and Flutter.
Feature: possibility to specify a path to Keyless artifacts. Artifacts are provided by Keyless by default. Artifacts path can be overridden by the customer.
Fix: remove lottie dependency
UX: remove success animation in favor of static image
API Surface: deprecate builder pattern in favor of optional config constructor parameters (builders are deprecated)
Bugfix: internal data cleanup
Performance improvements: avoid unnecessary assets extraction
Feature: Shared Circuits: integrators can now set the desired number of shared circuits when calling an sdk configure Fix: Liveness: update liveness setting for higher security
Feature: enroll with Keyless from an Auth0 user’s IdToken
Dynamic linking feature: new API exposing interface to choose one authentication method (BiomAuthConfig | PinAuthConfig)
UI customization: it is now possible to customize the font for Keyless SDK screens
UI customization: it is now possible to customize the brand color (primary accent color) for Keyless SDK screens
Integrating the Keyless authentication mechanism with existing IAMs requires some preliminary work on various parts of the customer’s Service Provider:
Binding of the user’s Auth0 identity with a Keyless ID: this happens via Keyless Enrollment. The user performs a normal enrollment with an option in the configuration that accepts an idToken
, coming from Auth0. This can be retrieved via standard Auth0 login flow.
Account linking: After the user’s idToken
has been bound to a Keyless Identity, the Auth0 authentication with Keyless will succeed. This authentication, though, returns a different user_id
. This is because the Auth0 user_id
and the Keyless user_id
have not been linked. There are many tutorials on how to perform
Create a secure connection between Keyless and Auth0, allowing you to leverage Keyless as an Identity Provider in Auth0.
Before following this guide, contact the Keyless Delivery Team to get the following information:
Discovery URL:
https://idp.keyless.io/realms/YOUR_REALM/.well-known/openid-configuration
Client ID: Will be provided by Keyless Delivery team.
Client Secret: Will be provided by Keyless Delivery team.
Scopes: Include any additional scopes you want to request (e.g., openid, profile, email).
Log in to your Auth0 account and navigate to the Dashboard.
In the Dashboard, go to Authentication > Enterprise > OpenID Connect.
Click Create Connection
Name: Enter a name for your connection (e.g., Keyless-SDK-Connection).
Issuer URL: Enter the Discovery URL provided by the Delivery team
Test the Connection by logging in with a test user and navigating to the Try Connection option in the Auth0 Dashboard.
In the Auth0 Dashboard, go to Applications > Applications.
Select the application you want to connect to Keyless, navigate to the Connections tab, and enable the newly created Keyless connection.
Once everything has been set up, specify the name of the Auth0 connection you’ve just created as part of the /authorize
endpoint of Auth0 within the SDK configuration.
This step can vary considerably by implementation. Contact the Keyless Solution Engineering team to discuss the best approach for your setup.
To enroll a user,
Retrieve the id_token
from Auth0
Perform a Keyless Enrollment, providing the id_token
into the withIAMToken
builder function:
Once the Enrollment phase completes successfully, authenticate the user.
Two preliminary steps are necessary before authentication:
Generatie a cryptographically secure UUID that we’re going to call operationId
Retrieve a value called keylessId
via the getUserId()
API.
Concatenate the UUID and keylessId
to produce the login_hint
: login_hint = <operation_id>;<keyless_id>
Authenticate with Keyless providing the operationId
:
Once successfully authenticated, launch a custom tab to log in with Keyless via Auth0, providing the login_hint
previously built as a parameter with key login_hint
.
Once you’re given access to the Keyless Dashboard by our tech support team, configure the OpenID URL in the Keyless Dashboard, o
Open the Access Control page.
Click on the IDP Configuration tab, this will redirect you to another page which contains what we’re looking for, the OpenID Configuration.
Set the OpenID Configuration URL please type a valid OpenID URL, here some examples of valid URLs:
https://yourdomain.auth0.com/.well-known/
https://yourdomain.auth0.com/.well-known
https://yourdomain.auth0.com/
https://yourdomain.auth0.com
Click the Save Configuration button.
Keyless is able to recover an account from what we refer to as temporary state.
The temporary state is obtained:
from your backend through Keyless Identity Verification Bridge. More in .
from your client app using the Keyless Mobile SDK.
What follows refers to option 2: obtain the temporary state from the Keyless Mobile SDK.
The Keyless temporary state contains all the necessary information to restore an account. It can be created during enrollment and authentication.
To create and use the temporary state Keyless requires the user biometric.
The temporay state internals are not important but you can expect a string similar to the following that you should pass as-is to recover the account:
Use the shouldRetrieveTemporaryState
parameter of the BiomEnrollConfig
or BiomAuthConfig
depending if you want to retrieve the temporary state during enrollment or authencation flows.
Dunring the enrollment flow:
During the authentication flow:
During the enrollment flow:
During the authentication flow:
Pass the temporary state during the enrollment flow to recover the account. The temporary state is the one you obtained and stored securely in the previous step.
When enrolling from the temporary state, Keyless shows the authentication UI to users. In the past users already went through the enrollment "onboarding" flow, we can reduce the friction in account recovery performing the authentication flow.
For technical reasons developers need to call Keyless.enroll
instead of Keyless.authenticate
even if the UI is the one from authentication flow.
The account is recovered and it's now possible to authenticate the user.
Keyelss mobile SDK can generate a signed a JWT containing a custom payload. You can use the signed JWT to implement .
Pass JwtSigningInfo
to the authentication to generate a signed JWT:
The AuthenticationSuccess contains the following fields:
signedJwt
: the signed JWT.
Use a PIN to perform specific operations when biometric authentication is not necessary
For authentication scenarios that don't necessitate biometric recognition, you can use PIN as an alternative.
PIN authentication has limited capabilities compared to biometric authentication. PIN supports:
,
,
Keyless requires at least one of the following authentication factor to be present for each user:
biometric factor
PIN factor
PIN factor can be any valid String
. Numbers are not enforced but are recommended, given the familiarity of numeric PINs for end users.
To enroll using the PIN factor create the following configuration:
To enroll multiple authentication factors you need call Keyless.enroll
for each factor.
To authenticate using the PIN factor create the following configuration:
To de-enroll using the PIN authentication factor, create the following configuration:
To remove the PIN factor, while still keeping the biometric factor, perform a biometric authentication using the following configuration:
To change the PIN use the newPin
parameter in the PinAuthConfig
:
To remove the PIN factor and keep the user enrolled with the biometric factor use the shouldRemovePin
parameter in PinAuthConfig
:
You can leverage the Keyless authentication mechanism to sign unrelated transactions, including Strong customer authentication (SCA) transactions.
Payment service providers compliant with are required to:
Generate an authentication code specific to the amount of the payment transaction and the payee agreed to by the payer when initiating the transaction
Make the payer aware of the amount of the payment transaction, and of the payee
Keyless helps you by:
protecting the authentication code that you use for dynamic linking.
displaying and signing the information to make the payer aware of details of the transaction.
Keyless is not a payment service provider. Keyless won't issue an authentication code tied to the transaction information.
By adding Keyless to your checkout flow you also benefit from .
SCA requires authentication to use at least two of the following three elements.
Something that only the customer knows. For example, a password or PIN.
Something that only the customer has. For example, a mobile phone or hardware token.
Something that the customer is. For example, a biometric such as a fingerprint or face.
With Keyless Passwordless MFA you can satisfy the last two points from the list above.
The following sections contain some examples on implementing SCA with Keyless.
Keyless displays a screen containing a list of labels and associated information on your behalf.
For this reason, the format of the dynamicLinkingInfo
must be a jsonArray containing jsonObjects (key/value pairs). We expect a valid JSON as follows:
This information is added to the Authentication request that the user needs to approve.
Once the user approves the transaction data, Keyless starts the authentication to:
Authenticate the payer with the device factor and the biometric factor using Keyless MFA.
Tie the transaction data to the Keyless MFA
To tie the transaction data to the Keyless MFA, populate the parameter dynamicLinkingInfo
of the authentication configuration AuthConfig
. Add the authentication code or any other information you want to display to the user and sign with Keyless MFA. For example, add the "authentication code".
Keyless can produce a signed JWT containing a claim titled td
(transaction data) that contains the payload you passed as dynamicLinnkingInfo
.
Keyless is not storing history of records about the transaction amount, the payee, the payer and the authentication code.
If the authentication is successful, the AuthenticationSuccess
contains the following fields:
signedJwt
: the signed JWT (specs below).
Congrats, you just performed a Strong Customer Authentication displaying and signing the transaction information.
This API allows for backend-to-backend communication between your backend and the Keyless servers.
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.
Based on customer feedback, we’ve enhanced this feature to allow querying the remaining lockout time (in seconds) after a user has been locked out. For implementation details, please refer to the .
UX: SDK Theme is customizable by customer -
Feature: improved PSD2 compliance -
Feature: account recovery -
Feature: expose SDK logs to customer app -
Feature: expose JWT signature compatible with core backend key pairs -
Before performing Enrollment and Authentication, follow to using the Keyless SDK.
Note that de-enrolling deletes the user biometric factor as well as the PIN factor. If you just want to remove the PIN authentication factor, use the instead.
The transactionData
contained in dynamicLinkingInfo
must respect the format to .
Verify the JWT using the public key from .
Get a user's pending operations
The user id
An user's pending operations
Unique operation identifier set and managed by the client
Operation payload set and managed by the client
User id set and managed by the client
Authentication type of the operation
Get a customer operation
Unique operation identifier set and managed by the client
A customer operation
Unique operation identifier
Creation date time
Name of the service that created the operation
An HEX string representing the user id
Customer SDK api key
User id set and managed by the client
Unique operation identifier set and managed by the client
Operation payload set and managed by the client
True if the operation is approved, false otherwise
Authentication type of the operation
State of the operation. Possible values are 'approved' or 'pending'
Create a pending operation
The user id
User id set and managed by the client
Unique operation identifier set and managed by the client
Operation payload set and managed by the client
Operation created successfully
Always true
Get the customer public key in PEM format
The public key in PEM format
PEM key representation of the customer public key
"-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwJ1\n-----END PUBLIC KEY-----"
Verify a signed JWT message. The only format accepted for now is a JWT generated by a PIN signature
The signed JWT message
The verification completed successfully. Check the result to see if the signature is valid or not
True if the signature is valid, false otherwise
Delete an user and all associated entities
The user id
User successfully deleted
Always true
Get user devices
The user id
User devices
An HEX string representing the user id
Customer unique identifier
Device public signing key
Device public encryption key
Device state
Device operation system version
Device's SDK version
Deletion date time
Delete user device
The user id
Public signing key
Device successfully deleted
Always true