Integração Web

🔗 Integração Web

Este guia mostra como adicionar o coletor do Auth Security XE à sua página de login e ligar a chamada checkaccessxe no backend. Os exemplos usam PHP e a guardiankey.class.php de referência, mas o contrato é o mesmo em qualquer linguagem.

Requisitos: uma página de login renderizada no servidor (ou alcançável por ele) onde você possa injetar um gkas_config por carregamento, e um endpoint de backend que processe o POST de login.

---

1. Gere a config no carregamento da página (GET)

A cada carregamento, gere um nonce de uso único (once), guarde‑o na sessão e monte o gkas_config que o coletor precisa. url, salt, once e time vinculam a tentativa.

<?php
session_start();

// Nonce novo por carregamento, guardado na sessão para o POST verificar.
if ($_SERVER['REQUEST_METHOD'] === 'GET' || empty($_SESSION['gkas_nonce'])) {
    $_SESSION['gkas_nonce']      = bin2hex(random_bytes(16));
    $_SESSION['gkas_nonce_time'] = time();
}

$origin = (isset($_SERVER['HTTPS']) && $_SERVER['HTTPS'] !== 'off' ? 'https' : 'http')
        . '://' . $_SERVER['HTTP_HOST'];

$gkas_config = [
    'url'  => $origin . $_SERVER['PHP_SELF'],
    'salt' => 'demo_salt',
    'once' => $_SESSION['gkas_nonce'],
    'time' => (string) time(),
];
?>

---

2. Carregue o coletor e inicialize‑o

Inclua o script hospedado do GuardianKey e chame gkas_init(...) com a config, o elemento do seu formulário e o nome do campo de usuário. O coletor liga‑se ao formulário; no submit ele monta o gkas_solution e o injeta como campo oculto antes do POST sair.

<form id="form" method="POST" action="">
  <input id="username" name="username" type="text" autocomplete="username">
  <input id="password" name="password" type="password" autocomplete="current-password">
  <input type="submit" value="Entrar">
</form>

<script src="https://guardiankey.io/js/gkas-setup-latest.js?v=1"></script>
<script>
  const gkas_config = <?= json_encode($gkas_config, JSON_UNESCAPED_SLASHES) ?>;
  // gkas_init(config, formElement, nomeDoCampoUsuario, debug?)
  gkas_init(gkas_config, document.getElementById('form'), "username", false);
</script>

Essa é a mudança inteira no frontend: um <script> e uma chamada gkas_init. Tudo o que o coletor faz é encapsulado; você nunca lê nem monta o gkas_solution.

💡 Passe true como último argumento de gkas_init para habilitar um painel de debug durante o desenvolvimento.

---

3. Trate o POST de login e chame checkaccessxe

No submit, o seu backend recebe username, password e gkas_solution. Valide o nonce, autentique o usuário normalmente, defina o flag de tentativa ("0" quando a senha está correta, "1" caso contrário) e chame checkaccessxe com os mesmos url/salt/once/time que você gerou no GET — repassando o gkas_solution inalterado.

<?php
require_once 'guardiankey.class.php';

$GKconfig = [
    'agentid'     => 'sdk',
    'key'         => 'BASE64_KEY',          // da sua config segura — nunca na página
    'iv'          => 'BASE64_IV',
    'service'     => 'TestServicePHP',
    'orgid'       => 'YOUR_ORG_ID',
    'authgroupid' => 'YOUR_AUTHGROUP_ID',
    'api_key'     => '',
    'reverse'     => 'True',
];
$GKconfig['api_key'] = hash('sha256', $GKconfig['key'] . $GKconfig['iv']);

$gk = new guardiankey($GKconfig);

if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    // 1) Valide / consuma o nonce (existe, não expirado, não reutilizado).
    //    (compare $_SESSION['gkas_nonce'] com $gkas_config['once'])

    // 2) Autentique o usuário com o seu próprio sistema normalmente.
    $passwordOk = check_password($_POST['username'], $_POST['password']);
    $attempt    = $passwordOk ? "0" : "1";

    // 3) Chame o XE com as mesmas entradas do challenge + a solução opaca.
    $ret = $gk->checkaccessxe(
        $_POST['username'],
        "",                       // useremail (opcional)
        $gkas_config['url'],
        $gkas_config['salt'],
        $gkas_config['once'],
        $gkas_config['time'],
        $_POST['gkas_solution'],  // repasse inalterado
        $attempt
    );

    $result = json_decode($ret);

    // 4) Aja conforme a decisão (veja o passo 4).
}

---

4. Aja conforme a decisão

O checkaccessxe retorna o mesmo modelo de resposta do Auth Security clássico. O campo response dirige a sua ação:

response	Significado	Ação sugerida
ACCEPT	Acesso normal	Permitir o login.
NOTIFY	Comportamento suspeito	Permitir, mas considerar verificação extra (ex.: 2FA) e/ou notificar o usuário.
BLOCK	Risco alto	Negar o acesso — mesmo que a senha esteja correta.

if (isset($result->response) && $result->response === 'BLOCK') {
    // Mensagem genérica para evitar vazamento de informação.
    http_response_code(403);
    echo "Usuário ou senha inválidos.";
} else {
    // ACCEPT (ou NOTIFY com o seu passo extra) → prossiga com a sessão.
    start_user_session($_POST['username']);
}

---

✅ Checklist

• GET monta um once (nonce) novo por carregamento e o guarda na sessão.
• Página de login carrega gkas-setup-latest.js e chama gkas_init(config, form, "username").
• POST valida/consome o nonce.
• Flag de tentativa definido: "0" senha correta, "1" caso contrário.
• checkaccessxe(...) chamado com os mesmos url/salt/once/time e o gkas_solution inalterado.
• Decisão tratada: BLOCK nega; ACCEPT/NOTIFY prosseguem (com step‑up opcional).

Veja a referência de backend e API para a assinatura completa de checkaccessxe, os campos de gkas_config e o formato da resposta.