> 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.md). # IAD Service **API Rest de detecção de ataques de injeção (Injection Attack Detection)** — Protege seus sistemas biométricos contra ataques de spoofing. ## O que é o IAD Service? IAD Service é um microserviço de API Rest que detecta ataques de injeção em capturas biométricas. Verifica que os dados biométricos provêm de fontes reais, e não de repetições (replays) nem de entradas sintéticas. > **Aviso de mudança incompatível (2.0.0)** A versão 2.0.0 quebra a compatibilidade da API REST pública com todas as versões 1.x.x anteriores. As integrações que atualizarem a partir de 1.x.x devem atualizar os caminhos dos endpoints, os nomes dos campos das solicitações multipart e a análise das respostas corretas. | Contrato 1.x.x | Contrato 2.0.0 | | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `POST /api/v1/iad/check-capture` | `POST /api/v1/iad/liveness/evaluate` | | `POST /api/v1/iad/extract-image` | `POST /api/v1/iad/extract` | | campo multipart `file` | campo multipart obrigatório `capture`; `file` é rejeitado quando falta `capture` | | Payloads privados herdados de sucesso (`capture_liveness`, `capture_type`, `rejection`, `mime_type`) | Payloads públicos da Facephi (`diagnostic`, `reason`, `probability`, `score`, `faceProbability`, `sdkDuration`, `queueDuration`, `mimeType`) | **Use-o para:** * Extrair imagens válidas de capturas autenticadas * Monitorar o estado e o desempenho do sistema * Integrá-lo sem atritos com seus fluxos de autenticação ## Início rápido ### Requisitos | Componente | Requisito | | ---------- | ---------------------------------------- | | SO | Linux x86\_64 (recomendado Ubuntu 24.04) | | Licença | Arquivo de licença válido da Facephi | ### Implantação com Docker ```bash docker run -d \ -p 6982:6982 \ -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 ``` ### Verificar se funciona ```bash # Check health curl http://localhost:6982/api/v1/iad/health # Check version curl http://localhost:6982/api/v1/iad/version ``` Respostas típicas: ```json { "message": "Healthy" } ``` ```json { "message": "2.2.0 Copyright © 2026 FacePhi Biometria. All rights reserved." } ``` ## Endpoints da API > **Nota de compatibilidade** Os caminhos documentados nesta página são válidos somente para a versão 2.0.0 e posteriores. ### Operações principais | Endpoint | Método | Propósito | | ------------------------------- | ------ | -------------------------------------------------------------------------------- | | `/api/v1/iad/liveness/evaluate` | POST | Avalia o liveness de uma captura criptografada com o contrato público da Facephi | | `/api/v1/iad/extract` | POST | Extrai a imagem de uma captura validada | ### Gerenciamento | Endpoint | Método | Propósito | | -------------------------------- | -------- | ---------------------------------------------------------------------------------- | | `/api/v1/iad/version` | GET | Versão do serviço e estado da licença | | `/api/v1/iad/health` | GET | Verificação ativa de estado (inclui snapshot `initialized` e `engine.lastHealth*`) | | `/api/v1/iad/metrics` | GET | Snapshot JSON de métricas operacionais e de qualidade | | `/api/v1/iad/metrics/prometheus` | GET | Snapshot equivalente em formato Prometheus | | `/api/v1/iad/config` | GET/POST | Obter ou atualizar a configuração | `/health` e `/metrics` têm objetivos diferentes: * `/health` executa a verificação ativa do engine e atualiza o snapshot de saúde. * `/metrics` expõe contadores e snapshots em memória, sem executar verificações ativas caras a cada scrape. ## 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 de entrada. 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 * Aplica-se aos endpoints de processamento de capturas como `POST /api/v1/iad/liveness/evaluate` e `POST /api/v1/iad/extract` * Quando a janela de vigência é excedida, o serviço retorna HTTP `400` com `message` igual a `Replay attack detected` Exemplo de implantação: ```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 ``` Essa funcionalidade é configurada apenas na inicialização por meio de variáveis de ambiente. Não faz parte de `config.json` nem é exposta por meio de `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 por meio de `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 mesmos valores por meio de variáveis de ambiente `FACEPHI_IAD_REST_AUTH_*` * `GET /api/v1/iad/config` omite todas as chaves de autenticação JWT * `POST /api/v1/iad/config` rejeita todas as chaves de autenticação JWT; use em vez disso a configuração de inicialização Exemplo de trecho de `config.json`: ```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 ``` ## Contrato público de erros Nas respostas HTTP públicas `400`, o serviço retorna mensagens públicas documentadas no corpo da resposta padrão. ### Resultado de Liveness As respostas corretas de `POST /api/v1/iad/liveness/evaluate` exibem apenas os seguintes campos públicos: | Campo | Significado | | ----------------- | -------------------------------------------------------------------- | | `diagnostic` | Resultado de alto nível: `Live` ou `NoLive` | | `reason` | Valor público do motivo retornado pelo serviço | | `probability` | Probabilidade pública da captura | | `score` | Pontuação pública de confiança | | `faceProbability` | Probabilidade pública opcional de liveness facial, quando disponível | | `sdkDuration` | Duração da análise da captura em milissegundos | | `queueDuration` | Duração na fila informada pelo RestManager em milissegundos | Os valores possíveis para `reason` são: * `None` * `Unknown` * `UntrustedEnvironment` * `SuspiciousActivity` * `UntrustedDevice` * `SdkIntegrityViolation` * `UntrustedCorruptedPayload` * `UntrustedContent` * `UntrustedContentLowConfidence` | `reason` | Significado | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `None` | A captura foi aceita como `Live` e nenhum motivo de rejeição se aplica. | | `Unknown` | O serviço não conseguiu atribuir a resposta a um motivo de rejeição público documentado. | | `UntrustedEnvironment` | A captura foi rejeitada porque o ambiente de execução não é considerado confiável. | | `SuspiciousActivity` | A captura foi rejeitada porque o dispositivo exibiu padrões de atividade associados a um ataque. | | `UntrustedDevice` | A captura foi rejeitada porque não foi possível confiar que o dispositivo fosse quem diz ser. | | `SdkIntegrityViolation` | A captura foi rejeitada porque o SDK de captura ou suas bibliotecas parecem ter sido alterados. | | `UntrustedCorruptedPayload` | A captura foi rejeitada porque o payload parece estar corrompido ou manipulado. | | `UntrustedContent` | A captura foi rejeitada porque foi detectado um ataque de injeção. | | `UntrustedContentLowConfidence` | A captura foi rejeitada porque o serviço detectou indícios de um ataque de injeção com menor confiança; ainda assim deve ser tratada como uma rejeição. | Quando existem várias causas de rejeição, o serviço retorna o primeiro valor público de rejeição documentado conforme a ordem de resposta do serviço. ### Erros de validação normalizados Para o endpoint `POST /api/v1/iad/liveness/evaluate`, as falhas de validação de captura são retornadas como HTTP `400` com valores de `message` documentados, como: | Cenário | `message` público | | ----------------------------------------------------- | --------------------------------- | | Rosto muito próximo | `NoneBecauseFaceTooClose` | | Rosto não encontrado | `NoneBecauseFaceNotFound` | | Rosto cortado | `NoneBecauseFaceCropped` | | Rosto ocluído | `NoneBecauseFaceOccluded` | | Muitos rostos | `NoneBecauseTooManyFaces` | | Ângulo do rosto muito grande | `NoneBecauseAngleTooLarge` | | Rosto muito pequeno | `NoneBecauseFaceTooSmall` | | Rosto muito perto da borda | `NoneBecauseFaceTooCloseToBorder` | | Olhos fechados | `NoneBecauseEyesClosed` | | Não é possível processar a imagem ou o payload | `NoneBecauseImageDataError` | | Problema de licença reportado pelo runtime do serviço | `NoneBecauseLicenseError` | | Janela de vigência de repetição excedida | `Replay attack detected` | | Falha de liveness não classificada | `ErrorProcessing` | Para o endpoint `POST /api/v1/iad/extract`, as falhas de análise e desencriptação do payload são retornadas como `NoneBecauseImageDataError`; as capturas expiradas rejeitadas pela proteção contra repetições retornam `Replay attack detected`; as falhas de extração não classificadas são retornadas como `ErrorFacialImage`. ## Exemplo de uso > **Nota de atualização** Os exemplos a seguir usam intencionalmente o contrato público 2.x introduzido na Versão 2.0.0: o campo multipart `capture` e o esquema de resposta pública. ### Avaliar Liveness ```bash curl -X POST \\ -F "capture=@biometric_capture.bin" \\ http://localhost:6982/api/v1/iad/liveness/evaluate ``` **Resposta:** ```json { "diagnostic": "Live", "reason": "None", "probability": 1, "score": 1, "sdkDuration": 12, "queueDuration": 3 } ``` ### Extrair imagem ```bash curl -X POST \\ -F "capture=@biometric_capture.bin" \\ http://localhost:6982/api/v1/iad/extract ``` **Resposta:** ```json { "image": "base64_encoded_image...", "mimeType": "image/jpeg" } ``` ### Obter configuração Retorna a visão pública da configuração em tempo de execução. As chaves de autenticação JWT são omitidas intencionalmente. ```bash curl http://localhost:6982/api/v1/iad/config ``` ### Atualizar configuração `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 definidas apenas na inicialização. ```bash curl -X POST \\ -H "Content-Type: application/json" \\ -d '{"config_json_string":"{\"port\":6982,\"number_of_threads\":1,\"engine_url\":\"http://localhost:8080\",\"engine_pool_size\":8}"}' \\ http://localhost:6982/api/v1/iad/config ``` **Resposta:** ```json { "message": "Configuration updated successfully" } ``` ## Configuração Cria `/app/config/config.json`: ```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": "/app/logs", "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 principais | Parâmetro | Padrão | Descrição | | ---------------------------------- | ----------------------- | ------------------------------------------------------------------------------ | | `port` | 6982 | Porta de escuta do serviço | | `number_of_threads` | 1 | Threads de trabalho para o processamento de solicitações | | `connection_timeout` | 60 | Timeout de conexão do Rest::Manager | | `keep_alive_request_number` | 0 | Número máximo de solicitações keep-alive | | `client_max_body_size` | 100 | Tamanho máximo do corpo da solicitação em MB | | `logger_level` | "info" | Nível de log (trace/debug/info/warn/error) | | `auth_enabled` | false | Requer autenticação JWT para os endpoints protegidos | | `auth_jwt_secret` | "" | Segredo compartilhado HS256 usado para validar os JWTs | | `auth_accept_authorization_header` | true | Aceita `Authorization: Bearer ` | | `auth_accept_api_key_header` | true | Aceita JWT no cabeçalho de API key configurado | | `auth_api_key_header_name` | "x-api-key" | Nome do cabeçalho usado quando a extração de token por API key está habilitada | | `engine_connection_timeout` | 10000 | Timeout de conexão (ms) | | `engine_request_timeout` | 60000 | Timeout de solicitação (ms) | | `engine_max_retries` | 3 | Tentativas de repetição do engine | | `engine_retry_delay` | 1000 | Atraso entre tentativas do engine em ms | | `engine_verify_ssl` | false | Verifica os certificados SSL do runtime de análise de capturas | | `engine_verbose` | false | Habilita logs detalhados do proxy de análise de capturas | | `engine_pool_size` | 4 | Tamanho do pool de conexões | | `engine_url` | `http://localhost:8080` | URL base do runtime de análise de capturas | ## Visão geral da arquitetura ```mermaid flowchart TD Client["Cliente
Aplicação"] Client -->|HTTP/REST| IADService subgraph IADService["Facephi IAD Service"] Components["• Licença
• Endpoints
• Validação de capturas
• Mitigação de ataques de repetição
• Pool de conexões
• Gestão de configuração"] end style Client fill:#4a9eff,stroke:#333,stroke-width:2px,color:#000 style IADService fill:#111111,stroke:#333,stroke-width:2px,color:#000 style Components fill:#60a5fa,stroke:#333,stroke-width:2px,color:#000 ``` ## Suporte Para consultas de licença ou Suporte Técnico, entre em contato com seu representante da Facephi.