Publicado em 9 de maio de 2025
As chaves de acesso oferecem uma autenticação forte e resistente a phishing. No entanto, fazer com que os usuários adotem essas tecnologias pode causar atrito. Com os upgrades de chave de acesso, é possível criar chaves de acesso para seus usuários no momento certo, desde que eles já tenham uma senha salva para seu site. A criação condicional, que permite upgrades de chaves de acesso, faz parte da especificação da WebAuthn.
Como funciona
Para ajudar os usuários a adotar chaves de acesso de maneira mais conveniente, use um recurso da API WebAuthn chamado Criação condicional. A criação condicional permite que seu site solicite uma chave de acesso para o usuário sem exigir nenhuma ação dele.
Esse fluxo funciona quando as seguintes condições são atendidas:
- O usuário tem uma senha salva no gerenciador de senhas padrão.
- A senha foi usada recentemente. Chame a criação condicional imediatamente após um login com senha.
Se ambas as condições forem atendidas, você poderá solicitar que o gerenciador de senhas crie uma chave de acesso para o usuário chamando a criação condicional. Depois de criar a chave de acesso, o usuário vai receber uma notificação, dependendo do gerenciador de senhas.
Compatibilidade
A criação condicional é compatível com o Safari no macOS e no iOS, bem como com o Chrome no computador.
Implementar a criação condicional
Os upgrades de chave de acesso são baseados em um recurso da API WebAuthn chamado Criação
condicionada. Essas são solicitações create() regulares da WebAuthn com o parâmetro mediation
definido como "conditional", que funciona de maneira semelhante ao preenchimento automático de chave de acesso para
solicitações get().
Use a criação condicional depois que o usuário fizer login com uma senha. O sucesso do upgrade depende do gerenciador de senhas e de algumas condições sendo atendidas. Essas condições podem variar de acordo com o gerenciador de senhas e podem mudar com o tempo. Por exemplo, no Chrome com o Gerenciador de senhas do Google (GPM), o usuário precisa ter feito login recentemente usando uma senha salva para o site.
Se o navegador criar a chave de acesso, ele vai retornar uma credencial de chave pública. Envie essa credencial para seu back-end para concluir o registro e permitir a autenticação futura.
Detecção de recursos
Para determinar se a criação condicional está disponível no navegador,
invoque PublicKeyCredential.getClientCapabilities(). Verifique se um objeto retornado
contém true para a propriedade conditionalCreate.
if (window.PublicKeyCredential && PublicKeyCredential.getClientCapabilities) {
const capabilities = await PublicKeyCredential.getClientCapabilities();
if (capabilities.conditionalCreate) {
// Conditional create is available
}
}
Se getClientCapabilities estiver indisponível, a criação condicional também
ficará indisponível.
Criar uma chave de acesso condicionalmente
Para fazer upgrade de uma chave de acesso, invoque navigator.credentials.create(), mas com
mediation: "conditional" desta forma.
const cred = await navigator.credentials.create({
publicKey: options,
// Request conditional creation
mediation: 'conditional'
});
Use o upgrade de chave de acesso imediatamente após o usuário fazer login para ter a melhor chance de atender aos critérios do gerenciador de senhas para criação automática.
É possível enviar a credencial de chave pública resultante ao servidor para verificar e registrar a chave de acesso. No servidor, verifique se o usuário fez login.
Advertências
A criação condicional não é difícil de implementar, mas há várias ressalvas ao integrar esse recurso a um sistema existente.
Ignorar a presença e a verificação do usuário no servidor
A resposta de registro retorna "Presença do usuário" e "Usuário verificado" como
false. Portanto, o servidor precisa ignorar essas flags durante a verificação de credenciais.
Abortar a chamada da WebAuthn em andamento antes de fazer upgrade da chave de acesso
Quando o RP espera que o usuário faça login com uma chave de acesso ou uma senha, a melhor escolha é fazer uma busca condicional. Isso pode fazer com que a chamada de recebimento condicional seja cancelada antes de realizar uma criação condicional.
Para fazer isso, use AbortController e chame .abort().
// To abort a WebAuthn call, instantiate an AbortController.
const controller = new AbortController();
const cred = await navigator.credentials.get({
publicKey: options,
signal: controller.signal,
// Request conditional get
mediation: 'conditional'
});
// Abort the call
controller.abort();
Ignorar as exceções de forma adequada
Quando uma criação de chave de acesso condicional é realizada, há alguns casos em que é necessário ignorar exceções:
InvalidStateError: uma chave de acesso já existe no provedor.NotAllowedError: a criação de uma chave de acesso não atende à condição.AbortError: a chamada do WebAuthn é abortada.
A exibição de erros nesses casos pode confundir o usuário, já que o navegador os processa silenciosamente: ele mostra uma notificação apenas em caso de sucesso, e as falhas não acionam mensagens visíveis.
Sinal quando o registro de uma chave de acesso falha
Quando uma chave de acesso é criada, mas não é registrada no servidor, o usuário não consegue fazer login. Isso pode acontecer quando a lista de chaves de acesso é inconsistente entre o provedor e o servidor.
Para evitar essas circunstâncias, use a API Signal para manter a consistência.
Não é possível fazer upgrade de logins sem senha
Nesse ponto, a criação de uma chave de acesso condicionalmente é bloqueada pelo usuário digitando uma senha válida. Isso significa que as abordagens de login sem senha, como links mágicos, verificação de número de telefone ou federação de identidade, não atendem à condição.
Resumo
Os upgrades de chaves de acesso podem acelerar a adoção de chaves de acesso no seu site, ajudando os usuários a fazer a transição de senhas para um método de autenticação mais seguro.
Para saber mais sobre chaves de acesso, consulte Fazer login sem senha com chaves de acesso.