Pular para o conteúdo principal

Como Integrar

🔗 Como Integrar​

O GuardianKey Auth Security pode ser facilmente integrado a qualquer sistema de autenticação, geralmente adicionando apenas algumas linhas de código na etapa de processamento do login. Para cada tentativa de acesso, a integração fornece uma pontuação de risco e uma ação recomendada (como ACCEPT, NOTIFY, BLOCK), permitindo decisões dinâmicas baseadas em políticas de segurança configuráveis.

🚀 Fluxo Geral de Integração​

O processo de integração consiste em três etapas principais:

  1. Capturar a Tentativa de Login
    O sistema coleta dados como nome de usuário, IP, resultado da autenticação e User-Agent.

  2. Enviar o Evento para o GuardianKey
    Esses dados são enviados via chamada REST para a API do GuardianKey.

  3. Agir de Acordo com a Resposta
    O sistema interpreta a resposta (ACCEPT, NOTIFY, BLOCK) e age conforme indicado.

🛡️ Identificadores Pseudonimizados de Usuário​

O GuardianKey não exige o nome de usuário em texto claro para calcular o risco. A integração cliente pode pseudonimizar o identificador antes de enviar o evento, por exemplo, aplicando um hash criptográfico consistente. O mesmo valor pseudonimizado e estável deve ser utilizado nos eventos seguintes, para que o motor comportamental correlacione as atividades e mantenha a linha de base do usuário sem receber o nome original.

Senhas e segredos de autenticação nunca devem ser inseridos no identificador nem enviados como atributos do evento.

📥 Exemplo de Fluxo no Backend​

Para verificar o risco de um evento de autenticação usando a GuardianKey API v2, seu backend deve:

  1. Criar um objeto JSON com os dados do evento (ex.: nome de usuário, IP, user agent).
  2. Codificar esse objeto como uma string JSON.
  3. Calcular um hash SHA-256 da seguinte concatenação:
    hash("sha256", message_json_string + key + iv)
  4. Enviar uma requisição POST para o endpoint da GuardianKey:
    https://api.guardiankey.io/v2/checkaccess

Estrutura do Corpo da Requisição​

O corpo da requisição deve ser um objeto JSON com a seguinte estrutura:

{
  "authgroupid": "SEU_AUTHGROUPID",
  "message": "{\"generatedTime\":1754428303,\"agentId\":\"AGENT_ID\",\"organizationId\":\"ORG_ID\",\"authGroupId\":\"AUTHGROUPID\",\"service\":\"SERVICE_NAME\",\"clientIP\":\"189.30.220.10\",\"clientReverse\":\"host.example.com\",\"userName\":\"maria\",\"authMethod\":\"\",\"loginFailed\":0,\"userAgent\":\"Mozilla/5.0...\",\"psychometricTyped\":\"\",\"psychometricImage\":\"\",\"event_type\":\"Authentication\",\"userEmail\":\"[email protected]\"}",
  "hash": "d9c34b6ecbd1a0f2a33b0a0de2a60ff63e8e2d5b8e7153ef32d5de7f57c55f5d"
}

⚠️ Importante:
O campo message deve conter uma string JSON codificada, não um objeto aninhado.
O hash é um SHA-256 de: message + key + iv

✅ Exemplo de Resposta da API​

{
  "client_os": "Linux",
  "risk_psychometric": "100.0",
  "generatedTime": 1754428303,
  "risk": 5.047,
  "country": "Brazil",
  "eventId": "3e1c389c1ae49efc...",
  "response": "ACCEPT",
  "risk_context": 5.0,
  "risk_intel": 0.05,
  "client_ua": "Chrome",
  "response_cache": 0,
  "message": "Origin not found in the threat DB.",
  "event_token": "06ef74884bfe78d927dbfcb2..."
}

🔐 O campo response pode conter:

  • "ACCEPT" – acesso normal
  • "NOTIFY" – comportamento suspeito, considere verificação adicional (ex.: 2FA)
  • "BLOCK" – negar acesso

A aplicação pode negar o acesso mesmo que a senha esteja correta.

💡 Exemplo Prático em PHP​

Abaixo está um exemplo simplificado de como integrar a chamada ao GuardianKey após o envio do login/senha:

require_once("guardiankey.class.php");
$GK = new guardiankey($GKconfig);

$username = $_POST['user'];
$password = $_POST['password'];

// Autentique o usuário normalmente em seu sistema
$login_failed = ($username != $password) ? 1 : 0;

$response = $GK->checkaccess($username, $username, $login_failed);
$result = json_decode($response);

if ($result->response === 'BLOCK') {
   echo "Acesso negado. Por favor, tente novamente mais tarde.";
} else {
   echo "Login autorizado!";
}

✅ O SDK PHP e outros encapsulam a criação do evento e o envio seguro.

📦 SDKs Disponíveis​

O GuardianKey fornece SDKs e exemplos para:

  • PHP
  • Python
  • Node.js
  • Java
  • .NET
  • Ruby
  • Lua
  • Classic ASP

Solicite o SDK para sua linguagem ou confira as integrações disponíveis.

🔐 Segurança e Criptografia​

Os endpoints da API GuardianKey suportam HTTPS com TLS 1.3, protegendo a comunicação dos eventos entre a integração de origem e o serviço. As integrações devem validar o certificado do servidor e utilizar um perfil TLS seguro em todo o caminho de comunicação.

Os eventos podem utilizar criptografia simétrica AES-256. Os fluxos de identidade e autenticação suportados também utilizam criptografia assimétrica RSA e ECDSA para assinaturas digitais, validação de requisições e operações WebAuthn. Esses controles fornecem confidencialidade, integridade e autenticidade aos fluxos de integração ponta a ponta suportados.

O GuardianKey não coleta senhas nem interfere no fluxo de autenticação.

🔔 Notificações (para casos NOTIFY ou HARD NOTIFY)​

O GuardianKey pode notificar o usuário e/ou administrador sobre tentativas de acesso suspeitas via e-mail.

A mensagem contém um link para o usuário confirmar se realizou o acesso.

Esse feedback do usuário é utilizado para treinar o modelo e reduzir falsos positivos.

✅ Boas Práticas​

  • Sempre valide a resposta do GuardianKey antes de conceder acesso.
  • Em caso de BLOCK, retorne uma mensagem genérica ("usuário ou senha inválidos") para evitar vazamento de informações.
  • Use o endpoint de risco em tempo real e, se desejar, implemente também notificações offline via webhook.