Ajude os usuários a adotar chaves de acesso com mais facilidade

Eiji Kitamura

Publicado em: 9 de maio de 2025, última atualização: 22 de dezembro de 2025

As chaves de acesso oferecem autenticação forte e resistente a phishing. No entanto, fazer com que os usuários as 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 da WebAuthn.

Como funciona

Para ajudar os usuários a adotar chaves de acesso com mais facilidade, 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 a criação condicional imediatamente após um login bem-sucedido baseado em senha.

Se as duas 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 é notificado dependendo do gerenciador de senhas.

Compatibilidade

A criação condicional é compatível com o Safari no macOS e todos os navegadores no iOS, bem como o Chrome no computador e o Chrome no Android.

Esse suporte significa que ele funciona nos provedores de chaves de acesso padrão: Chaves do iCloud (senhas) no Safari no macOS e iOS e o Gerenciador de senhas do Google no Chrome no computador e no Android.

Como o iOS 18 ou mais recente e o Android 14 ou mais recente oferecem suporte a provedores de chaves de acesso de terceiros, independentemente do navegador usado pelo usuário, o suporte à criação condicional depende do provedor de chaves de acesso. Se o provedor de chaves de acesso selecionado não oferecer suporte à criação condicional, uma nova chave de acesso não será criada.

Implementar a criação condicional

A criação automática de chaves de acesso é baseada em um recurso da API WebAuthn chamado criação condicional. Essas são solicitações create() normais da WebAuthn com o mediation parâmetro 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. Se a criação será bem-sucedida depende do gerenciador de senhas e de determinadas condições. 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 o back-end para concluir o registro e ativar a autenticação futura.

Detecção de recursos

Você pode determinar se a criação condicional está disponível no navegador invocando 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 realizar uma criação automática de chaves de acesso, invoque navigator.credentials.create(), mas com mediation: "conditional", como mostrado abaixo.

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 para o servidor para verificar e registrar a chave de acesso. No servidor, verifique se o usuário está conectado.

Advertências

A criação condicional em si não é difícil de implementar, mas há várias advertências 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 realizar uma criação automática de chaves de acesso

Quando o RP espera que o usuário faça login com uma chave de acesso ou uma senha, a melhor opção é realizar uma busca condicional. Isso pode fazer com que a chamada de busca 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 normalmente

Quando uma criação condicional de chaves de acesso é realizada, há alguns casos em que você precisa ignorar exceções:

• InvalidStateError: uma chave de acesso já existe no provedor de chaves de acesso. Lembre-se de especificar excludeCredentials.
• NotAllowedError: a criação de uma chave de acesso não atende à condição.
• AbortError: a chamada WebAuthn é interrompida.

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.

Sinalizar quando o registro de uma chave de acesso falha

Quando uma chave de acesso é criada, mas não é registrada no servidor, o usuário vai receber uma tentativa de login com falha. Isso pode acontecer quando a lista de chaves de acesso é inconsistente entre o provedor de chaves de acesso e o servidor.

Para evitar essas circunstâncias, use a API Signal para mantê-las consistentes.

O upgrade de logins sem senha não é compatível

Neste momento, a criação condicional de uma chave de acesso é limitada ao usuário que insere uma senha válida. 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 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, comece pelo login sem senha com chaves de acesso.