Skip to content

Installation Guide

Prerequisites

Before installing the IAD Service, ensure you have:

  • Docker installed and running
  • Valid Facephi license file
  • Access to Facephi Docker registry

Docker Registry Access

Login to the Facephi Docker registry:

docker login facephicorp.jfrog.io

You will need credentials provided by Facephi.

Installation

Breaking change notice (2.0.0) Version 2.0.0 is not backward compatible with 1.x.x integrations. Before upgrading a deployed client, review and update: - public endpoint paths - multipart request field names (file -> required capture; file-only requests are rejected) - successful response parsing (capture_liveness and related fields are no longer returned)

Pull the Docker Image

docker pull facephicorp.jfrog.io/docker-core-pro-fphi/facephi-iad-service:2.0.0

Replace 2.0.0 with the desired version.

Prepare Directories

Create directories for license, configuration, and logs:

mkdir -p ~/facephi_iad/{license,config,logs}

Place License File

Copy your license file to the license directory:

cp your-license.lic ~/facephi_iad/license/license.lic
chmod 644 ~/facephi_iad/license/license.lic

Docker Compose Deployment

Create docker-compose.yml:

version: '3.7'

services:
  iad-service:
    image: facephicorp.jfrog.io/docker-core-pro-fphi/facephi-iad-service:2.0.0
    container_name: facephi-iad-service
    ports:
      - "6982:6982"
    volumes:
      - ~/facephi_iad/license:/app/license
      - ~/facephi_iad/config:/app/config
      - ~/facephi_iad/logs:/app/logs
    restart: unless-stopped

Start the Service

docker compose up -d

Verify Deployment

# Check container status
docker ps | grep iad-service

# Check service health
curl http://localhost:6982/api/v1/iad/health

# View logs
docker logs facephi-iad-service

Experimental Replay Attack Mitigation

The service can enforce a freshness window on incoming capture payloads. This experimental protection is disabled by default.

  • Enable it with FACEPHI_IAD_REPLAY_ATTACK_CHECKER_ENABLED=true
  • Adjust the freshness window with FACEPHI_IAD_REPLAY_ATTACK_TOLERANCE_TIME=<seconds>
  • Default freshness window: 300 seconds
  • When the freshness window is exceeded, the public API returns HTTP 400 with message equal to Replay attack detected

This feature is configured at startup through environment variables. It is not part of config.json and is not exposed through GET|POST /api/v1/iad/config.

Example with docker run:

docker run -d \
  -p 6982:6982 \
  -e FACEPHI_IAD_REPLAY_ATTACK_CHECKER_ENABLED=true \
  -e FACEPHI_IAD_REPLAY_ATTACK_TOLERANCE_TIME=60 \
  -v /path/to/license:/app/license \
  -v /path/to/config:/app/config \
  --name iad-service \
  facephicorp.jfrog.io/docker-core-pro-fphi/facephi-iad-service:2.0.0

Example with Docker Compose:

services:
  iad-service:
    environment:
      FACEPHI_IAD_REPLAY_ATTACK_CHECKER_ENABLED: "true"
      FACEPHI_IAD_REPLAY_ATTACK_TOLERANCE_TIME: "60"

License Configuration

The license file must be located at /app/license/license.lic inside the container.

License File Format

LICENSE_TYPE=         # MACHINE, SHARED, or LOCAL
LICENSE_BEHAVIOUR=    # ONLINE or OFFLINE
LICENSE_KEY=          # Your license key

Optional fields:

  • LICENSE_URLS= — Comma-separated license server URLs (required for LOCAL type)
  • LICENSE_PATH_OFFLINE= — Path to offline activation file (required for MACHINE + OFFLINE)

LICENSE_ID and LICENSE_DATA, if present, are ignored by the service as of version 2.0.0. The IAD product credentials are embedded at build time, so these fields should be omitted from deployment templates.

Public API Summary

Compatibility note The routes below are the 2.0.0 contract. Clients built for 1.x.x must be migrated before they can call this version successfully.

Operational endpoints exposed by the service:

  • POST /api/v1/iad/liveness/evaluate
  • POST /api/v1/iad/extract
  • GET /api/v1/iad/version
  • GET /api/v1/iad/health
  • GET|POST /api/v1/iad/config

JWT Authentication

JWT authentication is optional and disabled by default.

  • Configure it at startup in /app/config/config.json with auth_enabled, auth_jwt_secret, auth_accept_authorization_header, auth_accept_api_key_header, and auth_api_key_header_name
  • Override those values with FACEPHI_IAD_REST_AUTH_* environment variables
  • GET /api/v1/iad/config never returns JWT authentication keys
  • POST /api/v1/iad/config rejects JWT authentication keys; manage them only at startup

Example startup configuration:

{
  "auth_enabled": true,
  "auth_jwt_secret": "replace-with-secret",
  "auth_accept_authorization_header": true,
  "auth_accept_api_key_header": true,
  "auth_api_key_header_name": "x-api-key"
}

Example environment variables:

export FACEPHI_IAD_REST_AUTH_ENABLED=true
export FACEPHI_IAD_REST_AUTH_JWT_SECRET=replace-with-secret
export FACEPHI_IAD_REST_AUTH_ACCEPT_AUTHORIZATION_HEADER=true
export FACEPHI_IAD_REST_AUTH_ACCEPT_API_KEY_HEADER=true
export FACEPHI_IAD_REST_AUTH_API_KEY_HEADER_NAME=x-api-key

Detailed Capture Information (longDetails)

POST /api/v1/iad/liveness/evaluate accepts an optional multipart text field longDetails in the same multipart/form-data body as the required capture part.

  • Accepted values are true and false (case-insensitive, trimmed).
  • When the field is absent, empty, or false, the endpoint returns the standard public liveness payload.
  • Any other value is rejected with HTTP 400.

For longDetails=true to return top-level additionalInfo, all of the following must be true:

  1. engine_bi_records_enabled resolves to true.
  2. engine_url points to an IAD Server that exposes both /check_capture_liveness and /bi_records.
  3. The BI record is found before engine_bi_records_timeout_ms expires.

Operational notes:

  • The service generates the correlation-id header automatically; clients do not send it.
  • BI lookup uses the current UTC date window when querying /bi_records; keep the service host and the IAD Server clock synchronized.

Activation paths for the embedded-engine Docker flow:

  1. Set logger_long_detail=true in /app/config/config.json.
  2. Set FACEPHI_IAD_LOGGER_LONG_DETAIL=true in the service container environment.
  3. Set IAD_SERVER_BI_LOGS_ENABLED=true in the service container environment. Optionally set IAD_SERVER_BI_LOGS_PATH to customize the BI logs directory.

Why those options work:

  • When the service launches the embedded engine itself, src/App.cpp injects IAD_SERVER_BI_LOGS_ENABLED=true and default IAD_SERVER_BI_LOGS_PATH=/app/logs into the child engine process whenever logger_long_detail resolves to true and those internal variables are absent.
  • Direct IAD_SERVER_BI_LOGS_* exports also work because the child engine inherits the parent environment.
  • If the service is configured to call an external engine instead of launching the embedded one, configure the equivalent BI logging capability on that engine deployment.

These keys can be set in /app/config/config.json, updated later through POST /api/v1/iad/config, or overridden with FACEPHI_IAD_ENGINE_BI_RECORDS_* environment variables.

Example configuration fragment:

{
  "engine_url": "http://iad-server.internal:8080",
  "engine_bi_records_enabled": true,
  "engine_bi_records_max_retries": 3,
  "engine_bi_records_retry_delay_ms": 50,
  "engine_bi_records_timeout_ms": 300,
  "engine_bi_records_redact_request_data": true
}

Example runtime configuration update:

curl -X POST http://localhost:6982/api/v1/iad/config \
  -H "Content-Type: application/json" \
  -d '{"config_json_string":"{\"engine_url\":\"http://iad-server.internal:8080\",\"engine_bi_records_enabled\":true,\"engine_bi_records_timeout_ms\":500,\"engine_bi_records_redact_request_data\":true}"}'

Example container environment using the service-level flag:

docker run -d \
  -p 6982:6982 \
  -e FACEPHI_IAD_LOGGER_LONG_DETAIL=true \
  -v /path/to/license:/app/license \
  -v /path/to/config:/app/config \
  --name iad-service \
  facephicorp.jfrog.io/docker-core-pro-fphi/facephi-iad-service:2.1.0

Alternative container environment using the inherited internal engine variables directly:

docker run -d \
  -p 6982:6982 \
  -e IAD_SERVER_BI_LOGS_ENABLED=true \
  -e IAD_SERVER_BI_LOGS_PATH=/app/logs \
  -v /path/to/license:/app/license \
  -v /path/to/config:/app/config \
  --name iad-service \
  facephicorp.jfrog.io/docker-core-pro-fphi/facephi-iad-service:2.1.0

Example liveness request:

curl -X POST http://localhost:6982/api/v1/iad/liveness/evaluate \
  -F "capture=@capture.bin;type=application/octet-stream" \
  -F "longDetails=true"

Firewall Configuration for License Validation

Add firewall rules to allow outbound HTTPS to Facephi license servers:

IP Port Protocol
52.223.22.71 443 TCP/IP
35.71.188.31 443 TCP/IP
75.2.113.112 443 TCP/IP
99.83.149.57 443 TCP/IP

Allow HTTPS traffic to:

  • https://api.cryptlex.com:443
  • https://api.eu.cryptlex.com:443

Service Configuration

Create /app/config/config.json to customize service behavior.

Configuration File Location

  • Default location: /app/config/config.json (inside container)
  • Mount external file: Use volume mapping in docker-compose

Complete Configuration Example (Current Defaults)

{
  "port": 6982,
  "number_of_threads": 1,
  "connection_timeout": 60,
  "keep_alive_request_number": 0,
  "client_max_body_size": 100,
  "logger_level": "info",
  "logger_path": "",
  "logger_rotation": "daily",
  "logger_max_files": 7,
  "auth_enabled": false,
  "auth_jwt_secret": "",
  "auth_accept_authorization_header": true,
  "auth_accept_api_key_header": true,
  "auth_api_key_header_name": "x-api-key",
  "engine_connection_timeout": 10000,
  "engine_request_timeout": 60000,
  "engine_max_retries": 3,
  "engine_retry_delay": 1000,
  "engine_verify_ssl": false,
  "engine_verbose": false,
  "engine_pool_size": 4,
  "engine_url": "http://localhost:8080",
  "engine_bi_records_enabled": true,
  "engine_bi_records_max_retries": 3,
  "engine_bi_records_retry_delay_ms": 50,
  "engine_bi_records_timeout_ms": 300,
  "engine_bi_records_redact_request_data": false
}

Service Parameters

Parameter Type Default Description
port integer 6982 Service listening port
number_of_threads integer 1 Worker threads for request handling
connection_timeout integer 60 Connection timeout in seconds (0 = no timeout)
keep_alive_request_number integer 0 Keep-alive requests (0 = disabled)
client_max_body_size integer 100 Max request body size in MB
logger_path string "" Log file path (empty = stdout)
logger_level string "info" Log level: trace, debug, info, warn, error
logger_rotation string "daily" Log rotation: daily, hourly, size
logger_max_files integer 7 Max log files to retain
auth_enabled boolean false Require JWT authentication for protected endpoints
auth_jwt_secret string "" HS256 shared secret used to validate JWTs
auth_accept_authorization_header boolean true Accept Authorization: Bearer <jwt>
auth_accept_api_key_header boolean true Accept JWTs in the configured API key header
auth_api_key_header_name string "x-api-key" Header name used when API key token extraction is enabled

Engine Parameters

Parameter Type Default Description
engine_connection_timeout integer 10000 Connection timeout (ms)
engine_request_timeout integer 60000 Request timeout (ms)
engine_max_retries integer 3 Max retry attempts
engine_retry_delay integer 1000 Delay between retries (ms)
engine_verify_ssl boolean false Verify capture-analysis SSL certificates
engine_verbose boolean false Enable verbose capture-analysis HTTP logging
engine_pool_size integer 4 Connection pool size
engine_url string "http://localhost:8080" Base URL of the capture-analysis runtime
engine_bi_records_enabled boolean true Enable additionalInfo retrieval for longDetails=true
engine_bi_records_max_retries integer 3 Retries while waiting for the BI record
engine_bi_records_retry_delay_ms integer 50 Delay between BI record retries (ms)
engine_bi_records_timeout_ms integer 300 Total BI retrieval latency budget (ms)
engine_bi_records_redact_request_data boolean false Strip output.request_data from additionalInfo

Production Configuration

For production deployments:

{
  "port": 6982,
  "number_of_threads": 8,
  "connection_timeout": 60,
  "keep_alive_request_number": 1000,
  "client_max_body_size": 100,
  "logger_level": "info",
  "logger_path": "/app/logs",
  "logger_rotation": "daily",
  "logger_max_files": 30,
  "engine_connection_timeout": 10000,
  "engine_request_timeout": 60000,
  "engine_max_retries": 3,
  "engine_retry_delay": 1000,
  "engine_verify_ssl": true,
  "engine_verbose": false,
  "engine_pool_size": 20,
  "engine_url": "https://localhost:8080"
}

Development Configuration

For local development:

{
  "port": 6982,
  "number_of_threads": 2,
  "logger_level": "debug",
  "logger_path": "/app/logs",
  "engine_connection_timeout": 5000,
  "engine_request_timeout": 30000,
  "engine_max_retries": 1,
  "engine_verify_ssl": false,
  "engine_verbose": true,
  "engine_pool_size": 2,
  "engine_url": "http://localhost:8080"
}

Dynamic Configuration Updates

Update configuration without restarting:

# Update configuration
curl -X POST http://localhost:6982/api/v1/iad/config \
  -H "Content-Type: application/json" \
  -d '{"config_json_string":"{\"engine_url\":\"http://localhost:8081\",\"engine_pool_size\":8,\"engine_bi_records_enabled\":true,\"engine_bi_records_timeout_ms\":500}"}'

# Verify current configuration
curl http://localhost:6982/api/v1/iad/config

POST /api/v1/iad/config expects a JSON object with the config_json_string field, containing the full configuration serialized as a JSON string. JWT authentication keys are rejected by this endpoint and must be configured only at startup.

Note: Runtime updates are not persisted automatically. To make permanent changes, update the configuration file on disk and restart the service if needed.

Troubleshooting

Service Won't Start

Check license file: 

docker exec facephi-iad-service ls -la /app/license/

Check logs: 

docker logs facephi-iad-service

License Validation Fails

  • Verify license file permissions: chmod 644 license.lic
  • Ensure firewall allows outbound HTTPS to license servers
  • Check license expiration date
  • Confirm license is for IAD Service product

Performance Issues

  • Increase engine_pool_size to handle more concurrent requests
  • Adjust number_of_threads based on available CPU cores
  • Monitor resource usage: docker stats facephi-iad-service
  • Review logs for timeout errors or retries

Upgrading

To upgrade to a new version:

Important Upgrading from 1.x.x to 2.0.0 is a breaking API migration, not a drop-in replacement. Validate all client calls against the new endpoint names and request/response examples before promoting the deployment.

# Pull new version
docker pull facephicorp.jfrog.io/docker-core-pro-fphi/facephi-iad-service:2.0.0

# Update docker-compose.yml with new version
# Stop current service
docker compose down

# Start new version
docker compose up -d

# Verify upgrade
curl http://localhost:6982/api/v1/iad/version

Always review release notes before upgrading.