API Signal do WebAuthn: Atualize e Exclua Passkeys no Lado do Cliente

Looking for a dev-focused passkey reference? Download our Passkeys Cheat Sheet. Trusted by dev teams at Ally, Stanford CS & more.

Get Cheat Sheet

Última atualização: 4 de novembro de 2025

Uma visão geral rápida do suporte à WebAuthn Signal API nas plataformas:

⚠️ Problema Conhecido: O Safari 26+ possui um bug onde a promise não resolve corretamente (WebKit Bug #298951). Correção aguardando merge.

O ecossistema de passkeys está evoluindo. Para facilitar mudanças, o padrão WebAuthn subjacente avança rapidamente. Novos recursos geralmente começam com uma explicação técnica no GitHub e depois evoluem para um pull request no padrão quando já foram discutidos o suficiente. Recentemente, este pull request foi adicionado ao rascunho do padrão como a WebAuthn Signal API. Neste artigo, vamos cobrir:

• Por que a WebAuthn Signal API é necessária: Quais casos de uso a WebAuthn Signal API suporta?
• Como a WebAuthn Signal API funciona: Como exatamente a API funciona? Quais são as recomendações para relying parties (RPs)?

No momento da escrita deste artigo, a WebAuthn Signal API está habilitada por padrão desde o Chrome 132 e era anteriormente conhecida como Reporting API antes de ser renomeada para evitar conflitos com outra API de mesmo nome.

A WebAuthn Signal API aborda casos de uso específicos relacionados ao gerenciamento de passkeys no lado do cliente. Especificamente, ela ajuda a manter as informações sincronizadas entre a relying party (RP) e os autenticadores que fazem parte dos sistemas operacionais do cliente. Existem os seguintes casos de uso importantes:

Subscribe to our Passkeys Substack for the latest news.

Subscribe

Quando uma passkey é criada, ela inclui várias informações: user.id, user.name e user.displayName. A passkey em si é identificada através do Credential ID único.

• user.id: é um identificador único que representa a conta à qual a passkey está vinculada. Este user.id é crucial porque é usado para a correspondência real da passkey com a conta do usuário.
• user.name e user.displayName: são metadados usados apenas para fins de exibição na interface do usuário.

A ilustração a seguir mostra uma estrutura de banco de dados simples e típica que explica qual informação geralmente seria armazenada em qual campo:

É importante entender que, embora o user.name (frequentemente um endereço de e-mail) e o user.displayName (um nome mais amigável e legível) ajudem o usuário a identificar sua conta na interface de seleção, a associação real entre uma passkey e uma conta é mantida através do user.id e do Credential ID:

• Uma conta pode ter várias passkeys, mas cada passkey é identificada de forma única e correspondida à conta usando o user.id.
• Cada passkey em si tem um Credential ID único que é gerado pelo autenticador.

Um problema surge quando o user.name, que pode ser um endereço de e-mail, muda. Atualmente, não há mecanismo para atualizar essa alteração diretamente no autenticador do lado do cliente. O user.name pode mudar por vários motivos, como quando um usuário atualiza seu endereço de e-mail. Apesar dessa mudança nos metadados da conta no lado do servidor, o antigo user.name continuará a aparecer na interface de seleção de credenciais, o que pode causar confusão para os usuários.

A solução alternativa para esse problema é criar uma nova passkey com o user.name atualizado e o mesmo user.id e, em seguida, substituir a passkey existente. No entanto, essa abordagem é inconveniente por vários motivos:

1. Redundância: Um autenticador só pode armazenar uma passkey por user.id para um ID de relying party específico. Isso significa que a passkey antiga deve ser substituída por uma nova para atualizar os metadados, o que é um passo extra.
2. Experiência do Usuário: Os usuários não entenderão por que precisam criar uma nova passkey. É por isso que essa solução alternativa não é amplamente utilizada.
3. Complexidade: Gerenciar a criação de passkeys e a substituição apenas para atualizar metadados é uma complexidade desnecessária.

Endereços de e-mail, números de telefone e outros identificadores podem mudar regularmente. Sem um método direto para atualizar user.name e user.displayName diretamente no autenticador, os usuários podem encontrar um problema persistente onde veem e precisam selecionar uma passkey associada ao seu e-mail antigo. Essa situação prejudica a experiência fluida que as passkeys visam proporcionar. A WebAuthn Signal API visa resolver esse problema permitindo que as relying parties relatem atualizações nos metadados das passkeys sem exigir a criação de novas. Antes de explicarmos como implementar a Signal API, vamos explorar o segundo caso de uso importante que ela aborda.

Become part of our Passkeys Community for updates & support.

Join

Outro caso de uso crucial é a exclusão de passkeys no autenticador do lado do cliente. Com o tempo, os usuários podem revogar credenciais através da lista de gerenciamento de passkeys ou excluir suas contas, e torna-se necessário garantir que essas credenciais sejam removidas do autenticador do cliente para evitar que apareçam em futuras interfaces de seleção de credenciais (Conditional UI / autopreenchimento de passkeys).

A necessidade dessa funcionalidade surge em vários cenários:

1. Passkey excluída via configurações da conta: Quando uma credencial não é mais válida, como após um usuário tê-la excluído explicitamente através das configurações da conta:

Da perspectiva do usuário, é difícil entender que uma exclusão na configuração da sua conta, em um diálogo como o acima, não leva à remoção da passkey neste cliente.

2. Exclusão de Conta: Quando um usuário exclui sua conta, todas as passkeys associadas também devem ser removidas.

3. Políticas de Segurança: Relying parties podem ter políticas de segurança que exigem a revogação de credenciais após períodos de inatividade ou devido a problemas de segurança detectados.

Sem um método direto para excluir passkeys no lado do cliente, essas credenciais desatualizadas ou inválidas continuam a poluir a interface de seleção, levando à confusão. Os usuários podem ver e tentar usar passkeys que não são mais válidas, resultando em falhas nas tentativas de autenticação e uma experiência ruim.

Veja este vídeo sobre como excluir passkeys no lado do servidor no Corbado Connect Management Console:

Implementar a WebAuthn Signal API envolve várias etapas e considerações para garantir que a funcionalidade seja integrada de forma correta e segura. A Signal API permite que relying parties (RPs) atualizem ou excluam credenciais de passkey no autenticador do lado do cliente. Esta seção descreve as principais considerações e etapas para implementação.

Ao implementar a WebAuthn Signal API, é crucial ter em mente as seguintes considerações:

• Preservação de Privacidade: A WebAuthn Signal API foi projetada para preservar a privacidade do usuário, pois essa é uma das bases do WebAuthn. Isso significa que nenhum feedback é fornecido à RP sobre se a alteração solicitada foi processada. A API opera silenciosamente para evitar qualquer possível vazamento de informações sobre o estado das credenciais.

• Disponibilidade do Autenticador: A eficácia da WebAuthn Signal API depende da disponibilidade do autenticador. Isso inclui tanto a disponibilidade física quanto o suporte de software (por exemplo, compatibilidade do navegador e do sistema operacional). O navegador só pode realizar ações se o autenticador estiver acessível e suportar as operações necessárias sem precisar de autenticação biométrica.

• Restrições de Domínio: A API garante que apenas a relying party associada a um domínio específico possa solicitar alterações nas credenciais relacionadas a esse domínio. Esta é uma medida de segurança para evitar modificações não autorizadas por terceiros.

• Credential ID como Chave: Ao referenciar passkeys, o Credential ID é a chave primária usada pela WebAuthn Signal API. Este ID identifica exclusivamente a passkey no autenticador do lado do cliente. A API permite que as RPs alterem metadados associados a passkeys ou sinalizem que certas passkeys não devem mais ser acessadas, mas apenas através do Credential ID. Caso um autenticador não conheça um Credential ID específico, ele o ignorará silenciosamente.

Essas considerações são essenciais para entender como os aspectos mais importantes da WebAuthn Signal API funcionam corretamente.

A WebAuthn Signal API fornece um mecanismo simplificado para que as relying parties (RPs) atualizem os metadados associados às passkeys nos autenticadores do lado do cliente. Isso é especialmente importante para garantir que os usuários vejam informações precisas e atualizadas na interface de seleção de credenciais sem ter que criar novas passkeys desnecessariamente. Veja como a API permite que isso aconteça:

Atualizando Metadados com signalCurrentUserDetails(options)

O método signalCurrentUserDetails(options) na Signal API é projetado especificamente para atualizar metadados de passkeys. Este método permite que as RPs forneçam os valores atuais para user.name e user.displayName.

Veja como o processo funciona (veja também o padrão WebAuthn Nível 3).

1. Estrutura do Método: O método signalCurrentUserDetails(options) inclui o rp.id, user.id e os valores atualizados para user.name e user.displayName.

PublicKeyCredential.signalCurrentUserDetails({
    rpId: "example.com",
    userId: "aabbcc", // user handle, base64url.
    name: "Novo nome de usuário",
    displayName: "Novo nome de exibição",
});

2. Atualizando os Metadados Locais: Procura por credenciais disponíveis localmente (no autenticador) que correspondam ao rpId e userId. Para todas as credenciais correspondentes, o autenticador atualizará o name e displayName da credencial.

3. Preservação de Privacidade: O processo é projetado para preservar a privacidade. A Signal API não fornece feedback à RP sobre se as atualizações foram processadas com sucesso, prevenindo qualquer vazamento de informações sobre o estado das credenciais.

4. Consistência entre Dispositivos: Ao executar regularmente o método signalCurrentUserDetails(options), as RPs podem garantir que os metadados das passkeys permaneçam consistentes em diferentes dispositivos e plataformas onde o usuário possa se autenticar. Essa abordagem reduz as chances de informações desatualizadas ou incorretas serem exibidas na interface de seleção de credenciais.

Na captura de tela acima, você pode ver como o Google Chrome sinaliza tal atualização para o usuário. A WebAuthn Signal API faz parte do Chrome e pode ser testada com o Gerenciador de Senhas do Google no desktop.

A WebAuthn Signal API fornece mecanismos para que as relying parties (RPs) sinalizem a exclusão de passkeys dos autenticadores do lado do cliente. Isso é essencial para garantir que credenciais desatualizadas ou inválidas não apareçam na interface de seleção, mantendo assim uma experiência de usuário simplificada e segura. Existem dois métodos para excluir passkeys localmente: signalUnknownCredential(options) e signalAllAcceptedCredentials(options). O primeiro pode ser usado em situações onde o usuário não está autenticado, enquanto o último pode ser usado quando o usuário está autenticado. Portanto, este último deve ser preferido por razões de privacidade.

Veja como os dois métodos funcionam:

1. Estrutura do Método: O método signalUnknownCredential(options) inclui o rpId (ID da relying party) e o credentialId (o identificador único da credencial a ser excluída).

PublicKeyCredential.signalUnknownCredential({
    rpId: "example.com",
    credentialId: "aabbcc", // id da credencial que o usuário acabou de tentar, base64url
});

2. Chamando o Método: As RPs chamam este método sempre que detectam que uma credencial deve ser excluída. Isso pode ser imediatamente após uma tentativa de autenticação com uma credencial inválida, durante a exclusão da conta ou quando um usuário revoga uma credencial através das configurações da conta.

3. Processando o Método: Quando o método signalUnknownCredential(options) é chamado, o autenticador do lado do cliente tenta encontrar credenciais que correspondam ao rpId e credentialID especificados para omissão. Dependendo das capacidades do autenticador, a credencial é removida ou um procedimento específico do autenticador para ocultar a credencial em futuras cerimônias de autenticação é empregado.

1. Estrutura do Método: O método signalAllAcceptedCredentials(options) inclui o rpId (ID da relying party), userId e uma lista de Credential Ids válidos allAcceptedCredentialIds (lista de identificadores únicos de credenciais que devem ser mantidas).

PublicKeyCredential.signalAllAcceptedCredentials({
    rpId: "example.com",
    userId: "aabbcc", // user handle, base64url.
    allAcceptedCredentialIds: ["bb"],
});

2. Chamando o Método: As RPs chamam este método sempre que detectam que uma credencial deve ser excluída e sinalizam uma lista de credenciais válidas. Este método deve ser preferido em relação ao signalUnknownCredential(options) para excluir credenciais.

3. Processando o Método: Quando o método signalAllAcceptedCredentials(options) é chamado, o autenticador do cliente verifica a correspondência de rpId e userId. O autenticador então busca todas as credenciais locais que correspondem a rpId e userId. O resultado é comparado com allAcceptedCredentialIds. Se houver credenciais locais que não estão em allAcceptedCredentialIds, essas credenciais são removidas localmente (ou ocultadas, dependendo do autenticador).

4. Reexibir Credenciais: Se credenciais foram apenas ocultadas (dependendo do autenticador) e agora fazem parte de allAcceptedCredentialIds, então essas credenciais estarão presentes em futuras cerimônias de autenticação novamente.

5. Dicas Úteis:

   • Ao usar signalAllAcceptedCredentials(options), é importante notar que os autenticadores podem nem sempre estar conectados no momento em que este método é executado. Como resultado, relying parties podem considerar executar signalAllAcceptedCredentials(options) periodicamente, como durante cada login, para garantir que todas as credenciais estejam atualizadas.
   • As relying parties devem ser cautelosas ao especificar a lista de IDs de credenciais (allAcceptedCredentialIds). Credenciais que não estiverem incluídas nesta lista podem ser ocultadas ou removidas pelo autenticador, potencialmente de forma irreversível. Para evitar que credenciais válidas sejam omitidas por engano, é crucial garantir que a lista esteja completa. Se um ID de credencial válido for deixado de fora acidentalmente, ele deve ser readicionado ao signalAllAcceptedCredentials(options) o mais rápido possível para torná-lo visível novamente, assumindo que o autenticador suporte isso.
   • Sempre que possível, os autenticadores devem preferir ocultar temporariamente as credenciais em vez de removê-las permanentemente. Essa abordagem pode ajudar a facilitar a recuperação se um ID de credencial válido for omitido acidentalmente pela relying party, permitindo que ele seja restaurado sem perda permanente.

Na captura de tela acima, você pode ver como o Google Chrome sinaliza exclusões. A WebAuthn Signal API pode ser testada com o Gerenciador de Senhas do Google no desktop.

Para implementar efetivamente a WebAuthn Signal API e garantir a sincronização perfeita dos metadados das passkeys nos autenticadores do lado do cliente, considere as seguintes recomendações:

• Fique atento às atualizações da WebAuthn Signal API e implementação real: Mantenha-se informado sobre os desenvolvimentos e atualizações mais recentes relacionados à Signal API. A WebAuthn Signal API está habilitada no Google Chrome 132, seguido por outros navegadores (por exemplo, Safari também anunciou suporte). Verifique regularmente o progresso e as atualizações na WebAuthn Signal API para garantir que sua implementação esteja alinhada com os padrões e práticas mais recentes. Atualizaremos esta postagem conforme o cenário evoluir.
• Comece com a abordagem signalAllAcceptedCredentials(options) após cada login bem-sucedido: Essa abordagem garante que todos os metadados e IDs de credenciais sejam atualizados em um único método, simplificando o processo e mantendo a consistência entre dispositivos e plataformas e, ao mesmo tempo, desativa credenciais excluídas ou obsoletas.
• Mensagens em tempo real com signalUnknownCredential(options) para implantações em larga escala: Considere usar mensagens em tempo real com o método signalUnknownCredential(options) em implantações de larga escala ou quando houver necessidade de atualizações imediatas. Este método pode aumentar a eficiência e a precisão do gerenciamento de credenciais, garantindo que credenciais inválidas ou desatualizadas sejam removidas prontamente da interface de seleção.

Seguindo essas recomendações, conseguimos implementar a WebAuthn Signal API de forma eficaz assim que ela for suportada, garantindo que os metadados das passkeys permaneçam atualizados e consistentes em todos os autenticadores do lado do cliente, proporcionando assim uma experiência de usuário suave e segura para passkeys.

O padrão WebAuthn está em contínua evolução, tornando-se mais rico em recursos a cada mês. A introdução da WebAuthn Signal API é um passo significativo no gerenciamento de metadados e exclusões de passkeys em autenticadores do lado do cliente. Esta API aborda os casos de uso cruciais de manter as informações sincronizadas entre relying parties (RPs) e autenticadores, garantindo que passkeys inválidas ou desatualizadas sejam removidas, melhorando assim a experiência do usuário.

• Por que a Signal API é necessária? A Signal API é essencial para atualizar metadados de passkeys e excluir passkeys em autenticadores do lado do cliente. Ela resolve problemas relacionados a informações desatualizadas de user.name e user.displayName, que podem causar confusão quando as credenciais são apresentadas na interface de seleção. Além disso, ajuda a manter uma interface de seleção de credenciais limpa e segura, removendo passkeys revogadas ou excluídas.
• Como a Signal API funciona? A Signal API funciona permitindo que as RPs chamem métodos sobre o estado atual das credenciais, incluindo atualizações de metadados e sinalização de exclusão de passkeys. Esses relatórios são processados pelo autenticador do lado do cliente, garantindo que as informações apresentadas aos usuários sejam precisas e atualizadas. A API é projetada para preservar a privacidade e opera sem fornecer feedback à RP sobre o sucesso das atualizações.

À medida que o padrão WebAuthn evolui, ele se beneficia dos diversos interesses de seus participantes, que impulsionam diferentes partes do padrão. Ficar de olho nesses desenvolvimentos é crucial para se manter atualizado com as melhorias mais recentes e garantir que as implementações permaneçam alinhadas com as melhores práticas e padrões mais atuais. A comunidade WebAuthn continua a impulsionar a inovação, tornando a autenticação mais segura e amigável para o usuário.