Pular para o conteúdo principal

Visão Geral

🧠 Auth Security XE​

O Auth Security XE (o fluxo checkaccessxe) estende o Auth Security com um coletor no frontend. Além do evento de servidor que o Auth Security clássico já envia, o XE adiciona um pequeno trecho de JavaScript na sua página de login que captura sinais do dispositivo e do comportamento em um token opaco gkas_solution. Esse token é enviado ao GuardianKey junto com o evento de login, produzindo uma decisão de risco em tempo real mais rica e precisa (ACCEPT / NOTIFY / BLOCK) e uma identidade de dispositivo mais forte.

É a contraparte web do SDK Mobile: o navegador executa o coletor JavaScript, enquanto apps nativos executam o SDK — ambos alimentam a mesma chamada de backend checkaccessxe.

🆚 Auth Security vs. Auth Security XE​

Auth Security (clássico)Auth Security XE
Origem dos sinaisApenas evento de backend (IP, usuário, resultado, User‑Agent…)Evento de backend + coletor de frontend (gkas_solution)
Mudança no frontendNenhumaAdicionar um <script> e uma chamada de init na página de login
Chamada de backendcheckaccess(...)checkaccessxe(...)
Identidade de dispositivoApenas contextualSinais de identidade mais fortes, ligados ao dispositivo
DecisãoACCEPT / NOTIFY / BLOCKACCEPT / NOTIFY / BLOCK (mesmo modelo de resposta)

O XE é aditivo: você mantém o mesmo modelo de risco, console e tratamento de resposta, e ganha os sinais de frontend. Se você já integra o Auth Security clássico, migrar para o XE é basicamente adicionar o coletor e trocar a chamada de backend.

🧩 O que você integra​

PeçaQuem fornecePapel
Script coletor (gkas-setup-latest.js)GuardianKey (hospedado)Roda na sua página de login; monta o token gkas_solution no submit.
Sua página de loginVocêCarrega o script, monta o gkas_config, chama gkas_init(...).
Seu backendVocêGera o nonce por carregamento, valida‑o, chama checkaccessxe com as suas credenciais GuardianKey.

🔐 As credenciais GuardianKey (key/iv/agentid/…) ficam apenas no seu backend. O navegador nunca as possui. A página só recebe um gkas_config de vida curta (url/salt/once/time) do seu próprio backend.

🔄 Fluxo​

   ┌──────────────┐  1. GET página de login           ┌──────────────┐
   │  Navegador   │ ────────────────────────────────▶ │  Seu backend │  gera nonce (once),
   │ (login page) │ ◀──────────────────────────────── │              │  monta gkas_config
   └──────────────┘   HTML + gkas_config {url,salt,    └──────────────┘
          │                       once,time}
          │ 2. gkas_init(config, form, "username")
          │    coletor liga-se ao form; no submit monta o gkas_solution
          ▼
   ┌──────────────┐  3. POST (username, password,     ┌──────────────┐   checkaccessxe   ┌────────────┐
   │  Navegador   │ ───── gkas_solution) ───────────▶ │  Seu backend │ ────────────────▶ │ GuardianKey│
   │              │ ◀──────────────────────────────── │              │ ◀──────────────── │    XE      │
   └──────────────┘   página reage à decisão          └──────────────┘  decisão de risco └────────────┘
                                                              │
                                                              ├─ ACCEPT → permite o login
                                                              ├─ NOTIFY → permite + verificação extra
                                                              └─ BLOCK  → nega o acesso
  1. Carregamento da página (GET) — o seu backend gera um nonce de uso único (once), guarda‑o na sessão e embute um gkas_config (url, salt, once, time) na página.
  2. Init do coletor — gkas_init(gkas_config, form, "username") liga‑se ao seu formulário de login; quando o usuário envia, ele monta o gkas_solution e o injeta no formulário como um campo oculto.
  3. Submit (POST) — o formulário envia usuário, senha e gkas_solution. O seu backend valida o nonce, define o flag de tentativa e chama checkaccessxe, repassando o gkas_solution inalterado. Em seguida, age conforme a decisão.

📦 Sinais coletados​

O coletor reúne uma série de informações do dispositivo e do comportamento (como sinais de dispositivo/identidade, comportamento de interação, ambiente, geolocalização, entre outros) e as empacota no token opaco gkas_solution.

O que importa para a integração:

  • Best‑effort. Capacidades ausentes do navegador ou permissões negadas (ex.: geolocalização) nunca quebram o fluxo — o sinal correspondente é simplesmente omitido.
  • Sem senhas, sem conteúdo digitado. O GuardianKey não coleta credenciais.
  • Sem trabalho de schema no backend. O seu backend repassa o token como está; a guardiankey.class.php de referência já o empacota para o checkaccessxe.

⏭️ Próximos passos​