--- url: 'https://www.corbado.com/pt/blog/webauthn-mediacao-imediata' title: 'Explicação sobre a Mediação Imediata do WebAuthn' description: 'Uma análise aprofundada da mediação imediata do WebAuthn. Descubra como ela cria um único botão de login, evita códigos QR confusos e constrói um fluxo de login mais inteligente.' lang: 'pt' author: 'Vincent Delitz' date: '2025-08-08T11:41:42.609Z' lastModified: '2026-08-29T06:03:19.683Z' keywords: 'Mediação imediata WebAuthn, mediação imediata' category: 'WebAuthn Know-How' --- # Explicação sobre a Mediação Imediata do WebAuthn ## 1. Introdução: O Paradoxo das Passkeys e o Botão Único de "Entrar" A transição para passkeys está a criar um "paradoxo das passkeys": alguns utilizadores têm passkeys, enquanto muitos ainda usam as tradicionais passwords. Isto leva a ecrãs de login sobrecarregados com múltiplos botões: "Entrar com Password", "Entrar com Google" e "Entrar com Passkey". Esta fragmentação causa fricção. Um utilizador pode clicar em "Entrar com Passkey" num novo dispositivo apenas para se deparar com um confuso pedido de [código QR](https://www.corbado.com/pt/blog/login-codigo-qr-autenticacao), porque a sua passkey não está disponível localmente. O problema central é a incapacidade do site de conhecer o contexto do utilizador antes de iniciar um fluxo de [autenticação](https://www.corbado.com/pt/blog/webauthn-relying-party-id-rpid-passkeys). Uma solução é adotar uma abordagem que prioriza o identificador e determina o melhor método de login para o utilizador. Outra solução potencial é um único botão de "Entrar" inteligente que orquestra o fluxo mais simples para cada utilizador. Deveria solicitar diretamente uma passkey se houver uma disponível no dispositivo, ou recorrer de forma elegante a outros métodos, caso contrário. Foi anunciada uma nova funcionalidade do WebAuthn que pode tornar isto possível: Mediação Imediata (`mediation: 'immediate'`). Ao definir esta propriedade numa chamada à API WebAuthn, os programadores podem construir uma experiência de login inteligente e unificada que resolve o paradoxo das passkeys. Este artigo fornece uma análise focada para programadores sobre `mediation: 'immediate'`, explorando o que é, como funciona e como implementá-la. ## 2. O que é a Mediação WebAuthn? Para entender a Mediação Imediata, é útil conhecer primeiro as outras opções. **A mediação do utilizador no WebAuthn é a forma como o navegador gere a interação entre o seu site (a Relying Party) e o autenticador do utilizador** (por exemplo, [Face ID](https://www.corbado.com/faq/is-face-id-passkey), [YubiKey](https://www.corbado.com/glossary/yubikey)). ### 2.1. Mediação Modal (Comportamento Padrão) Este é o fluxo clássico e explícito do WebAuthn. Quando uma [Relying Party](https://www.corbado.com/glossary/relying-party) chama `navigator.credentials.get()` sem especificar uma preferência de `mediation`, o navegador **sempre** apresenta uma caixa de diálogo modal. Esta caixa de diálogo sobrepõe-se ao conteúdo da página, exigindo a atenção imediata do utilizador e pausando toda a outra interação com o site. - **Caso de Uso:** Ideal para botões dedicados de "Entrar com Passkey", onde o utilizador declarou claramente a sua intenção. - **Limitação:** Se o utilizador não tiver uma passkey no dispositivo atual, é-lhe mostrado um fluxo entre dispositivos (por exemplo, [código QR](https://www.corbado.com/pt/blog/login-codigo-qr-autenticacao)), o que pode ser um beco sem saída confuso. ### 2.2. Mediação Condicional: `mediation: 'conditional'` Introduzido para ajudar os utilizadores na transição para passkeys, este modo é mais subtil. Com `mediation: 'conditional'`, o pedido WebAuthn é anexado a um campo de entrada (por exemplo, nome de utilizador) com o atributo `autocomplete="webauthn"`. Quando o utilizador clica no campo, a interface de preenchimento automático do navegador sugere quaisquer passkeys disponíveis. - **Caso de Uso:** Ideal para melhorar progressivamente os formulários de login tradicionais, permitindo que os utilizadores descubram e usem passkeys sem um botão separado. - **Limitação:** Prioriza a privacidade de forma tão rigorosa que, se o utilizador não tiver uma passkey ou não interagir com o pedido, a promise da chamada à API _nunca é resolvida_. O site não recebe nenhum sinal, tornando impossível orquestrar uma interface de [fallback](https://www.corbado.com/pt/faq/login-segundo-dispositivo-chave-de-acesso-vinculada). ## 3. O que é a Mediação Imediata? `mediation: 'immediate'` é a solução para o problema do "botão de [login único](https://www.corbado.com/pt/glossary/autenticacao-unica-sso)". Fornece uma forma fiável para um site verificar a disponibilidade de uma passkey antes de mostrar qualquer interface. ### 3.1 O Conceito Central: "Pergunte, Não Mande" Em vez de _mandar_ o utilizador autenticar-se com uma passkey através de um modal, a mediação `immediate` _pergunta_ ao navegador: "Existe uma passkey prontamente disponível para este utilizador neste dispositivo _agora mesmo_?" Crucialmente, esta consulta verifica apenas credenciais _disponíveis localmente_ (por exemplo, autenticadores no dispositivo como o [Windows Hello](https://www.corbado.com/glossary/windows-hello) ou passkeys sincronizadas através de um gestor de passwords). Foi concebida para **evitar** acionar o fluxo de [código QR](https://www.corbado.com/pt/blog/login-codigo-qr-autenticacao) entre dispositivos, que é um ponto de fricção comum. ### 3.2 O Fluxo Lógico de Dois Caminhos O poder desta funcionalidade reside no seu resultado claro e binário. A promise retornada por `navigator.credentials.get()` terá sucesso ou falhará, dando ao programador um sinal claro. - **Caminho 1 (Sucesso): Existe uma Credencial.** Se o navegador encontrar uma passkey disponível localmente, ignora a interface do site e apresenta _imediatamente_ o seu próprio modal nativo, como um seletor de contas. Se o utilizador se autenticar com sucesso, a promise é resolvida com o objeto `PublicKeyCredential`. - **Caminho 2 (Falha): Não Existe Nenhuma Credencial.** Se o navegador não encontrar credenciais disponíveis localmente, não mostra **nenhuma interface**. Em vez disso, a promise de `navigator.credentials.get()` é _imediatamente_ rejeitada com uma `DOMException` chamada `NotAllowedError`. ### 3.3 Quais são os Benefícios da Mediação Imediata? O `NotAllowedError` não é um bug. É mais como uma funcionalidade. É um sinal fiável e instantâneo de que o site deve prosseguir com um método de [autenticação](https://www.corbado.com/pt/blog/webauthn-relying-party-id-rpid-passkeys) de [fallback](https://www.corbado.com/pt/faq/login-segundo-dispositivo-chave-de-acesso-vinculada). Isto permite que os programadores usem um simples bloco `try...catch`: o bloco `try` tenta o fluxo de passkey simplificado, e o bloco `catch` escuta por `NotAllowedError` para renderizar um formulário de login tradicional. Resolve elegantemente o problema do botão de [login único](https://www.corbado.com/pt/glossary/autenticacao-unica-sso), criando um ponto de entrada que se adapta inteligentemente ao contexto do utilizador. ## 4. Comparação entre Mediação Imediata, Condicional e Modal Escolher o modo de mediação correto é uma decisão crítica de UX. Esta tabela fornece uma comparação lado a lado. | Funcionalidade / Comportamento | Modal (Padrão) | UI Condicional (`conditional`) | Imediata (`immediate`) | | ------------------------------------------------ | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | **Chamada à API** | `navigator.credentials.get()` | `navigator.credentials.get({ mediation: 'conditional' })` | `navigator.credentials.get({ mediation: 'immediate' })` | | **Gatilho** | Ação explícita do utilizador (ex: clique no botão) | Carregamento da página; UI ao focar no campo de entrada | Ação explícita do utilizador (ex: clique no botão) | | **Apresentação da UI** | **Sempre** mostra uma caixa de diálogo modal imediatamente. | Mostra uma UI não modal, estilo preenchimento automático. | **Apenas se** for encontrada uma credencial local, mostra uma caixa de diálogo modal. | | **Comportamento se Não Houver Credencial Local** | Mostra UI para fluxos entre dispositivos (ex: código QR). | A promise permanece pendente, nunca é resolvida, nenhum erro é lançado. | A promise é **imediatamente rejeitada** com `NotAllowedError`. | | **Conhecimento do Site** | Não aprende nada até o utilizador completar o fluxo. | Não aprende nada se o utilizador não interagir. Privacidade máxima. | Aprende uma informação: se existe uma credencial local. | | **Caso de Uso Principal** | Botão dedicado "Entrar com Passkey". 2FA explícito. | Formulários unificados de login/registo. Melhoria progressiva de formulários de password. | Um único botão principal de "Entrar" para uma base de utilizadores mista. | | **Ação do Programador** | Lidar com sucesso ou cancelamento do utilizador. | Lidar com sucesso. Nenhum sinal de falha para agir. | Lidar com sucesso ou `NotAllowedError` para acionar uma UI de fallback. | ## 5. Como Implementar a Mediação Imediata Aqui está um guia prático, passo a passo, para implementar `mediation: 'immediate'`. ### 5.1. Passo 1: Deteção da Funcionalidade Como `mediation: 'immediate'` é uma nova funcionalidade, a deteção robusta da funcionalidade é crucial. ```javascript // A deteção da funcionalidade é essencial para a melhoria progressiva. let immediateMediationAvailable = false; if (window.PublicKeyCredential && PublicKeyCredential.getClientCapabilities) { try { const capabilities = await PublicKeyCredential.getClientCapabilities(); // A capacidade 'immediateGet' sinaliza o suporte do navegador. immediateMediationAvailable = capabilities.immediateGet === true; } catch (e) { console.error("Error getting client capabilities:", e); } } ``` ### 5.2 Passo 2: A Chamada `navigator.credentials.get()` Esta chamada deve ser acionada por um gesto do utilizador, como o clique num botão. ```javascript // Esta função deve ser o manipulador de eventos para o seu botão principal de "Entrar". async function handleSignInClick() { if (!immediateMediationAvailable) { // Recorrer a mostrar um formulário de login legado se a funcionalidade não for suportada. showLegacyLoginForm(); return; } try { // Obtenha um desafio novo e aleatório do seu servidor para cada tentativa. const challenge = await fetchChallengeFromServer(); const publicKeyCredentialRequestOptions = { challenge: challenge, // O desafio fornecido pelo servidor como um Uint8Array rpId: "example.com", // A lista allowCredentials DEVE estar vazia para a mediação imediata // para proteger a privacidade do utilizador. allowCredentials: [], }; const credential = await navigator.credentials.get({ publicKey: publicKeyCredentialRequestOptions, // Esta é a chave que ativa o fluxo de mediação imediata. mediation: "immediate", }); // Se a promise for resolvida, envie a credencial para o seu servidor para verificação. await verifyCredentialOnServer(credential); } catch (error) { // O bloco catch é uma parte crítica do fluxo de controlo. handleAuthError(error); } } ``` ### 5.3 Passo 3: Lidar com `NotAllowedError` para um Fallback Elegante O bloco `catch` é onde a "inteligência" do botão de [login único](https://www.corbado.com/pt/glossary/autenticacao-unica-sso) é realizada. ```javascript // Lidar com o NotAllowedError é a chave para o mecanismo de fallback. function handleAuthError(error) { // Verifique a propriedade 'name' da DOMException. if (error.name === "NotAllowedError") { // Este é o sinal esperado para mostrar o formulário de login tradicional. console.log( "Nenhuma passkey local encontrada. A mostrar formulário de login legado.", ); showLegacyLoginForm(); } else { // Isto lida com outros erros potenciais, como o utilizador dispensar o pedido. console.error("Erro de autenticação:", error); } } ``` ### 5.4 Passo 4: Criar um Fluxo Unificado com Passwords Para a experiência mais integrada, pode pedir ao navegador para procurar tanto por passkeys como por passwords guardadas no mesmo pedido, adicionando `password: true`. ```javascript // Combinar passkeys e passwords para uma experiência de login verdadeiramente unificada. const credential = await navigator.credentials.get({ publicKey: publicKeyCredentialRequestOptions, password: true, // Peça ao navegador para incluir passwords guardadas. mediation: "immediate", }); // O objeto 'credential' retornado será um PublicKeyCredential // ou um PasswordCredential. A sua lógica do lado do servidor deve lidar com ambos. ``` ### 5.5. Evitar Armadilhas Comuns 1. **Pedidos WebAuthn Concorrentes:** Um pedido `conditional` pendente (muitas vezes iniciado no carregamento da página) pode bloquear um novo pedido `immediate`. Considere usar um `AbortController` para cancelar quaisquer pedidos pendentes antes de iniciar um novo. 2. **A Restrição `allowCredentials`:** O array `allowCredentials` **deve** estar vazio. Fornecer IDs de credenciais fará com que a chamada falhe. Esta é uma salvaguarda de privacidade crucial para impedir que os sites verifiquem utilizadores específicos e conhecidos. 3. **O Requisito de Gesto do Utilizador:** A chamada deve ser iniciada a partir de um gesto do utilizador (por exemplo, um evento de 'clique'). Chamá-la programaticamente no carregamento da página será bloqueado pelos navegadores como uma medida de proteção de privacidade. ## 6. Segurança e Privacidade da Mediação Imediata `mediation: 'immediate'` foi concebida com uma clara compreensão das suas contrapartidas de [segurança](https://www.corbado.com/pt/blog/senhas-complexas-quebradas-em-breve) e privacidade. ### 6.1. O "Vazamento de Um Bit": Reconhecendo a Contrapartida A principal contrapartida é um "vazamento de um bit". Ao cronometrar a resolução da promise, uma [Relying Party](https://www.corbado.com/glossary/relying-party) pode inferir uma informação: se a promise foi rejeitada instantaneamente (nenhuma credencial local) ou foi atrasada (um pedido na UI foi mostrado porque uma credencial local foi encontrada). O propósito deste vazamento é permitir uma melhor UX. ### 6.2. Porque é que Este é um Risco Aceitável: As Salvaguardas Integradas Os criadores anteciparam o potencial de abuso (por exemplo, rastreamento de utilizadores) e integraram várias salvaguardas não negociáveis: 1. **Gesto Obrigatório do Utilizador:** A chamada à API deve ser acionada por uma ação do utilizador, como um clique. Isto impede que um site sonde silenciosamente por contas no carregamento da página e torna o fingerprinting em larga escala impraticável. 2. **Desativado no Modo Privado/Anónimo:** A funcionalidade é desativada nos modos de navegação privada para impedir a ligação da atividade de um utilizador entre sessões normais e privadas. 3. **Lista `allowCredentials` Proibida:** O array `allowCredentials` deve estar vazio. Isto impede que um site use esta funcionalidade para verificar se um utilizador _específico_ e conhecido está a visitar. 4. **Apenas Contexto de Primeira Parte:** A funcionalidade é desativada em contextos de terceiros (por exemplo, um `iframe` de outra origem) para impedir o rastreamento entre sites. Estas mitigações garantem que as garantias de [segurança](https://www.corbado.com/pt/blog/senhas-complexas-quebradas-em-breve) centrais do WebAuthn permanecem intactas. A cerimónia de [autenticação](https://www.corbado.com/pt/blog/webauthn-relying-party-id-rpid-passkeys) em si não é alterada e permanece resistente a [phishing](https://www.corbado.com/glossary/phishing). ## 7. Suporte dos Navegadores para a Mediação Imediata `mediation: 'immediate'` é uma funcionalidade avançada da [especificação WebAuthn Nível 3](https://w3c.github.io/webauthn/), e o seu lançamento está em curso. A partir de meados de 2025, uma estratégia de melhoria progressiva é essencial. | Navegador | Estado | Notas e Fonte | | ------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | **Chrome** | **Em teste para programadores** | Disponível através da flag `experimental-web-platform-features`. [Bug de acompanhamento](https://issues.chromium.org/issues/408002783). | | **Edge** | Em Desenvolvimento (Esperado) | Como um navegador Chromium, o suporte deve seguir o do Chrome. | | **Safari (WebKit)** | Em Consideração | [Posições de Padrões do WebKit](https://github.com/WebKit/standards-positions/issues/504). Sem compromisso público. | | **Firefox (Gecko)** | Em Consideração | [Posições de Padrões da Mozilla](https://github.com/mozilla/standards-positions/issues/1239). Sem compromisso público. | ## 8. Mediação Imediata vs. Passkey Intelligence Embora `mediation: 'immediate'` forneça uma ótima ferramenta de baixo nível para um botão de login mais inteligente, é importante distingui-la de uma solução mais ampla de "[Passkey Intelligence](https://docs.corbado.com/corbado-connect/features/passkey-intelligence)", como a oferecida pela Corbado. Ambas visam resolver o paradoxo das passkeys e aumentar a adoção, mas fazem-no de maneiras diferentes. | Funcionalidade | `mediation: 'immediate'` | Passkey Intelligence (ex: Corbado) | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Como Funciona** | Uma chamada à API nativa do navegador que verifica a existência de passkeys disponíveis localmente no dispositivo atual. | Um serviço de backend que recolhe e analisa dados sobre dispositivos de utilizadores, autenticadores e histórico de logins entre sessões. | | **Sinal Fornecido** | Um sinal simples e binário: uma passkey local existe (`pedido na UI`) ou não existe (`NotAllowedError`). | Insights ricos e contextuais, por exemplo, "Este utilizador acabou de fazer login com uma password num dispositivo compatível com passkeys que usa frequentemente." | | **Vantagem Chave** | Verificação nativa muito rápida com sobrecarga de rede mínima. | Disponibilidade universal, independente do suporte do navegador/SO para novas funcionalidades WebAuthn. Insights mais profundos para uma UX mais personalizada. | | **Dependência Principal** | Requer suporte atualizado do navegador e do SO, que ainda não é universal. | Integração com um serviço de backend. | **Passkey Intelligence** vai um passo além, recolhendo e avaliando dados ao longo do tempo. Isto permite intervenções mais sofisticadas e oportunas junto do utilizador. Por exemplo, um backend de [Passkey Intelligence](https://docs.corbado.com/corbado-connect/features/passkey-intelligence) pode detetar: - Um utilizador que se autentica com sucesso com uma password num novo dispositivo compatível com passkeys e sugere que adicione uma passkey para a próxima vez. - Um utilizador que completa um login "híbrido" entre dispositivos e sugere imediatamente que registe o novo dispositivo. - Um utilizador que falha o login num novo dispositivo e oferece a criação de passkey como uma opção de recuperação ou configuração (recuperação automática). Esta abordagem orientada por dados é independente do suporte do navegador para `mediation: 'immediate'`, o que significa que pode fornecer um fluxo de login mais inteligente para todos os seus utilizadores, agora mesmo. **O Melhor de Dois Mundos** Em última análise, estas duas abordagens não são mutuamente exclusivas; são complementares. A solução ideal combina-as: 1. Use um serviço de **Passkey Intelligence** como o cérebro do seu processo de login. 2. O serviço pode então usar `mediation: 'immediate'` como um dos seus sinais em navegadores suportados para realizar uma verificação inicial rápida. 3. Com base no resultado — ou na falta de suporte para a funcionalidade — o serviço de inteligência pode então usar os seus dados históricos mais ricos para orquestrar o [fallback](https://www.corbado.com/pt/faq/login-segundo-dispositivo-chave-de-acesso-vinculada) perfeito, seja mostrando um campo de password ou oferecendo um pedido de criação de passkey no momento certo. Ao combinar a velocidade nativa de `mediation: 'immediate'` com os insights profundos de um backend de [Passkey Intelligence](https://docs.corbado.com/corbado-connect/features/passkey-intelligence), pode fornecer a experiência de login mais integrada, adaptativa e eficaz possível, guiando suavemente cada utilizador em direção a um futuro sem passwords. ## 9. O Impacto para o Negócio da Mediação Imediata A Mediação Imediata é uma grande melhoria na experiência de login. Fornece a inteligência necessária para eliminar pontos comuns de fricção e confusão para os utilizadores durante a transição para passkeys. - **Reduz a Confusão do Utilizador:** Ao permitir um único botão de "Entrar", a mediação `immediate` remove a carga cognitiva para o utilizador. Eles já não precisam de se lembrar qual o método de autenticação que configuraram ou escolher de uma lista sobrecarregada de opções. O processo de login torna-se mais simples e intuitivo. - **Previne Abandono de Logins com Passkey:** Uma razão comum pela qual os utilizadores abandonam um login com passkey é o aparecimento inesperado de um código QR para um fluxo entre dispositivos. Como `mediation: 'immediate'` apenas procura por credenciais locais, evita completamente este estado confuso. Em vez de o utilizador abandonar o fluxo, a aplicação recebe um sinal claro (`NotAllowedError`) para recorrer elegantemente a outro método, resultando numa jornada mais suave. - **Cria um Fluxo Integrado e Inteligente:** O benefício principal é uma experiência de login inteligente. A aplicação pode perguntar ao navegador se um login com passkey integrado é possível antes de se comprometer com uma UI. Esta abordagem de "Pergunte, Não Mande" garante que os utilizadores apenas veem pedidos que são relevantes para eles. Faz com que o login pareça inteligente e adaptativo, reforçando a conveniência das passkeys e incentivando o seu uso contínuo. ## 10. Conclusão: Mediação Imediata A Mediação Imediata é uma nova funcionalidade do WebAuthn que resolve a experiência de login fragmentada do período de transição para passkeys. Permite a criação de um único botão de "Entrar" inteligente que se adapta ao contexto do utilizador, eliminando confusão e fricção. Embora introduza uma contrapartida de privacidade calculada, inclui salvaguardas robustas para mitigar riscos sem comprometer a [segurança](https://www.corbado.com/pt/blog/senhas-complexas-quebradas-em-breve) central do WebAuthn. Para os programadores, o caminho a seguir é a melhoria progressiva. Construa uma experiência de base sólida e adicione a mediação `immediate` por cima para os navegadores suportados. Adotar esta funcionalidade é um movimento estratégico para acelerar a adoção de passkeys, aumentar a segurança, reduzir os custos operacionais e melhorar a conversão. Implementar estes fluxos de autenticação avançados pode ser complexo. A Plataforma de Passkeys Empresarial da Corbado abstrai esta complexidade. A nossa [infraestrutura](https://www.corbado.com/passkeys-for-critical-infrastructure) lida com a orquestração ótima do fluxo — incluindo mediação condicional e `immediate`, permitindo que a sua equipa implemente uma experiência de autenticação de ponta e sem fricção com confiança.