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 para computador oferece suporte à API Signal a partir da versão 132. O Gerenciador de senhas do Google pode atualizar as chaves de acesso refletindo o indicador. Para provedores de chaves de acesso baseados em extensões do Chrome, cabe a eles refletir ou não o indicador.

O suporte para o Chrome no Android será lançado mais tarde.

O Safari é compatível, mas ainda não foi implementado. O Firefox ainda não compartilhou as opiniões.

Contexto

Quando uma chave de acesso (uma credencial detectável) é criada, metadados como nome de usuário e 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 confiável (RP, na sigla em inglês). Salvar o nome de usuário e o nome de exibição ajuda o usuário a identificar qual das chaves de acesso oferecidas usar para fazer login quando solicitado. Isso é útil principalmente quando eles 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 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, deixando a chave de acesso no provedor de chaves de acesso intacta. Na próxima vez que o usuário tentar fazer login com uma chave de acesso, ela ainda será apresentada ao usuário pelo provedor de chaves de acesso. No entanto, a tentativa de fazer login vai falhar porque o servidor não poderá verificar com 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 vai 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 estejam sincronizados.

API Signal

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

• PublicKeyCredential.signalUnknownCredential: Sinaliza que uma credencial não existe.
• PublicKeyCredential.signalAllAcceptedCredentials: sinaliza uma lista de credenciais salvas
• PublicKeyCredential.signalCurrentUserDetails: Sinaliza o nome de usuário e/ou nome de exibição atualizados

Indicar 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. Cabe ao provedor de chaves de acesso lidar com esse sinal, mas espera-se que a chave de acesso associada seja removida para que o usuário não faça login com uma chave de acesso, já que a credencial associada não existe.

Essa API pode ser invocada quando um login com chaves de acesso falha devido à ausência de uma credencial. Assim, o RP pode impedir que o usuário tente 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 a transmissão de toda a lista de IDs de credenciais. Portanto, ele deve ser usado sempre que o usuário não estiver autenticado para evitar revelar o número de chaves de acesso de um determinado usuário.

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",
      ...
    ]
  });
}

Ao chamar PublicKeyCredential.signalAllAcceptedCredentials() com um ID de RP, um ID de usuário e uma lista de IDs de credenciais armazenadas, o RP pode informar ao provedor de chaves de acesso as credenciais restantes no armazenamento. Cabe ao provedor de chaves de acesso lidar com esse indicador, mas as chaves que não correspondem a essa lista devem ser removidas para que o usuário não veja chaves de acesso no login para as quais a credencial associada não existe.

Essa API precisa ser invocada quando um usuário exclui 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 as informações atualizadas do usuário. Cabe ao provedor da chave de acesso lidar com esse sinal, mas espera-se que as chaves de acesso do usuário sejam atualizadas com as novas informações.

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

Resumo

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

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