Teste de origem: mediação imediata do WebAuthn para login sem atrito

José Luis Zapata

Publicado em: 19 de agosto de 2025

A mediação imediata do WebAuthn é um novo recurso da Web projetado para simplificar os fluxos de login do usuário. Esse teste de origem oferece uma visão geral do recurso, dos benefícios e dos detalhes de implementação, convidando você a participar e ajudar a moldar o futuro da autenticação na Web.

Contexto

A autenticação na Web geralmente causa atrito, complicando o login do usuário. Os fluxos atuais do WebAuthn, embora sejam poderosos, têm dificuldades com os botões "Fazer login", principalmente quando as credenciais não estão disponíveis imediatamente, o que leva a substituições de formulário padrão.

Esse novo recurso introduz um fluxo de login de baixo atrito, semelhante às APIs preferImmediatelyAvailableCredentials em dispositivos móveis. Ele simplifica o processo de login, muitas vezes antes dos formulários de login padrão, reduzindo o atrito e melhorando a experiência do usuário.

Como funciona

A mediação imediata do WebAuthn permite uma experiência de login mais direta e eficiente. Ele permite que o navegador ofereça instantaneamente as credenciais disponíveis ou sinale imediatamente a ausência delas sem solicitar autenticação entre dispositivos ou com chave de segurança, o que simplifica a implementação para desenvolvedores.

O tipo de mediação immediate

Estamos lançando um tipo de mediação immediate para solicitações navigator.credentials.get(). Quando essa opção é definida, a promessa é rejeitada com NotAllowedError se nenhuma credencial disponível localmente for encontrada. Se as credenciais estiverem presentes, o navegador vai processar a autenticação normalmente.

Essa flexibilidade permite que os sites adaptem o fluxo de login, oferecendo métodos alternativos quando as credenciais imediatas não estão disponíveis.

É importante lembrar que os navegadores ainda podem retornar NotAllowedError para manter a privacidade e a segurança do usuário, evitando problemas como impressão digital ou rastreamento.

Detecção de recursos

É possível detectar se a mediação imediata está disponível usando PublicKeyCredential.getClientCapabilities(). Os desenvolvedores podem verificar a capacidade immediateGet no objeto capabilities retornado.

async function checkImmediateMediationAvailability() {
  try {
    const capabilities = await PublicKeyCredential.getClientCapabilities();
    if (capabilities.immediateGet && window.PasswordCredential) {
      console.log("Immediate Mediation with passwords supported.");
    } else if (capabilities.immediateGet) {
      console.log("Immediate Mediation without passwords supported.");
    } else { console.log("Immediate Mediation unsupported."); }
  } catch (error) {
    console.error("Error getting client capabilities:", error);
  }
}

Observação:para ajudar com um suporte mais amplo a navegadores, um polyfill para getClientCapabilities() está disponível no repositório WebAuthn Polyfills do GitHub (em inglês).

Implementação de exemplo

Para usar a API, chame navigator.credentials.get() com mediation: 'immediate'. Recomendamos incluir password: true na solicitação, já que a maioria dos usuários provavelmente tem uma senha salva e pode se beneficiar imediatamente dessa experiência.

button.addEventListener('click', async (event) => {
  event.preventDefault();
  event.stopPropagation();
  const cred = await navigator.credentials.get({
    password: true,
    publicKey: {
      challenge, // Your server-generated challenge
      rpId: 'example.com' // Your Relying Party ID
    },
    mediation: 'immediate',
  });
});

Os desenvolvedores precisam processar o NotAllowedError em um bloco catch para oferecer uma experiência de login de fallback normal.

Um fluxo explicativo para mediação imediata

A mediação imediata do WebAuthn oferece suporte a dois casos de uso principais para simplificar o login do usuário: ativar um botão dedicado "Fazer login com chave de acesso" que suprime opções de substituição indesejadas e facilitar um fluxo de login dinâmico que oferece credenciais de forma proativa antes de uma ação crítica do usuário.

Caso de uso 1: login explícito com o botão de login

Esse cenário se concentra em fornecer um botão de login dedicado, garantindo uma experiência do usuário limpa, sem solicitações inesperadas ou acesso a uma página de login.

1. O usuário inicia o processo de login:o usuário clica em um botão "Fazer login". Em seguida, a parte confiável chama navigator.credentials.get() com mediation: "immediate".
2. Solicitações do navegador para seleção de credenciais (se disponível): o navegador verifica se há chaves de acesso ou senhas solicitadas disponíveis localmente. Se encontrar alguma, ela vai apresentar imediatamente uma interface modal para o usuário escolher uma conta. As contas são classificadas por carimbo de data/hora do último uso e, em seguida, em ordem alfabética. Observação: se senhas e chaves de acesso de vários gerenciadores de senhas forem encontradas para a mesma conta, o navegador vai priorizar as chaves de acesso. Quando há várias chaves de acesso para a mesma conta de provedores diferentes, a última usada tem prioridade.
3. Login bem-sucedido:o usuário seleciona a chave de acesso na interface do navegador. Se o navegador exigir verificação, ele vai pedir que o usuário confirme a identidade usando o método configurado anteriormente (como um PIN, entrada biométrica ou padrão). O login é concluído.
4. Caminho alternativo: sem chave de acesso ou dispensa do usuário:se não houver chaves de acesso locais ou senhas solicitadas disponíveis para o site, ou se o usuário dispensar a interface do navegador, o navegador vai gerar um NotAllowedError para a parte confiante, e não vai mostrar nenhuma interface para opções entre dispositivos ou de chave de segurança. A parte confiável pode continuar com a página de login padrão ou oferecer mecanismos de autenticação alternativos.

Caso de uso 2: fluxo de login implícito antes de uma ação do usuário

Esse cenário permite uma experiência de login proativa, oferecendo chaves de acesso e senhas antes que um usuário realize uma ação que exija um estado autenticado, como o pagamento.

1. O usuário inicia uma ação que exige login:o usuário clica em um botão para uma ação que exige que ele faça login (por exemplo, um botão "Finalizar compra" ). Em seguida, a parte confiável chama navigator.credentials.get() com mediation: "immediate".

2. Solicitações do navegador para seleção de credenciais (se disponível): o navegador verifica se há chaves de acesso ou senhas disponíveis localmente. Se encontrar, ele apresentará imediatamente uma interface modal para o usuário escolher uma conta. As contas são classificadas por carimbo de data/hora do último uso, depois em ordem alfabética e são deduplicadas para mostrar uma única entrada por conta. Observação: quando senhas e chaves de acesso de vários gerenciadores de senhas são encontradas para a mesma conta, o navegador prioriza as chaves de acesso. Quando existem várias chaves de acesso para a mesma conta de provedores diferentes, a última chave de acesso usada tem prioridade.

3. Login bem-sucedido:o usuário seleciona uma credencial na interface do navegador. Se o navegador exigir verificação, ele vai pedir que o usuário confirme a identidade usando o método configurado anteriormente (como um PIN, entrada biométrica ou padrão). O login é concluído.

4. Caminho alternativo: sem credenciais ou dispensa do usuário:se não houver credenciais locais disponíveis para o site ou se o usuário dispensar a interface do navegador, o navegador vai gerar um NotAllowedError para a parte confiável e não vai mostrar nenhuma interface. A experiência de login do usuário não vai mudar. Em seguida, a parte confiante pode pedir mais detalhes ao usuário (por exemplo, endereço de e-mail) ou mostrar mecanismos de autenticação alternativos, como um formulário de senha, verificação por SMS ou uma solicitação modal da WebAuthn que oferece suporte a autenticadores entre dispositivos.

Vantagens

A mediação imediata do WebAuthn oferece várias vantagens importantes para desenvolvedores e usuários:

• Login sem atrito:oferece uma experiência de login mais tranquila e com menos atrito para usuários que têm chaves de acesso ou senhas disponíveis imediatamente salvas no navegador ou gerenciador de senhas.
• Login inteligente:a API permite um fluxo de login quando o usuário quer realizar atividades que exigem que ele esteja conectado. Elas se adaptam de forma inteligente ao status das credenciais do usuário. Ele oferece autenticação imediata quando possível, evitando redirecionamentos desnecessários e simplificando o fluxo.
• Gerenciamento de credenciais aprimorado: quando vários gerenciadores de senhas oferecem credenciais para a mesma conta, o navegador seleciona de forma inteligente a opção mais adequada, simplificando o gerenciamento de credenciais para os usuários.
• Redução da confusão do usuário:ao apresentar credenciais conhecidas diretamente, o recurso minimiza a confusão do usuário, que geralmente está associada a várias opções de login ou formulários padrão.
• Fallback sem interrupções:garante um fallback sem interrupções para páginas de login padrão para usuários sem credenciais imediatas, ou seja, a experiência permanece inalterada em relação aos fluxos atuais.

Privacidade e segurança

A mediação imediata do WebAuthn permite que os sites identifiquem a presença de credenciais disponíveis imediatamente antes que um usuário autorize explicitamente uma tentativa de login. Para proteger a privacidade do usuário e evitar possíveis usos indevidos, implementamos várias medidas importantes:

• Requisito de gesto do usuário:a chamada de API exige um gesto do usuário (qualquer ativação temporária do usuário). Isso dificulta a sondagem silenciosa e a coleta de impressões digitais para sites.
• Sessões anônimas e particulares:em sessões anônimas ou particulares, qualquer solicitação de mediação imediata gera NotAllowedError.
• Restrições nas listas de allowCredentials:solicitações que usam listas de allowCredentials geram NotAllowedError. Isso impede que os sites infiram o histórico de interação do usuário ou rastreiem os usuários em várias sessões.
• Cancelamento:definir o parâmetro signal em uma solicitação com mediação imediata é inválido. Isso impede que os sites dispensem programaticamente qualquer interface do navegador.

Faça um teste

Recomendamos que você teste a mediação imediata da WebAuthn.

Status no Chrome

Esse recurso está progredindo no ciclo de desenvolvimento do Chromium:

• Computador:teste de desenvolvedor no Chrome 136, com um teste de origem do Chrome 139 ao 141.
• Android:teste para desenvolvedores no Chrome 140.

Para testes locais

Para testar a mediação imediata da WebAuthn localmente:

1. Baixe o Chrome 139:faça o download e abra a versão mais recente do Chrome no seu computador.
2. Ative a flag de mediação imediata:navegue até chrome://flags/#web-authentication-immediate-get na barra de endereço e ative a flag "Web Authentication Immediate Get".
3. Prepare as credenciais:verifique se você tem chaves de acesso e senhas utilizáveis salvas:
   • Senhas salvas no Gerenciador de senhas do Google.
   • Chaves de acesso salvas no Gerenciador de senhas do Google (requer fazer login e sincronizar o Chrome com uma Conta do Google), no Windows Hello ou no chaveiro do iCloud.

Para testes públicos (teste de origem)

Para testar a mediação imediata do WebAuthn com o teste de origem em um ambiente público:

1. Inscreva-se:acesse a página de testes de origem do Chrome e inscreva-se no teste"Mediação imediata do WebAuthn".
2. Adicione o token aos cabeçalhos HTTP:inclua o token de teste de origem fornecido nos cabeçalhos HTTP do seu site: HTML Origin-Trial: [YOUR_TRIAL_TOKEN]

Observação:você também pode fornecer seus tokens de forma programática com JavaScript.

Cenários de teste

Oferecemos uma implementação de referência e recomendamos que você crie seu próprio protótipo para testar vários cenários.

• Demonstração de referência:teste a implementação de referência em https://deephand.github.io/webauthn-immediate-demo/.
  • Implemente um protótipo:ao implementar um protótipo no seu site, faça a chamada navigator.credentials.get() com mediation: 'immediate' depois que um usuário clicar em algo (por exemplo, um botão "Fazer login" ou qualquer interação que exija que o usuário esteja conectado).
• Fluxo 1: fazer login sem senha ou chave de acesso:se você não tiver chaves de acesso ou senhas disponíveis para o site, clicar em "Fazer login" vai direto para a página de login padrão, sem que a interface do navegador apareça.
• Fluxo 2: fazer login com uma chave de acesso local disponível imediatamente:se você tiver uma chave de acesso salva para o site, clicar em "Fazer login" vai acionar a interface de mediação imediata, oferecendo a chave de acesso para seleção.
• Fluxo 3: fazer login com uma chave de acesso ou senha local:se você tiver chaves de acesso e senhas salvas, ative a opção "Solicitar senha" (definindo password: true no seu código). Ao clicar em "Fazer login", as opções de chave de acesso e senha vão aparecer na interface da mediação imediata.