> For the complete documentation index, see [llms.txt](https://docs.vaultid.com.br/workspace/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vaultid.com.br/workspace/cess/hubdeautenticacao/fluxo-com-popup.md).

# Fluxo com Popup

Para integrar o Certifier Auth Hub em sua aplicação, a Soluti recomenda veementemente a abertura do Hub através de uma janela Popup controlada via JavaScript.

{% hint style="danger" %}
**Não recomendamos o uso em Iframes!**\
Muitas certificadoras e provedores externos (como portais de identidade OAuth2/OpenID Connect) configuram regras rígidas de segurança como `X-Frame-Options: DENY` ou `Content-Security-Policy: frame-ancestors 'none'`. Isso impede que as telas de digitação de senhas ou consentimento sejam abertas dentro de iframes. Ao usar iframe, a autenticação falhará silenciosamente para a maior parte dos usuários.
{% endhint %}

{% hint style="info" icon="globe" %}
**Requisito Obrigatório: Cadastro de Origem (Whitelist)**\
Para que a sua aplicação receba os eventos do popup via `postMessage`, é obrigatório informar previamente à Soluti quais são os seus domínios autorizados. Se a sua URL de origem não estiver registrada na whitelist interna do Hub, a janela do popup abrirá corretamente, mas as mensagens com os eventos de retorno não serão entregues à sua aplicação.
{% endhint %}

#### Como Configurar o Popup de Forma Otimizada e Monitorar com Polling

Como o popup realiza redirecionamentos para ambientes externos das certificadoras (outros domínios), o script perde temporariamente a capacidade de ler o estado interno da janela. Para garantir que você detecte caso o usuário feche a aba durante esses redirecionamentos, você deve implementar um loop de **polling** verificando a propriedade `closed` do objeto retornado pelo `window.open`.

```javascript
// Exemplo de integração utilizando Popup e Polling de fechamento

function openAuthHub(token, loginHint = null) {
  // URL oficial de produção do Certifier Auth Hub
  const appUrl = 'https://certifierauthhub.vaultid.com.br';
  let url = `${appUrl}/?token=${token}`;
  
  if (loginHint) {
    url += `&login_hint=${encodeURIComponent(loginHint)}`;
  }
  
  // Dimensões recomendadas do popup
  const width = 460;
  const height = 680;
  
  // Centraliza o popup na tela do usuário
  const left = window.screen.width / 2 - width / 2;
  const top = window.screen.height / 2 - height / 2;

  const popupWindow = window.open(
    url,
    'CertifierAuthHubPopup',
    `width=${width},height=${height},left=${left},top=${top},menubar=no,toolbar=no,location=no,status=no,resizable=yes`
  );

  if (!popupWindow) {
    alert('O bloqueador de popups impediu a inicialização. Por favor, autorize popups.');
    return null;
  }

  // Polling para detectar se o usuário fechou o popup
  // Importante: quando o usuário é redirecionado para a página externa de uma certificadora,
  // o controle direto de scripts é perdido devido à política de mesma origem, mas a propriedade
  // 'closed' do popup continua acessível.
  const pollTimer = setInterval(() => {
    if (popupWindow.closed) {
      clearInterval(pollTimer);
      console.warn('O usuário fechou o popup de autenticação (cancelamento via fechar janela).');
      
      // Aqui você deve disparar sua lógica de cancelamento interno
      handleAuthCancel('Janela do Hub fechada pelo usuário.');
    }
  }, 1000);

  // Armazene a referência do timer e do popup para poder manipulá-los no callback de retorno
  window.authPollTimer = pollTimer;
  window.authPopupWindow = popupWindow;

  return popupWindow;
}

function handleAuthCancel(reason) {
  console.log('Autenticação cancelada:', reason);
}
```

#### Comportamentos Importantes do Popup

* **Bloqueadores de Popups:** Certifique-se de chamar a função `window.open` diretamente a partir de um evento de clique iniciado pelo usuário (ex: clique de botão). Chamadas assíncronas feitas fora de eventos diretos de clique podem ser bloqueadas pelos navegadores.
* **Dimensões:** As telas internas do Hub foram perfeitamente desenhadas e otimizadas para a proporção mobile e desktop compacto (largura de 460px e altura de 680px).