Detecção de recursos da WebAuthn mais simples

Eiji Kitamura

Publicado em 15 de janeiro de 2025, atualizado em 9 de abril de 2026

A WebAuthn oferece recursos exclusivos, como interação com Bluetooth para o protocolo híbrido, comunicação com provedores de chaves de acesso e sugestão de chaves de acesso no preenchimento automático. No entanto, diferentes clientes e autenticadores oferecem níveis variados de suporte para recursos da WebAuthn. Essa disparidade pode levar a uma experiência do usuário fragmentada, em que alguns usuários podem encontrar erros ou não conseguir usar determinadas opções de autenticação. Ao oferecer uma maneira para os desenvolvedores determinarem os recursos do cliente, eles podem criar fluxos de autenticação mais robustos que se adaptam a essas variações.

O método PublicKeyCredential.getClientCapabilities() permite que as partes confiáveis determinem quais recursos da WebAuthn são compatíveis com o navegador. O método retorna uma promessa que é resolvida em uma lista de recursos compatíveis, permitindo que os desenvolvedores personalizem as experiências e os fluxos de trabalho de autenticação com base nos recursos específicos do cliente.

Compatibilidade

getClientCapabilities()

A getClientCapabilities() é uma API WebAuthn que permite que as partes confiáveis determinem quais recursos estão disponíveis. Para usar a API, é necessário chamar PublicKeyCredential.getClientCapabilities(). A promessa retornada é resolvida em um objeto que contém recursos, cada um indicando a disponibilidade com true ou false. Se o recurso for undefined, considere que a disponibilidade dele não é conhecida.

if (window.PublicKeyCredential && PublicKeyCredential.getClientCapabilities) {
  const capabilities = await PublicKeyCredential.getClientCapabilities();
  if (capabilities.conditionalGet === true &&
      capabilities.passkeyPlatformAuthenticator === true) {
    // The browser supports passkeys and the conditional mediation.
  }
}

conditionalCreate

O navegador pode criar uma credencial sem uma interface modal proeminente se o usuário já tiver consentido em criar uma.

conditionalGet

O navegador pode autenticar mostrando chaves de acesso como parte da caixa de diálogo de preenchimento automático, em vez de uma interface modal proeminente. O equivalente atual é PublicKeyCredential.isConditionalMediationAvailable().

hybridTransport

O dispositivo pode usar o Bluetooth para que o navegador possa criar uma credencial e autenticar com ela entre dispositivos usando o protocolo híbrido. Isso geralmente significa que o navegador pode mostrar um QR code para que o usuário possa digitalizar e fazer login com um smartphone que tenha uma credencial.

passkeyPlatformAuthenticator

O navegador pode criar uma credencial e autenticar com ela usando um autenticador de plataforma de verificação do usuário ou outro dispositivo que ofereça suporte a ela pelo protocolo híbrido. Equivalente a hybridTransport || userVerifyingPlatformAuthenticator.

relatedOrigins

O navegador pode criar uma credencial e autenticar com ela que não corresponda ao ID da RP, desde que ela seja especificada em o arquivo de origens relacionadas.

signalAllAcceptedCredentials

O navegador pode sinalizar as credenciais disponíveis no servidor para o provedor de chaves de acesso , para que ele possa manter a lista de chaves de acesso consistente com o servidor.

signalCurrentUserDetails

O navegador pode sinalizar informações do usuário, como nome de usuário e nome de exibição no servidor para o provedor de chaves de acesso, para que ele possa manter as informações de chaves de acesso consistentes com o servidor.

signalUnknownCredential

O navegador pode sinalizar uma credencial excluída no servidor para o provedor de chaves de acesso , para que ele possa manter a lista de chaves de acesso consistente com o servidor.

userVerifyingPlatformAuthenticator

O navegador pode criar e autenticar com uma credencial em um autenticador de plataforma. Isso não significa que o navegador oferece suporte ao protocolo híbrido. O equivalente atual é PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable().

extensions

As RPs também podem determinar as extensões disponíveis com getClientCapabilities().

if (capabilities['extension:appid'] === true) {
  // appId extension is supported
}

O identificador é prefixado com extension: seguido por um nome de extensão. Consulte os identificadores de extensão da WebAuthn definidos na IANA para nomes de extensão.

Saiba mais

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