Pular para o conteúdo principal

Como Integrar

O GuardianKey Auth Bastion Enterprise foi projetado para oferecer integração rápida, segura e flexível com qualquer sistema Web, sem a necessidade de alterar o código-fonte da aplicação original. A seguir, apresentamos uma visão geral das possibilidades de integração da solução.

⚠️ Importante: cada caso de integração é analisado e apoiado individualmente pela equipe de Sucesso do Cliente da GuardianKey, garantindo compatibilidade, segurança e desempenho. Para integrações específicas, entre em contato com nosso suporte técnico.

📌 TOC (Table of Contents)​

🎯 Objetivos de Integração​

A integração com o bastião pode ocorrer com dois objetivos distintos:

1. 🛡️ Proteger sistemas com autenticação em dois fatores (2FA)​

O bastião intercepta a rota de autenticação do sistema, exigindo uma verificação adicional (TOTP, e-mail, SMS) antes de permitir o acesso ao formulário de login.

2. 🆔 Oferecer login via OAuth2/OIDC​

O bastião substitui ou complementa o login original do sistema, permitindo autenticação federada com o GovBR diretamente pela interface do bastião.

Especificação do módulo integrador OAuth2/OICD

1️⃣ Integração para Proteção com 2FA​

Requisitos​

  • O sistema a ser protegido deve ser uma aplicação Web.
  • O bastião deve ser capaz de receber diretamente as conexões do usuário final (ou via proxy que preserve o IP original).
  • O sistema protegido deve ser acessível pelo bastião (internamente ou externamente).
  • É necessário definir:
    • Domínio (FQDN) da aplicação.
    • Caminho protegido (ex: /login, /auth).
    • Servidores backend (para redirecionamento após autenticação).
    • Tipo de autenticação 2FA: TOTP, e-mail ou outros.
    • Método de registro de usuários: e-mail, credenciais, API, bastião.

Fluxo Geral​

Usuário acessa sistema → Interceptado pelo bastião → Valida 2FA → Redirecionado ao formulário de login → Login realizado → Acesso concedido

Possibilidades​

  • A validação de 2FA ocorre antes do login original.
  • O bastião pode usar endpoints do sistema para buscar o e-mail do usuário ou validar credenciais (se necessário).
  • A sessão autenticada gera um token vinculado ao IP e com tempo de expiração (TTL).

📌 Dica: use User Pool para compartilhar usuários 2FA entre múltiplos authgroups.

2️⃣ Integração com Login via GovBR (OAuth2/OIDC)​

Requisitos​

  • O sistema deve ser Web e acessível pelo bastião.
  • O sistema protegido precisa ter o meesmo username que será autênticado no autênticador Oauth2/OIDC, para ser possível a correção do usuário; no caso o autenticador for o Gov.br o sistema protegido precisa ter o CPF do usuário em sua base.

Características da Integração​

  • Toda a lógica OAuth2 é gerenciada dentro do bastião.
  • O botão "Login com GovBR" é injetado automaticamente na interface de login, com template personalizável.

Após o login no GovBR:​

  • O bastião realiza a associação do usuário por CPF (ou username, de acordo com a configuração do autenticador).
  • O usuário é redirecionado para a URL original solicitada, já autenticado.

Modos de Uso:​

  • Exclusivo: substitui o login padrão.
  • Opcional: o usuário escolhe entre login GovBR ou tradicional.

⚠️ Para proteção adicional, é possível ativar integração com o GuardianKey Auth Security (score de risco), porém não é compatível com 2FA nesse modo.

Fluxo Geral​

Usuário acessa sistema → Escolhe "Login com GovBR" → Autenticação OAuth2 → CPF retornado → Usuário autenticado → Redirecionamento à aplicação

🧩 Modelagem Recomendada​

A estrutura básica de uma integração no painel do Bastion envolve:

Organization
 └── Domain Name (ex: app.empresa.com.br)
            └── Authgroup (ex: Sistema RH)
                     ├── Caminhos protegidos (ex: /login)
                     ├── Método de autenticação (Oauth2/GovBR)
                     ├── Oauth2 Integrations (chaves e endpoints do autenticador)
                     └── Backends (IP ou host do sistema protegido)

É necessário configurar também um agente integrador, que faz a criação da sessão autenticada no sistema que será protegido.

🧠 Dicas para Integração Eficiente​

  • Defina claramente qual caminho será protegido (ex: /login).
  • Escolha o tipo de autenticação mais apropriado ao seu público (ex: e-mail para portais públicos, TOTP para internos).
  • Certifique-se de que o bastião pode comunicar-se com o sistema protegido (DNS interno, firewall etc.).
  • Considere reusar pools de usuários se mais de um sistema compartilhar a base de usuários.
  • Ao usar GovBR, garanta que o sistema identifique corretamente o CPF do usuário.

🤝 Suporte à Integração​

A GuardianKey oferece apoio completo à integração, com suporte técnico e orientação especializada por meio da equipe de Sucesso do Cliente. Para garantir a segurança e funcionamento adequado, recomendamos que qualquer nova integração seja validada com nosso time.

📩 Entre em contato via [email protected] ou seu canal dedicado.