How to Run Keyless Agent

This page talks through how to set-up and run IDV Bridge On-Premise (Keyless agent) and the required configurations.

Pull the 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:

dockerpullquay.io/keyless_technologies/keyless-agent:v2.0.1

Running Keyless Agent

Customers can run this on their own as docker image or utilize our helm chart.

Once the docker image is setup to run the service, the service is configured via the following environment variables. If there is no default then it is required.

• NUM_OF_CIRC - Number of circuits to create during enrollment (default: 25 )

To enable online enrollment, the following environment variables are required. If not set the online enrollment will be disabled:

• AUTH_SERVER_URL - URL of the keyless auth server (same as host passed to SDK)

• AUTH_SERVER_API_KEY - API key for the keyless auth server (same as api key passed to SDK)

To configure the HTTP server:

• PORT - port for HTTP server to listen on (default: 80)

• HTTP_KEEP_ALIVE - HTTP keep-alive timeout in seconds (default: 75)

• WEB_WORKERS - The number of worker processes for handling requests. (default: 1); more workers slows startup time but increases throughput

• MAX_REQUESTS - The maximum number of requests a worker will process before restarting. (default: 10); If this is set to zero then the automatic worker restarts are disabled.

• MAX_REQUESTS_JITTER - The maximum jitter to add to the max_requests setting. (default: 2); The jitter causes the restart per worker to be randomized.

Note that the defaults are set-up to run the service in a very conservative mode, designed for low resource usage and low throughput. For higher throughput following settings are recommended for a 2 core 8GB machine:

• WEB_WORKERS=2 (or 3) there should be at least 2 workers to handle requests concurrently.

• MAX_REQUESTS=100 to restart workers after processing 100 requests, processing images require a lot of memory and this will help to keep memory usage in check.

• MAX_REQUESTS_JITTER=10 this adds some jitter to the restarts to avoid all workers restarting at the same time.

Understanding circuits for Authentication

Circuits are a key concept in the Keyless platform to ensure we remain 100% Privacy-preserving. They ensure that our cryptographic transformation is a unique process for every user, on every device and for every authentication which prevents any reverse engineering attempts by bad actors.

These circuits are generated on the client side (e.g., the IDV bridge) and sent to the server. Each authentication request consumes one circuit, and a successful authentication replenishes the circuit supply. However, if a user repeatedly fails authentication, the circuits may become exhausted. When this occurs, the user must re-enroll. The maximum number of circuits therefore determines the maximum number of consecutive failed authentication attempts allowed before the account is locked and re-enrollment is required, with the trade-off that setting this maximum too high will start to effect performance. The default is set to 25 and we generally would advise against changing this without good reason

Migration from version 1.x.x to version 2.x.x

Breaking Changes and Deprecations

The original offline enrollment endpoint ( /enrollment-data ) is now deprecated and will be removed. Most of its API stays the same except the error reporting. Since KA now uses new biometric SDK, error names completely changed.

The integrators are advised to switch to the new endpoint ( /v1/offline-enrollment ) as soon as possible or consider if online enrollment better suits their use-case.

Migration from /enrollment-data to /v1/offline-enrollment

With the new endpoint the integrator must choose scenario (using Scenario header). Scenario is similar to config query parameter in the old endpoint.

• SELFIE scenario is similar to config=default in the old endpoint. This is also a default on old endpoint.

• TRUSTED_SOURCE scenario is similar to config=less-strict in the old endpoint

• DOCUMENT scenario has no equivalent in the old endpoint

The request body is the same.

The response now follows camelCase naming convention and stats field has been removed.

The error response is now more detailed and follows the same naming convention as the rest of the API.