Dicas de Credencial de Chave Pública / User-Agent do WebAuthn

O WebAuthn e as passkeys estão ganhando um forte impulso e cada vez mais adoção. Além disso, do ponto de vista técnico, o padrão WebAuthn está evoluindo rapidamente. As dicas de credencial de chave pública do WebAuthn (também chamadas de Dicas de User-Agent) são a mais recente adição à API de Autenticação da Web, com o objetivo de aprimorar a forma como os desenvolvedores implementam a autenticação com passkeys em suas aplicações.

Neste artigo, responderemos às seguintes perguntas:

• O que são as Dicas de Credencial de Chave Pública do WebAuthn?
• Por que precisamos das Dicas de Credencial de Chave Pública do WebAuthn?
• Como funcionam as Dicas de Credencial de Chave Pública do WebAuthn?
• Quais são as limitações e os casos recomendados para o uso das Dicas de Credencial de Chave Pública do WebAuthn em seus projetos?

Para começar, vamos analisar a motivação.

Atualmente, existem diferentes locais onde se pode criar e armazenar uma passkey:

• Gerenciador de senhas de terceiros (ex: 1Password, Dashlane, Bitwarden, KeePassXC)
• Gerenciador de Senhas do Google / Perfil do Chrome
• Chaves do iCloud / Senhas da Apple
• Windows Hello
• Outro smartphone (iOS, Android) ou tablet (iPadOS, Android)
• Chave de segurança de hardware (ex: YubiKey)

Para o usuário, isso pode oferecer flexibilidade e liberdade de escolha. No entanto, algumas aplicações e cenários exigem a restrição de algumas dessas opções, por exemplo, se for necessário permitir apenas chaves de segurança de hardware devido a requisitos de segurança elevados.

Para influenciar a criação de passkeys e seu armazenamento, tínhamos a propriedade authenticatorAttachment.

Subscribe to our Passkeys Substack for the latest news.

Subscribe

A propriedade authenticatorAttachment permite que as partes confiáveis (relying parties) restrinjam onde a passkey pode ser criada.

platform indica um autenticador que está integrado ao dispositivo que executa o WebAuthn. O WebAuthn se comunica com ele usando métodos de transporte específicos da plataforma, como APIs nativas. Uma credencial de chave pública vinculada a um autenticador de plataforma é chamada de credencial de plataforma. Da lista acima, os seguintes gerenciadores de credenciais / locais poderiam armazenar credenciais de plataforma:

• Gerenciador de senhas de terceiros (ex: 1Password, Dashlane, Bitwarden, KeePassXC)
• Gerenciador de Senhas do Google / Perfil do Chrome
• Chaves do iCloud / Senhas da Apple
• Windows Hello

Windows 11 e Chrome:

macOS 15 (Sequoia) e Chrome:

Ao clicar em Cancelar, o seguinte modal aparece:

macOS 15 (Sequoia) e Safari:

cross-platform indica um autenticador externo ao dispositivo que executa o WebAuthn (autenticador itinerante), pois pode ser usado em múltiplos dispositivos. O WebAuthn interage com ele usando protocolos de transporte multiplataforma como Bluetooth ou NFC. Uma credencial de chave pública associada a um autenticador itinerante é chamada de credencial itinerante. Da lista acima, os seguintes gerenciadores de credenciais / locais poderiam armazenar credenciais multiplataforma:

• Outro smartphone (iOS, Android) ou tablet (iPadOS, Android)
• Chave de segurança de hardware (ex: YubiKey)

Windows 11 e Chrome:

macOS 15 (Sequoia) e Chrome:

macOS 15 (Sequoia) e Safari:

Não especificado indica que tanto um autenticador de plataforma quanto um autenticador multiplataforma podem ser usados. Aqui, o usuário pode escolher onde gostaria de armazenar as passkeys.

Windows 11 e Chrome:

macOS 15 (Sequoia) e Chrome:

macOS 15 (Sequoia) e Safari:

Ao clicar em Cancelar, o seguinte modal aparece:

O authenticatorAttachment foi usado por bastante tempo. No entanto, também era inflexível em relação a novos desenvolvimentos como a Autenticação Entre Dispositivos (via códigos QR e Bluetooth). Nesse caso, uma passkey também é armazenada, por exemplo, no Gerenciador de Senhas do Google (credencial de plataforma), mas acionada com cross-platform pela parte confiável. Além disso, o controle de uma parte confiável para influenciar o tipo de passkey a ser usada em uma cerimônia de login (não de registro) só podia ser feito modificando o valor transports de uma credencial.

É aí que entram as Dicas de Credencial de Chave Pública do WebAuthn.

Become part of our Passkeys Community for updates & support.

Join

As dicas de credencial de chave pública do WebAuthn são um novo parâmetro introduzido na API de Autenticação da Web (oficialmente no WebAuthn Nível 3). Elas fornecem orientação aos navegadores sobre o tipo de autenticador que um usuário provavelmente usará durante o processo de autenticação. Isso ajuda a oferecer uma experiência de usuário mais simplificada e intuitiva, focando a UI do navegador nas opções mais relevantes.

Os Três Tipos de Dicas

As dicas vêm em três tipos:

1. security-key: Indica que se espera que o usuário use uma chave de segurança de hardware (ex: YubiKey).
2. client-device: Sugere que o usuário usará um autenticador de plataforma conectado ao dispositivo cliente (como Touch ID no macOS, Face ID no iOS ou Windows Hello no Windows).
3. hybrid: Implica que o usuário pode usar um smartphone ou tablet para autenticação entre dispositivos via código QR e Bluetooth.

Essas dicas não são requisitos estritos da parte confiável, mas servem como orientação para aprimorar a experiência do usuário, como dicas para o navegador.

A seguir, você verá capturas de tela para macOS Sequoia (Edge + Chrome) e Windows 10 (Chrome) com authenticatorAttachment não especificado e a Dica de User-agent do WebAuthn definida como security-key.

Aqui, vemos outra limitação: a dica security-key não é respeitada no Windows 10, pelo menos não diretamente. O fluxo é basicamente o mesmo que para a dica client-device.

Ao clicar em Cancelar, o seguinte modal aparece:

A seguir, você verá capturas de tela para macOS Sequoia (Edge + Chrome) e Windows 10 (Chrome) com authenticatorAttachment não especificado e a Dica de User-agent do WebAuthn definida como client-device.

Ao clicar em Cancelar, o seguinte modal aparece:

Ao clicar em Cancelar, o seguinte modal aparece:

Ao clicar em Cancelar, o seguinte modal aparece:

A seguir, você verá capturas de tela para macOS Sequoia (Edge + Chrome) e Windows 10 (Chrome) com authenticatorAttachment não especificado e a Dica de User-agent do WebAuthn definida como hybrid.

Com a introdução das dicas, os desenvolvedores agora podem fornecer um array de preferências em ordem decrescente de prioridade, oferecendo mais flexibilidade.

O trecho de código abaixo informa ao navegador que o usuário provavelmente se autenticará usando uma chave de segurança de hardware, focando a UI de acordo.

Para compatibilidade com user agents mais antigos, quando esta dica é usada em PublicKeyCredentialCreationOptions, o authenticatorAttachment deve ser definido como cross-platform.

const credential = await navigator.credentials.create({
  publicKey: {
    challenge: /* your challenge here */,
    hints: ['security-key'],
    authenticatorSelection: {
      authenticatorAttachment: 'cross-platform'
    }
  }
});

A dica security é particularmente valiosa em casos de alta garantia, onde o site / parte confiável deseja permitir apenas chaves de segurança de hardware e direciona o usuário nesse sentido.

Neste exemplo, a dica sugere que o usuário pode usar o autenticador de plataforma integrado do dispositivo atual.

Para compatibilidade com user agents mais antigos, quando esta dica é usada em PublicKeyCredentialCreationOptions, o authenticatorAttachment deve ser definido como platform.

const credential = await navigator.credentials.create({
  publicKey: {
    challenge: /* your challenge here */,
    residentKey: true,
    hints: ['client-device'],
    authenticatorSelection: {
      authenticatorAttachment: 'platform'
    }
  }
});

Definir a dica client-device é benéfico se houver várias passkeys associadas a uma conta de usuário e algumas delas puderem estar disponíveis no dispositivo que está fazendo o login, enquanto outras estão armazenadas em dispositivos diferentes. Se o sistema (inteligência de passkeys) detectar que o usuário tentando fazer login tem alta probabilidade de ter uma passkey local disponível, então esta dica pode ser definida nas PublicKeyCredentialRequestOptions, economizando um clique do usuário para selecionar a passkey correta.

Neste exemplo, a dica sugere que o usuário pode usar um smartphone ou um dispositivo similar para autenticação.

Para compatibilidade com user agents mais antigos, quando esta dica é usada em PublicKeyCredentialCreationOptions, o authenticatorAttachment deve ser definido como cross-platform.

const credential = await navigator.credentials.create({
  publicKey: {
    challenge: /* your challenge here */,
    residentKey: true,
    hints: ['hybrid'],
    authenticatorSelection: {
      authenticatorAttachment: 'cross-platform'
    }
  }
});

A dica hybrid pode ser útil se o usuário tiver várias chaves e o sistema (inteligência de passkeys) detectar que no dispositivo atual provavelmente não há uma passkey local disponível. Para melhorar a UX e economizar um clique, você pode definir esta Dica de User-agent do WebAuthn e solicitar diretamente ao usuário a autenticação entre dispositivos (via código QR e Bluetooth). Além disso, se você está tentando construir um sistema de passkey mobile-first, definir esta dica faz muito sentido.

Para experimentar você mesmo as diferentes opções, recomendamos dar uma olhada no Passkeys Debugger.

Want to experiment with passkey flows? Try our Passkeys Debugger.

Try for Free

É crucial entender como as Dicas de Credencial de Chave Pública do WebAuthn interagem com outros parâmetros do WebAuthn, como authenticatorAttachment e credential transports.

Primeiramente, é importante notar que essas dicas não são requisitos estritos. Elas não vinculam o user-agent (navegador), mas servem como orientação para fornecer a melhor experiência, aproveitando informações contextuais que você tem sobre a solicitação. Isso significa que os navegadores podem optar por considerar as dicas, mas não são obrigados a segui-las estritamente.

As dicas são fornecidas como um array em ordem de preferência decrescente. Esta ordem determina como o navegador deve priorizá-las:

• A Primeira Dica Tem Precedência: Se duas dicas forem contraditórias, o navegador dá prioridade à primeira.
• Dicas Sobrepostas: Se uma dica mais específica pode não ser reconhecida por todos os navegadores, você pode incluir outras menos específicas depois para uma compatibilidade mais ampla.
• Dicas Duplicadas: Se a mesma dica aparecer mais de uma vez, quaisquer aparições subsequentes são ignoradas.

Exemplo:

hints: ['security-key', 'hybrid', 'client-device']

Neste array:

1. O navegador primeiro prioriza security-key.
2. Se não for aplicável, ele considera hybrid.
3. Por último, ele analisa client-device (autenticadores de plataforma no dispositivo cliente).

As dicas podem contradizer informações contidas em authenticatorAttachment e credential transports. Quando isso ocorre, as dicas têm precedência. Isso oferece mais flexibilidade em comparação com o uso estrito anterior de authenticatorAttachment, que limitava o autenticador a platform ou cross-platform.

Exemplo com Parâmetros Contraditórios:

const credential = await navigator.credentials.create({
  publicKey: {
    challenge: /* your challenge here */,
    hints: ['hybrid'],
    authenticatorSelection: {
      authenticatorAttachment: 'platform' // Contradiz a dica
    }
  }
});

Neste caso:

• Dica: Sugere uma preferência por autenticadores híbridos.
• authenticatorAttachment: Especifica platform, que normalmente limita os autenticadores ao dispositivo cliente.
• Resultado: O navegador prioriza a dica sobre o authenticatorAttachment, focando nas opções híbridas.

Atualmente, as dicas de credencial de chave pública do WebAuthn estão disponíveis apenas no Chrome (a partir da versão 128). Até o momento, Edge e Safari indicaram planos para integrar este recurso, enquanto o Firefox ainda não confirmou seu cronograma de lançamento.

É importante lembrar que no Chrome, o parâmetro authenticatorAttachment continua a ser respeitado por enquanto. Isso significa que hoje o authenticatorAttachment é o fator decisivo, não importa qual dica seja definida. No entanto, esperamos que em futuras versões do Chrome, as dicas de credencial de chave pública se tornem a abordagem preferida e única.

Mesmo que a versão mais recente do Chrome suporte as Dicas de User-agent do WebAuthn, essas dicas não são respeitadas pelo Windows 11 e pelo Windows Hello / Segurança do Windows. A razão subjacente é que a UI é controlada pelo próprio sistema operacional (Windows Hello / Segurança do Windows).

Além disso, para uma passkey que está armazenada no Gerenciador de Senhas do Google e sincronizada com o Windows 11, as Dicas de User-agent do WebAuthn não são respeitadas, pois a autenticação local final no Windows 11 acontece com o Windows Hello / Segurança do Windows. Com a futura sincronização de passkeys no Windows 11 via contas da Microsoft, também esperamos melhorias para o Windows 11 e as Dicas de User-agent do WebAuthn.

No Windows 10, as Dicas de User-agent do WebAuthn são respeitadas, pois a UI do WebAuthn é gerenciada pelo Chrome e não pelo Windows Hello / Segurança do Windows. No entanto, durante nossos testes, não vimos um efeito para security-key. Quando esta dica foi definida, o fluxo parecia o mesmo que para client-device.

As dicas de credencial de chave pública (user-agent) do WebAuthn trazem uma série de benefícios tanto para desenvolvedores quanto para usuários. O recurso ainda é novo e não foi implementado em todos os navegadores e sistemas operacionais (até outubro de 2024).

É importante estar ciente das limitações atuais que vêm especialmente com o Windows 11. No Windows 11, a UI de passkeys é gerenciada pelo Windows Hello (modal de segurança do Windows Hello) e isso atualmente se sobrepõe ao suporte do Chrome / Edge para as Dicas de User-agent do WebAuthn. Isso também se aplica a passkeys sendo sincronizadas do Gerenciador de Senhas do Google para o Windows (aqui, as dicas também não têm efeito ainda).

Isso significa que as dicas de credencial de chave pública do WebAuthn realmente funcionam apenas no macOS e no Windows 10 (dos principais sistemas operacionais de desktop).

Além disso, até outubro de 2024, mesmo que o Chrome / Edge seja usado nesses sistemas operacionais, se o authenticatorAttachment for definido, ele também se sobrepõe às Dicas de User-agent do WebAuthn (conforme afirmado pelo Google).

Do ponto de vista de casos de uso, vemos os seguintes casos de uso recomendados para obter o máximo valor deste novo recurso.

Ao construir seu backend e inteligência de passkeys, tente incluir o uso correto das dicas de credencial de chave pública para facilitar o login e poupar o usuário de cliques desnecessários. Por exemplo, se seu sistema detectar que um usuário está fazendo login em um dispositivo onde provavelmente há uma passkey local disponível, use a dica client-device.

Se o usuário acessar o site de um novo dispositivo e sua inteligência de passkeys souber que uma passkey pode estar disponível em um dispositivo móvel do usuário, defina a dica como hybrid, para que o usuário possa escanear rapidamente o código QR e usar a passkey híbrida.

O objetivo principal aqui é fornecer uma experiência de usuário mais fluida e intuitiva. Ao orientar os navegadores sobre quais autenticadores provavelmente serão usados, os desenvolvedores podem reduzir a confusão e o atrito do usuário durante o processo de login. Em vez de os usuários serem sobrecarregados com opções de autenticação desnecessárias, as dicas permitem que os navegadores se concentrem nas escolhas mais relevantes, o que leva a uma experiência mais rápida e direta.

Empresas de alta garantia ou organizações governamentais que padronizaram o uso de chaves de segurança de hardware para autenticação de usuários acharão as dicas de credencial de passkey particularmente úteis. Usando a dica security-key, elas podem garantir que os navegadores exibam प्रमुखmente a opção de chave de segurança de hardware.

Isso é especialmente útil para grandes organizações onde os funcionários receberam chaves de segurança de hardware e onde outros métodos de autenticação (como autenticadores de plataforma) não são permitidos. A dica security-key permite que as empresas restrinjam seus fluxos de autenticação sem limitar sua flexibilidade para melhorias futuras.

A dica hybrid se destaca em cenários onde a autenticação entre dispositivos e, portanto, uma abordagem mobile-first é desejada ou quando os usuários se movem frequentemente entre dispositivos ou plataformas.

Um exemplo desse caso de uso seria um aplicativo voltado para o consumidor que antecipa que a maioria de seus usuários usará seus smartphones para autenticação, seja por meio de métodos biométricos ou aplicativos de autenticação baseados na web (passkeys mobile-first). Ao especificar hybrid como uma dica, os desenvolvedores garantem que a UI do navegador incentive o uso do smartphone, melhorando a conveniência e a acessibilidade.

As dicas de credencial de chave pública do WebAuthn oferecem uma maneira flexível de aprimorar a experiência do usuário durante a autenticação com passkeys. Vamos revisitar as perguntas da introdução com os insights que reunimos:

1. O que são as Dicas de Credencial de Chave Pública do WebAuthn?

   São sugestões opcionais fornecidas pelo site / aplicativo para orientar os clientes sobre o método de autenticação mais provável que um usuário usará – seja uma chave de segurança de hardware, um autenticador de plataforma ou uma solução híbrida como a autenticação entre dispositivos.

2. Por que precisamos das Dicas de Credencial de Chave Pública do WebAuthn?

   Elas simplificam o processo de autenticação, reduzindo as opções apresentadas aos usuários, diminuindo o atrito / cliques desnecessários e melhorando a experiência geral.

3. Como funcionam as Dicas de Credencial de Chave Pública do WebAuthn?

   Os desenvolvedores especificam dicas como security-key, client-device ou hybrid com base no contexto, permitindo que os navegadores priorizem o método de autenticação relevante para o usuário. Embora essas dicas não sejam requisitos estritos, elas ajudam a otimizar o fluxo da UI durante a autenticação.

4. Quais são as limitações e os casos de uso recomendados?

   Atualmente, o suporte total a essas dicas é limitado ao Chrome e Edge, com outros navegadores e sistemas operacionais como o Windows 11 mostrando níveis variados de compatibilidade. Os casos de uso mais eficazes incluem melhorar a UX de login, impor o uso de chaves de segurança de hardware em ambientes de alta segurança e permitir a autenticação entre dispositivos em aplicações mobile-first.

Em conclusão, as Dicas de Credencial de Chave Pública do WebAuthn permitem que os desenvolvedores criem processos de autenticação mais intuitivos e amigáveis ao usuário, orientando os navegadores para as opções mais apropriadas para cada cenário de usuário. Embora ainda em evolução, este recurso pode aprimorar significativamente tanto a segurança quanto a experiência do usuário em implementações de passkeys.