Explicação sobre a Mediação Imediata do WebAuthn

60-page Enterprise Passkey Whitepaper:
Learn how leaders get +80% passkey adoption. Trusted by Rakuten, Klarna & Oracle

Get free Whitepaper

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, 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.

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.

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, YubiKey).

Este é o fluxo clássico e explícito do WebAuthn. Quando uma 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), o que pode ser um beco sem saída confuso.

Want to experiment with passkey flows? Try our Passkeys Debugger.

Try for Free

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.

mediation: 'immediate' é a solução para o problema do "botão de login único". Fornece uma forma fiável para um site verificar a disponibilidade de uma passkey antes de mostrar qualquer interface.

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 ou passkeys sincronizadas através de um gestor de passwords). Foi concebida para evitar acionar o fluxo de código QR entre dispositivos, que é um ponto de fricção comum.

Want to try passkeys yourself in a passkeys demo?

Try Passkeys

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.

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 de fallback. 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, criando um ponto de entrada que se adapta inteligentemente ao contexto do utilizador.

Escolher o modo de mediação correto é uma decisão crítica de UX. Esta tabela fornece uma comparação lado a lado.

Aqui está um guia prático, passo a passo, para implementar mediation: 'immediate'.

Como mediation: 'immediate' é uma nova funcionalidade, a deteção robusta da funcionalidade é crucial.

// 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);
    }
}

Esta chamada deve ser acionada por um gesto do utilizador, como o clique num botão.

// 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);
    }
}

O bloco catch é onde a "inteligência" do botão de login único é realizada.

// 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);
    }
}

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.

// 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.

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.

mediation: 'immediate' foi concebida com uma clara compreensão das suas contrapartidas de segurança e privacidade.

A principal contrapartida é um "vazamento de um bit". Ao cronometrar a resolução da promise, uma 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.

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 centrais do WebAuthn permanecem intactas. A cerimónia de autenticação em si não é alterada e permanece resistente a phishing.

mediation: 'immediate' é uma funcionalidade avançada da especificação WebAuthn Nível 3, e o seu lançamento está em curso. A partir de meados de 2025, uma estratégia de melhoria progressiva é essencial.

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", como a oferecida pela Corbado. Ambas visam resolver o paradoxo das passkeys e aumentar a adoção, mas fazem-no de maneiras diferentes.

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 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 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, 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.

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.

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 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 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.