IDV Bridge On-Premise

This page covers the fundamentals that customers need be aware of when installing Keyless Agent - the IDV Bridge On-Premise solution.

Introduction

IDV Bridge allows our customers to take the user portraits ("selfies") of their users that have been captured in previous identity processes and use these to register them into the Keyless system. In doing so they can be leveraged to support future facial biometric authentication without customers having to take any additional steps.

This guide takes you through the key features and elements within IDV Bridge On-Premise (“Keyless Agent”) that you need to be aware of. Further to this we have created a runbook for integrators who want to execute Keyless Agent as well as an optimization guide to understand throughput options and expectations.

Offline/Online enrollment

There are two modes that the Keyless agent can run-in:

• Offline Enrollment

  • As the name suggests this mode ensures that, at the moment of processing, Keyless Agent is not connected to the internet. This is particularly critical If your PII policies dictate that services that access user images cannot have access to internet as they do so.

  • Note that in this case, it’s critical to handle Keyless server state (see below for details).

• Online Enrollment

  • Still 100% privacy-preserving, all user images are processed within your own infrastructure, ensuring that Keyless never sees the selfie or biometric template - the registration and creation of the Keyless ID takes place automatically, ready for a user to authenticate against.

Client and Server State

Once you’ve selected which method is appropriate for you, the Keyless agent processes a user's selfie (JPEG, png, bmp) and provides two critical outputs that you need to store above all else::

1. Client State - this is used to initialize a Keyless Device via the Keyless SDK.

2. Server State - this is transmitted to the Keyless infrastructure to create and register a user within the Keyless ecosystem. Note this is only produced when working in offline mode.

This streamlined approach ensures secure and efficient user onboarding into the Keyless platform.

High Level Flow

1. User starts the onboarding process through the IDV Vendor Mobile SDK, performing liveness detection, capturing selfie and document data

2. Captured data are sent to the customer backend

3. Onboarding data are sent to the IDV bridge for KYC analysis

4. The IDV vendor returns a response

5. User selfie is sent to the Keyless Agent to create a Keyless user template

6. Keyless Agent sends back a clientState (for SDK initialization) and a serverState (for Keyless backend initialization)

   1. Client state is stored on the customer backend for later use (device binding + account recovery)

7. POST /uncommitted-users passing the server state in order to initialize the Keyless user on Keyless backend

8. POST /uncommitted-users/{userId}/commit in order to activate the Keyless user

9. The clientState is sent to the mobile App to initialize a new Keyless device for the specific user

10. Call Enrollment.withTemporaryState(client-state)

11. Keyless prompts the user to authenticate biometrics and confirm the device binding operation

Installation via Docker image

The Docker image is available on Keyless Quay repository. First, execute a docker login:

docker login -u="keyless_technologies+<PROVIDED_TENANT_NAME>" -p="<PROVIDED_PASSWORD>" quay.io

Then, proceed with pulling the container:

docker pull quay.io/keyless_technologies/keyless-agent:v2.0.1

Installation via Helm Chart

IDV Bridge On-Premise can also be installed via a Helm Chart. This installation method provides the advantage of using a kubernetes orchestrator for both scaling and easier maintenance.

The first step is to add the Keyless helm repository to your helm repository list with the following command:

$ helm repo add keyless https://example.com (the actual FQDN will be shared upon request)

The charts can then be listed:

$ helm search repo keyless

The list of needed values for each chart can be obtained by using the helm show values command:

$ helm show values keyless/keyless-agent

The reference values.yaml are to be saved and configured to the specific installation needs.

Once the configuration is performed it can be applied by issuing:

$ helm upgrade --install keyless-agent keyless/keyless-agent --atomic --wait

Finally, to allow container images to be pulled from our quay.io repository the creation of a registry secret is needed. This secret will contain the provided credentials in the format specified at the below link:

https://kubernetes.io/docs/concepts/configuration/secret/#docker-config-secrets

Enrolling images via the Keyless Agent APIs

We automatically generate the Keyless agent APIs in ReDoc. Note, this resource can also be accessed once Keyless Agent has been installed in your infrastructure, using the endpoint /redoc.

Head to this guide to understand how to enroll user images into Keyless for both Online and Offline enrollment, service health check and details of the errors.

Operations APIs (applies to offline enrollment flow only)

When working in offline mode the only way to then subsequently register a user with Keyless for ongoing authentication is to follow the guidance in this section.

As stated above, after a user image is processed by the IDV Bridge there are two key outputs:

1. Client State - Must be securely stored for future use during SDK Device Enrollment.

2. Server State - Must be transmitted to the Keyless infrastructure to complete the user registration process.

Base URL: api.keyless.io/v2

Secret Key for further authentication

The APIs are secured using an API key, which can be generated from the Access Control section of the Keyless Dashboard. To access Keyless APIs, users must generate a Secret Key from this section.

Once the API key is obtained, it should be included in the request header as X-Api-Key.

POST /uncommited Users

To create an uncommitted user from a server-state generated by the Keyless IDV Bridge, the server state returned by the IDV Bridge is used as a body. Content Type is application/json.

The newly created User ID is returned as a JSON response:

{
  "userId": "0123456789ABCDEF"
}

POST /uncommitted-users/{userId}/commit

Once the user has been created with /uncommitted-users, it needs to be activated via an explicit “commit” API call. Such a call requires no body, as the userId is passed as URL parameter.

How to then authenticate with Keyless

Once you've completed the registration of your users via IDV Bridge On-Premise, you'll want them to authenticate them using Keyless’ facial biometric authentication. We recommend the following next steps:

• For customers who want to authenticate users inside their own iOS and Android apps -> https://docs.keyless.io/consumer/

• For customers who want to authenticate users inside their browser based apps -> https://docs.keyless.io/web-sdk/

• Or for general understanding on how the core Keyless components interact - IDV Bridge, Mobile SDK, WebSDK - head to https://docs.keyless.io/idv-bridge