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

O ecossistema de passkeys está em evolução. Para facilitar a mudança, o padrão WebAuthn subjacente evolui rapidamente. Novas funcionalidades geralmente começam com uma explicação técnica no GitHub e depois evoluem para um pull request no padrão quando são suficientemente discutidas. Recentemente, este pull request foi adicionado ao rascunho do padrão como a API Signal do WebAuthn. Neste artigo, vamos abordar:

• Por que a API Signal do WebAuthn é necessária: Quais casos de uso a API Signal do WebAuthn suporta?
• Como a API Signal do WebAuthn funciona: Como exatamente a API Signal do WebAuthn funciona? Quais são as recomendações para as partes confiáveis?

Na data de atualização deste post, em janeiro de 2025, a API Signal do WebAuthn 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 API Signal do WebAuthn 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 parte confiável (RP) e os autenticadores que fazem parte dos sistemas operacionais do lado 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 ID da Credencial exclusivo.

• [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 exclusivamente para fins de exibição na interface do usuário.

A ilustração a seguir mostra uma estrutura de banco de dados típica e simples que explica quais informações geralmente seriam armazenadas em cada campo:

É importante entender que, embora user.name (geralmente um endereço de e-mail) e 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 ID da Credencial:

• Uma conta pode ter várias passkeys, mas cada passkey é identificada de forma única e associada à conta usando o user.id
• Cada passkey possui um ID da Credencial exclusivo 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á um mecanismo para atualizar essa mudança 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 user.name antigo 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 então sobrescrever a passkey existente. No entanto, essa abordagem é inconveniente por várias razões:

1. Redundância: Cada user.id pode ter apenas uma passkey por ID da parte confiável, o que significa que a passkey antiga deve ser substituída por uma nova, 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 em que veem e precisam selecionar uma passkey associada ao seu endereço de e-mail antigo. Essa situação prejudica a experiência fluida que as passkeys visam proporcionar. A API Signal do WebAuthn visa resolver esse problema, permitindo que as partes confiáveis relatem atualizações nos metadados das passkeys sem exigir a criação de novas. Antes de explicarmos como implementar a API Signal, 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 lado do cliente para evitar que apareçam em futuras interfaces de seleção de credenciais (UI Condicional / preenchimento automático de passkey).

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

1. Passkey excluída através das 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:

Do ponto de vista do usuário, é difícil entender que uma exclusão nas configurações de 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: As partes confiáveis 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 tentativas de autenticação falhas e uma má experiência do usuário.

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

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

• Preservação da Privacidade: A API Signal do WebAuthn é projetada para preservar a privacidade do usuário, pois é um dos fundamentos do WebAuthn. Isso significa que não há feedback fornecido à RP sobre se a alteração solicitada foi processada. A API opera silenciosamente para evitar qualquer vazamento potencial de informações sobre o estado das credenciais.

• Disponibilidade do Autenticador: A eficácia da API Signal do WebAuthn depende da disponibilidade do autenticador. Isso inclui tanto a disponibilidade física (por exemplo, a presença de uma chave de segurança) 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 parte confiável 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.

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

Essas considerações são essenciais para entender os aspectos mais importantes do funcionamento correto da API Signal do WebAuthn.

A API Signal do WebAuthn fornece um mecanismo simplificado para que as partes confiáveis (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 precisar criar novas passkeys desnecessariamente. Veja como a API permite que isso aconteça:

Atualizando Metadados com signalCurrentUserDetails(options)

O método signalCurrentUserDetails(options) na API Signal é 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 (consulte 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: "New user name",
    displayName: "New display name",
});

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

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

4. Consistência Entre Dispositivos: Ao executar regularmente os métodos signalCurrentUserDetails(options), as RPs podem garantir que os metadados das passkeys permaneçam consistentes em diferentes dispositivos e plataformas onde o usuário pode 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 API Signal do WebAuthn faz parte do Chrome 130 e pode ser testada com o Google Password Manager no desktop se a flag de recursos experimentais da web estiver ativada.

A API Signal do WebAuthn fornece mecanismos para que as partes confiáveis (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 de credenciais, mantendo assim uma experiência de usuário simplificada e segura. Existem dois métodos para excluir as passkeys localmente: signalUnknownCredential(options) e signalAllAcceptedCredentials)(options). O primeiro pode ser usado em situações em que o usuário não está autenticado, enquanto o segundo pode ser usado quando o usuário está autenticado. Portanto, o segundo 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 parte confiável) e o credentialId (o identificador único da credencial a ser excluída).

PublicKeyCredential.signalUnknownCredential({
    rpId: "example.com",
    credentialId: "aabbcc", // credential id the user just tried, base64url
});

2. Chamando o Método: As RPs chamam este método sempre que detectam que uma credencial deve ser excluída. Isso pode ocorrer 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. Lidando com 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 é empregado para ocultar a credencial em futuras cerimônias de autenticação.

1. Estrutura do Método: O método signalAllAcceptedCredentials(options) inclui o rpId (ID da parte confiável), userId e uma lista de IDs de Credencial 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 vez de signalUnknownCredential(options) para excluir credenciais.

3. Lidando com o Método: Quando o método signalAllAcceptedCredentials(options) é chamado, o autenticador do lado do cliente corresponde ao rpId e userId. O autenticador procura 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 uma credencial foi apenas ocultada (dependendo do autenticador) e agora faz parte de allAcceptedCredentialIds, então essa credencial estará presente novamente em futuras cerimônias de autenticação.

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, as partes confiáveis podem considerar executar signalAllAcceptedCredentials(options) periodicamente, como durante cada login, para garantir que todas as credenciais estejam atualizadas.
   • As partes confiáveis devem ter cuidado ao especificar a lista de IDs de credencial (allAcceptedCredentialIds). Credenciais que não estão 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 acidentalmente deixado de fora, ele deve ser readicionado a signalAllAcceptedCredentials(options) o mais rápido possível para torná-lo visível novamente, supondo 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 foi acidentalmente omitido pela parte confiável, permitindo que seja restaurado sem perda permanente.

Na captura de tela acima, você pode ver como o Google Chrome sinaliza exclusões. A API Signal do WebAuthn faz parte do Chrome 132 e pode ser testada com o Google Password Manager no desktop.

Para implementar eficazmente a API Signal do WebAuthn e garantir a sincronização transparente dos metadados de passkeys entre os autenticadores do lado do cliente, considere as seguintes recomendações:

• Fique atento às atualizações e à implementação real da API Signal do WebAuthn: Mantenha-se informado sobre os últimos desenvolvimentos e atualizações relacionados à API Signal. A API Signal do WebAuthn está habilitada com o Google Chrome 132, seguido por outros navegadores (por exemplo, o Safari também anunciou suporte). Verifique regularmente o progresso e as atualizações da API Signal do WebAuthn para garantir que sua implementação esteja alinhada com os padrões e práticas mais recentes. Atualizaremos este post no futuro; ele se baseia atualmente nas informações disponíveis em 14 de janeiro de 2025.
• Comece com a abordagem signalAllAcceptedCredentials(options) após cada login bem-sucedido: Essa abordagem garante que todos os metadados e IDs de credencial sejam atualizados em um único método, simplificando o processo e mantendo a consistência entre dispositivos e plataformas, ao mesmo tempo que desativa credenciais excluídas ou obsoletas.
• Mensagens em tempo real com signalUnknownCredential(options) para implantações em grande escala: Considere usar mensagens em tempo real com o método signalUnknownCredential(options) em implantações em grande 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 prontamente removidas da interface de seleção.

Seguindo estas recomendações, você pode implementar a API Signal do WebAuthn 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 fluida e segura para as passkeys.

O padrão WebAuthn está em contínua evolução, tornando-se mais rico em funcionalidades a cada mês. A introdução da API Signal do WebAuthn é 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 as partes confiáveis (RPs) e os autenticadores, e garantir que passkeys inválidas ou desatualizadas sejam removidas, melhorando assim a experiência do usuário.

• Por que a API Signal é necessária? A API Signal é 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 API Signal funciona? A API Signal funciona permitindo que as RPs chamem métodos sobre o estado atual das credenciais, incluindo atualizações de metadados e sinalização da 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 últimas melhorias e garantir que as implementações permaneçam alinhadas com as melhores práticas e padrões mais recentes. A comunidade WebAuthn continua a impulsionar a inovação, tornando a autenticação mais segura e amigável ao usuário.