Detecção de recursos da WebAuthn mais simples com getClientCapabilities()

Eiji Kitamura

Publicado em: 15 de janeiro de 2025

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 do WebAuthn. Essa disparidade pode levar a uma experiência 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 do 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 experiências e fluxos de trabalho de autenticação com base nos recursos específicos do cliente.

Compatibilidade

getClientCapabilities()

O getClientCapabilities() é uma API WebAuthn que permite que as partes confiáveis determinem quais recursos estão disponíveis. Para usar a API, chame 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 &&
  if (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 em destaque 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 em destaque. O equivalente atual é PublicKeyCredential.isConditionalMediationAvailable().

hybridTransport

O dispositivo pode usar o Bluetooth para que o navegador crie uma credencial e faça a autenticação com ela em vários dispositivos usando o protocolo híbrido. Isso geralmente significa que o navegador pode mostrar um QR code para que o usuário o digitalize e faça login com um smartphone que tenha uma credencial.

passkeyPlatformAuthenticator

O navegador pode criar uma credencial e se autenticar com ela usando um autenticador de plataforma de verificação do usuário ou outro dispositivo compatível com o protocolo híbrido. É equivalente a hybridTransport || userVerifyingPlatformAuthenticator.

relatedOrigins

O navegador pode criar uma credencial e autenticar com ela que não corresponda ao ID do RP, desde que esteja especificado no 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 mantenha 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 o provedor mantenha as informações da chave 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 mantenha 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 é compatível com o protocolo híbrido. O equivalente atual é PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable().

extensões

Os 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 do WebAuthn definidos na IANA (link em inglês) para nomes de extensão.

Saiba mais

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