Instalação e implantação do serviço

Pré-requisitos

Antes de instalar o IAD Service, verifique se você tem:

• Docker instalado e em execução

• Um arquivo de licença válido da Facephi

• Acesso ao registro Docker da Facephi

Acesso ao registro Docker

Faça login no registro Docker da Facephi:

docker login facephicorp.jfrog.io

Você precisará das credenciais fornecidas pela Facephi.

Instalação

Aviso de alteração incompatível (2.0.0) A versão 2.0.0 não é retrocompatível com as integrações 1.x.x. Antes de atualizar um cliente implantado, revise e atualize:

• os caminhos dos endpoints públicos

• os nomes dos campos das solicitações multipart (file -> obrigatório capture; as solicitações que incluem apenas file são rejeitadas)

• a análise das respostas corretas (os campos capture_liveness e relacionados não são mais retornados)

Baixar a imagem Docker

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

Substitua 2.2.0 pela versão desejada.

Preparar os diretórios

Crie os diretórios para a licença, a configuração e os logs:

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

Colocar o arquivo de licença

Copie o seu arquivo de licença para o diretório de licença:

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

Implantação com Docker Compose

Crie docker-compose.yml:

version: '3.7'

services:
  iad-service:
    image: facephicorp.jfrog.io/docker-pro-fphi/facephi-iad-service:2.2.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

Iniciar o serviço

docker compose up -d

Verificar a implantação

# Verificar o status do contêiner
docker ps | grep iad-service

# Verificar a saúde do serviço
curl http://localhost:6982/api/v1/iad/health

# Ver logs
docker logs facephi-iad-service

Mitigação experimental de ataques de repetição (replay)

O serviço pode aplicar uma janela de vigência (freshness window) aos payloads de captura recebidos. Essa proteção experimental está desabilitada por padrão.

• Ative-a com FACEPHI_IAD_REPLAY_ATTACK_CHECKER_ENABLED=true

• Ajuste a janela de vigência com FACEPHI_IAD_REPLAY_ATTACK_TOLERANCE_TIME=<seconds>

• Janela de vigência padrão: 300 segundos

• Quando a janela de vigência é excedida, a API pública retorna HTTP 400 com message igual a Ataque de replay detectado

Essa funcionalidade é configurada na inicialização por meio de variáveis de ambiente. Não faz parte de config.json nem é exposta por GET|POST /api/v1/iad/config.

Exemplo com 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-pro-fphi/facephi-iad-service:2.2.0

Exemplo com Docker Compose:

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

Configuração da licença

O arquivo de licença deve estar em /app/license/license.lic dentro do contêiner.

Formato do arquivo de licença

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

Campos opcionais:

• LICENSE_URLS= — URLs dos servidores de licença separadas por vírgulas (obrigatório para o tipo LOCAL)

• LICENSE_PATH_OFFLINE= — Caminho para o arquivo de ativação offline (obrigatório para MACHINE + OFFLINE)

LICENSE_ID e LICENSE_DATA, se estiverem presentes, são ignorados pelo serviço a partir da versão 2.0.0. As credenciais do produto IAD são incorporadas em tempo de compilação, portanto esses campos devem ser omitidos nos modelos de implantação.

Resumo da API pública

Nota de compatibilidade Os caminhos a seguir correspondem ao contrato da versão 2.0.0. Os clientes construídos para 1.x.x devem ser migrados antes de poder chamar corretamente esta versão.

Endpoints operacionais expostos pelo serviço:

• 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

Autenticação JWT

A autenticação JWT é opcional e está desabilitada por padrão.

• Configure-a na inicialização em /app/config/config.json com auth_enabled, auth_jwt_secret, auth_accept_authorization_header, auth_accept_api_key_header e auth_api_key_header_name

• Substitua esses valores pelas variáveis de ambiente FACEPHI_IAD_REST_AUTH_*

• GET /api/v1/iad/config nunca retorna as chaves de autenticação JWT

• POST /api/v1/iad/config rejeita as chaves de autenticação JWT; gerencie-as apenas na inicialização

Exemplo de configuração na inicialização:

{
  "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"
}

Exemplo de variáveis de ambiente:

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

Configuração do firewall para a validação da licença

Adicione regras de firewall para permitir o tráfego HTTPS de saída para os servidores de licença da Facephi:

IP	Porta	Protocolo
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

Permita o tráfego HTTPS para:

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

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

Configuração do serviço

Crie /app/config/config.json para personalizar o comportamento do serviço.

Localização do arquivo de configuração

• Localização padrão: /app/config/config.json (dentro do contêiner)

• Montar um arquivo externo: Use o mapeamento de volumes em docker-compose

Exemplo de configuração completa (valores padrão atuais)

{
  "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"
}

Parâmetros do serviço

Parâmetro	Tipo	Padrão	Descrição
port	integer	6982	Porta de escuta do serviço
number_of_threads	integer	1	Threads de trabalho para o processamento de solicitações
connection_timeout	integer	60	Timeout de conexão em segundos (0 = sem Timeout)
keep_alive_request_number	integer	0	Solicitações keep-alive (0 = desabilitado)
client_max_body_size	integer	100	Tamanho máximo do corpo da solicitação em MB
logger_path	string	""	Caminho do arquivo de log (vazio = stdout)
logger_level	string	"info"	Nível de log: trace, debug, info, warn, error
logger_rotation	string	"daily"	Rotação de logs: daily, hourly, size
logger_max_files	integer	7	Número máximo de arquivos de log a serem mantidos
auth_enabled	boolean	false	Exige autenticação JWT para os endpoints protegidos
auth_jwt_secret	string	""	Segredo compartilhado HS256 usado para validar os JWT
auth_accept_authorization_header	boolean	true	Aceita Authorization: Bearer <jwt>
auth_accept_api_key_header	boolean	true	Aceita JWT no cabeçalho de API key configurado
auth_api_key_header_name	string	"x-api-key"	Nome do cabeçalho usado quando a extração de token por API key está habilitada

Parâmetros do engine

Parâmetro	Tipo	Padrão	Descrição
engine_connection_timeout	integer	10000	Timeout de conexão (ms)
engine_request_timeout	integer	60000	Timeout da solicitação (ms)
engine_max_retries	integer	3	Número máximo de tentativas
engine_retry_delay	integer	1000	Atraso entre tentativas (ms)
engine_verify_ssl	boolean	false	Verifica os certificados SSL da análise de capturas
engine_verbose	boolean	false	Ativa o logging HTTP detalhado da análise de capturas
engine_pool_size	integer	4	Tamanho do pool de conexões
engine_url	string	http://localhost:8080	URL base do runtime de análise de capturas

Configuração de produção

Para implantações em produção:

{
  "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"
}

Configuração de desenvolvimento

Para desenvolvimento local:

{
  "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"
}

Atualizações dinâmicas de configuração

Atualize a configuração sem reiniciar:

# Atualizar a configuração
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}"}'

# Verificar a configuração atual
curl http://localhost:6982/api/v1/iad/config

POST /api/v1/iad/config espera um objeto JSON com o campo config_json_string, que contém a configuração completa serializada como uma string JSON. As chaves de autenticação JWT são rejeitadas por este endpoint e devem ser configuradas apenas na inicialização.

Observação: As atualizações em tempo de execução não são persistidas automaticamente. Para fazer alterações permanentes, atualize o arquivo de configuração em disco e reinicie o serviço se necessário.

Solução de problemas

O serviço não inicia

Verifique o arquivo de licença:

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

Verifique os logs:

docker logs facephi-iad-service

Falha na validação da licença

• Verifique as permissões do arquivo de licença: chmod 644 license.lic

• Certifique-se de que o firewall permite o tráfego HTTPS de saída para os servidores de licença

• Verifique a data de expiração da licença

• Confirme que a licença corresponde ao produto IAD Service

Problemas de desempenho

• Aumente engine_pool_size para lidar com mais solicitações simultâneas

• Ajuste number_of_threads de acordo com os núcleos de CPU disponíveis

• Monitore o uso de recursos: docker stats facephi-iad-service

• Revise os logs em busca de erros de Timeout ou de novas tentativas

Atualização

Para atualizar para uma nova versão:

Importante Atualizar de 1.x.x para 2.0.0 é uma migração de API com alterações incompatíveis, não uma substituição direta. Valide todas as chamadas do cliente em relação aos novos nomes de endpoints e aos exemplos de solicitação/resposta antes de promover a implantação.

# Baixar nova versão
docker pull facephicorp.jfrog.io/docker-pro-fphi/facephi-iad-service:2.0.0
docker pull facephicorp.jfrog.io/docker-pro-fphi/facephi-iad-service:2.2.0

# Atualizar docker-compose.yml com a nova versão
# Parar o serviço atual
docker compose down

# Iniciar nova versão
docker compose up -d

# Verificar a atualização
curl http://localhost:6982/api/v1/iad/version

Revise sempre as notas de versão antes de atualizar.