Publicado em: 09 de maio de 2025
As chaves de acesso oferecem autenticação avançada e resistente a phishing. No entanto, fazer com que os usuários os adotem pode gerar atrito. Com a criação automática de chaves de acesso, você pode 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 a criação automática de chaves de acesso, faz parte da especificação WebAuthn.
Como funciona
Para ajudar os usuários a adotar chaves de acesso com mais conveniência, 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. O ideal é chamar o Conditional Create imediatamente após um login com senha bem-sucedido.
Se as duas condições forem atendidas, você poderá pedir ao gerenciador de senhas para criar 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 todos os navegadores no iOS, além do Chrome no computador e no Android.
Implementar a criação condicional
A criação automática de chaves de acesso se baseia em um recurso da API WebAuthn chamado
Criação condicional. Essas são solicitações regulares de create() WebAuthn com o parâmetro mediation definido como "conditional", que funciona de maneira semelhante ao preenchimento automático de chaves de acesso para solicitações get().
Use a criação condicional depois que o usuário fizer login com uma senha. O sucesso da criação depende do gerenciador de senhas e de determinadas condições serem atendidas. Essas condições podem variar de acordo com o gerenciador de senhas e 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 ativar 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 não estiver disponível, a criação condicional também não estará.
Criar uma chave de acesso condicionalmente
Para fazer uma criação automática de chave de acesso, invoque
navigator.credentials.create(), mas com mediation: "conditional" assim.
const cred = await navigator.credentials.create({
publicKey: options,
// Request conditional creation
mediation: 'conditional'
});
Use a criação automática de chaves de acesso imediatamente após o login do usuário para ter a melhor chance de atender aos critérios do gerenciador de senhas para criação automática.
Você pode 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 está conectado.
Advertências
A criação condicional não é difícil de implementar, mas há várias ressalvas ao integrar esse recurso a um sistema atual.
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 WebAuthn em andamento antes de criar uma chave de acesso automática
Quando o RP espera que o usuário faça login com uma chave de acesso ou uma senha, realizar uma busca condicional é a melhor opção. Isso pode fazer com que a chamada GET condicional seja cancelada antes de uma criação condicional.
Para 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 sem estresse
Quando uma criação condicional de chaves de acesso é realizada, há alguns casos em que você precisa ignorar exceções:
InvalidStateError: já existe uma chave de acesso no provedor de chaves de acesso. Não se esqueça de especificarexcludeCredentials.NotAllowedError: criar uma chave de acesso não atende à condição.AbortError: a chamada WebAuthn foi cancelada.
Mostrar 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.
Sinalizar quando o registro de uma chave de acesso falhar
Quando uma chave de acesso é criada, mas não é registrada no servidor, o usuário tem uma tentativa de login com falha. 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
Neste ponto, a criação condicional de uma chave de acesso é controlada pela entrada de uma senha válida pelo usuário. Isso significa que 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
A criação automática de chaves de acesso pode acelerar a adoção delas 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, comece com Login sem senha com chaves de acesso.