Mantenha as chaves de acesso consistentes com as credenciais no seu servidor com a API Signal

Eiji Kitamura

Publicado em 12 de novembro de 2024. Última atualização: 29 de novembro de 2024

A API WebAuthn Signal permite que as partes confiáveis sinalizem as credenciais já existentes para provedores de chaves de acesso conectados. Assim, um provedor de chave de acesso compatível poderá atualizar ou remover chaves de acesso incorretas ou revogadas do armazenamento para que elas não sejam mais oferecidas aos usuários.

Compatibilidade

O Chrome oferece suporte à API Signal em todas as plataformas de computador e no Android.

O Safari é compatível, mas ainda não foi implementado. O Firefox ainda não compartilhou a opinião dele.

O Gerenciador de senhas do Google pode atualizar as chaves de acesso para refletir o indicador. Os provedores de chaves de acesso baseados em extensões do Chrome para computador decidem se vão refletir o indicador.

Contexto

Quando uma chave de acesso (uma credencial detectável) é criada, metadados como um nome de usuário e um nome de exibição são salvos no provedor de chaves de acesso (como um gerenciador de senhas) junto com a chave privada, enquanto a credencial de chave pública é salva no servidor da parte confiante (RP, na sigla em inglês). Salvar o nome de usuário e o nome de exibição ajuda os usuários a identificar quais chaves de acesso oferecidas usar para fazer login quando solicitado. Isso é especialmente útil quando os usuários têm mais de duas chaves de acesso de provedores diferentes.

No entanto, há alguns casos em que inconsistências entre a lista de chaves de acesso do provedor e a lista de credenciais do servidor podem causar confusão.

O primeiro caso é quando um usuário exclui uma credencial no servidor. Isso deixa a chave de acesso no provedor intacta. Na próxima vez que o usuário tentar fazer login com uma chave de acesso, o provedor ainda vai apresentar essa chave. No entanto, a tentativa de fazer login vai falhar porque o servidor não consegue verificar a chave pública excluída.

O segundo caso é quando um usuário atualiza o nome de usuário ou o nome de exibição no servidor. Na próxima vez que o usuário tentar fazer login, a chave de acesso no provedor de chaves de acesso continuará mostrando o nome de usuário e o nome de exibição antigos, mesmo que eles tenham sido atualizados no servidor. O ideal é que eles sejam sincronizados.

API Signal

A API Signal é uma API WebAuthn que resolve essas inconsistências permitindo que as partes confiáveis sinalizem mudanças para o provedor de chaves de acesso. Há três métodos:

Sinalizar que uma credencial não existe

const credential = await navigator.credentials.get({ ... });
const payload = credential.toJSON();

const result = await fetch('/login', { ... });

// Detect authentication failure due to lack of the credential
if (result.status === 404) {
  // Feature detection
  if (PublicKeyCredential.signalUnknownCredential) {
    await PublicKeyCredential.signalUnknownCredential({
      rpId: "example.com",
      credentialId: "vI0qOggiE3OT01ZRWBYz5l4MEgU0c7PmAA" // base64url encoded credential ID
    });
  } else {
    // Encourage the user to delete the passkey from the password manager nevertheless.
    ...
  }
}

Ao chamar PublicKeyCredential.signalUnknownCredential() com um ID de RP e um ID de credencial, o RP pode informar ao provedor de chaves de acesso que a credencial especificada foi removida ou não existe. O provedor de chaves de acesso determina como processar esse indicador, mas a chave de acesso associada precisa ser removida para que os usuários não tentem fazer login com uma chave de acesso sem uma credencial associada.

Browser Support

  • Chrome: 132.
  • Edge: 132.
  • Firefox: not supported.
  • Safari: 26.

Source

Essa API pode ser invocada quando um login com chaves de acesso falha porque uma credencial está ausente. Assim, o RP pode impedir que os usuários tentem fazer login com uma chave de acesso que não tenha uma credencial associada. Ao contrário de signalAllAcceptedCredentials, esse método não exige que você transmita toda a lista de IDs de credenciais. Portanto, use-o sempre que o usuário não estiver autenticado para evitar revelar o número de chaves de acesso de um determinado usuário.

Uma caixa de diálogo exibida quando uma chave de acesso é excluída do Gerenciador de senhas do Google no Chrome.
Uma caixa de diálogo exibida quando uma chave de acesso é excluída do Gerenciador de senhas do Google no Chrome.

Sinalizar uma lista de credenciais salvas

// After a user deletes a passkey or a user is signed in.

// Feature detection
if (PublicKeyCredential.signalAllAcceptedCredentials) {
  await PublicKeyCredential.signalAllAcceptedCredentials({
    rpId: "example.com",
    userId: "M2YPl-KGnA8", // base64url encoded user ID
    allAcceptedCredentialIds: [ // A list of base64url encoded credential IDs
      "vI0qOggiE3OT01ZRWBYz5l4MEgU0c7PmAA",
      ...
    ]
  });
}

Use PublicKeyCredential.signalAllAcceptedCredentials() depois que um usuário fizer login ou gerenciar as configurações da conta. Você fornece uma lista de todos os IDs de credenciais válidos para esse usuário. O provedor de chaves de acesso compara essa lista com o armazenamento local para essa parte confiável. O provedor de chaves de acesso marca como "oculta" qualquer chave de acesso encontrada no armazenamento que não esteja incluída na lista allAcceptedCredentialIds. O sistema não oferece mais essas chaves de acesso ocultas para fazer login ou preencher automaticamente, mas elas não são excluídas permanentemente de imediato, o que permite a restauração, se necessário. Por outro lado, o provedor de chaves de acesso restaura as chaves presentes em allAcceptedCredentialIds que estão marcadas como "ocultas". Isso permite que seu site restaure chaves de acesso que foram ocultadas por engano.

Browser Support

  • Chrome: 132.
  • Edge: 132.
  • Firefox: not supported.
  • Safari: 26.

Source

Invoque essa API quando um usuário excluir uma chave de acesso no RP e em todos os logins, para que o provedor de chaves de acesso possa manter uma lista sincronizada de chaves de acesso.

O indicador atualizou o nome de usuário e o nome de exibição

// After a user updated their username and/or display name
// or a user is signed in.

// Feature detection
if (PublicKeyCredential.signalCurrentUserDetails) {
  await PublicKeyCredential.signalCurrentUserDetails({
    rpId: "example.com",
    userId: "M2YPl-KGnA8", // base64url encoded user ID
    name: "a.new.email.address@example.com", // username
    displayName: "J. Doe"
  });
} else {
}

Ao chamar PublicKeyCredential.signalCurrentUserDetails() com um ID de RP, um ID de usuário, um nome de usuário e um nome de exibição, o RP pode informar ao provedor de chaves de acesso sobre as informações atualizadas do usuário. O provedor de chaves de acesso determina como processar esse indicador, mas ele precisa atualizar as chaves de acesso do usuário com as novas informações.

Browser Support

  • Chrome: 132.
  • Edge: 132.
  • Firefox: not supported.
  • Safari: 26.

Source

Essa API pode ser invocada quando o nome de usuário ou o nome de exibição do usuário é atualizado e em todos os logins, para que o provedor de chaves de acesso possa manter essas informações sincronizadas com o servidor.

Uma caixa de diálogo exibida quando os metadados de uma chave de acesso são atualizados no Gerenciador de senhas do Google no Chrome.
Uma caixa de diálogo exibida quando os metadados de uma chave de acesso são atualizados no Gerenciador de senhas do Google no Chrome.

Resumo

A API Signal ajuda você a criar uma experiência melhor de chave de acesso, eliminando falhas inesperadas de login. Com a API Signal, as partes confiáveis podem sinalizar a lista de credenciais atuais e os metadados delas para manter as chaves de acesso sincronizadas no provedor.

Para saber mais sobre chaves de acesso, consulte Login sem senha com chaves de acesso.