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.

---

📥 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 eventos podem ser enviados com criptografia simétrica (AES-256).

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.