Usando o SDK (Exemplo em PHP)

Repositórios oficiais

Outros SDKs

Verifique a organização GuardianKey para possíveis novos SDKs: https://github.com/guardiankey

Objetivo

Este documento fornece um exemplo prático de uso do SDK GKTinc em PHP.

Importante:
O SDK GKTinc é agnóstico quanto à linguagem.
O PHP é usado aqui apenas como exemplo de implementação por ser comum em aplicações web, WordPress e sistemas legados.

Os mesmos conceitos se aplicam a qualquer linguagem ou framework que consuma a API GKTinc.

Visão geral do fluxo

A integração envolve dois pontos principais:

Lado do servidor (PHP)

Gerar o objeto de configuração JavaScript (gktinc_config)
Validar o desafio após o envio do formulário

Lado do cliente (JavaScript)

Resolver o desafio automaticamente
Inserir gktinc_solution no POST do formulário

Fluxo simplificado:

Usuário abre a página de login
↓
Servidor gera gktinc_config (SDK PHP)
↓
JS resolve o desafio automaticamente
↓
Formulário é enviado com gktinc_solution
↓
Servidor valida o desafio (SDK PHP)

Requisitos

PHP 5.5 ou superior
Acesso à API GKTinc
Incluir o JavaScript oficial do GKTinc no front-end

Configuração básica do SDK (PHP)

Exemplo de inicialização

$config = array(
  'api_key' => 'YOUR_API_KEY',
  'protectiongroup_hashid' => 'YOUR_HASHID',
  'default_challenge_level' => 3,
  'api_url' => 'https://api.guardiankey.io/',
  'sslverify' => true,
  'log_file' => __DIR__ . '/gktinc.log',
);

$sdk = new GKTincSDK($config);

Principais parâmetros:

Parâmetro	Descrição
api_key	Chave de API do GKTinc
protectiongroup_hashid	Identificador do grupo protegido
default_challenge_level	Nível de desafio padrão
api_url	URL base da API (opcional)
sslverify	Verificação SSL (booleano)
log_file	Caminho do arquivo de log (opcional)

Gerando a configuração JavaScript

O SDK gera dinamicamente o objeto gktinc_config usado pelo JS do navegador.

Exemplo (PHP):

echo '<script>';
echo $sdk->get_javascript_config(
  true,  // pre_check: consultar o nível de desafio antes de renderizar
  true   // pre_enforce_block: bloquear se o pré-check retornar BLOCK
);
echo '</script>';

Coloque isto antes de carregar o JavaScript do GKTinc.

Incluindo o JavaScript do GKTinc

Adicione o script oficial no front-end:

<script src="https://guardiankey.io/js/gktinc-setup-latest.js"></script>

Inicializando o GKTinc no formulário

Anexe o GKTinc ao formulário de login (ou outro formulário sensível).

Exemplo (HTML + JS):

<form id="loginform" method="post">
  <input type="text" id="username" name="username">
  <input type="password" name="password">
  <button type="submit">Login</button>
</form>

<script>
  var formElement = document.getElementById('loginform');
  var inputElement = document.getElementById('username');

  gktinc_init(
   gktinc_config,
   formElement,
   inputElement,
   true
  );
</script>

Neste ponto:

O desafio é resolvido automaticamente
O campo gktinc_solution é inserido no POST

Validando o desafio no backend (PHP)

Após o envio do formulário, valide o desafio usando o SDK.

Exemplo:

if (!empty($_POST['gktinc_solution'])) {
  $username = isset($_POST['username']) ? $_POST['username'] : '';

  $result = $sdk->validate_challenge(
   $username,
   true // indica que um pré-check ocorreu antes
  );

  if ($result['action'] === 'BLOCK') {
   die('Acesso bloqueado pelo GKTinc');
  }
}

O resultado da validação inclui (entre outros campos):

action: ACCEPT ou BLOCK
score: pontuação de risco
country, city
ip_policy

Comportamento fail-open

Por padrão o SDK opera em modo fail-open:

Se a API estiver indisponível
Se gktinc_solution não estiver presente no POST
Se houver um erro de comunicação

→ O acesso não é bloqueado automaticamente.

Ajuste esse comportamento conforme a política de segurança da sua aplicação.

Observações

Este documento mostra um exemplo em PHP; o fluxo é o mesmo para qualquer linguagem.
Você pode chamar a API do GKTinc diretamente sem usar o SDK.
O JavaScript é necessário para gerar o gktinc_solution.
O SDK abstrai o cálculo de salt, montagem do payload e tratamento de erros.

Para integrações em outras linguagens, veja o uso da API e exemplos específicos de stack.

Repositórios oficiais​

Outros SDKs​

Objetivo​

Visão geral do fluxo​

Requisitos​

Configuração básica do SDK (PHP)​

Exemplo de inicialização​

Gerando a configuração JavaScript​

Incluindo o JavaScript do GKTinc​

Inicializando o GKTinc no formulário​

Validando o desafio no backend (PHP)​

Comportamento fail-open​

Observações​