> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-pt-br/sdks/backend-sdk/iad/installation/installation_instructions.md). # 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: ```bash docker login facephicorp.jfrog.io ``` Você precisará das credenciais fornecidas pela Facephi. ## Instalação {% hint style="danger" %} **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) {% endhint %} ### Baixar a imagem Docker ```bash 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: ```bash 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: ```bash 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`: ```yaml 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 ```bash docker compose up -d ``` ### Verificar a implantação ```bash # 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=` * 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`: ```bash 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: ```yaml 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 ```ini 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 {% hint style="danger" %} **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. {% endhint %} 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: ```json { "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: ```bash 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) ```json { "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 ` | | `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: ```json { "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: ```json { "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: ```bash # 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:** ```bash docker exec facephi-iad-service ls -la /app/license/ ``` **Verifique os logs:** ```bash 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: {% hint style="warning" %} **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. {% endhint %} ```bash # 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.**