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 o Bluetooth para o protocolo híbrido, comunicação com provedores de chave 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 aos recursos do WebAuthn. Essa disparidade pode levar a uma experiência de usuário fragmentada, em que alguns usuários podem encontrar erros ou não conseguir usar certas opções de autenticação. Fornecer uma maneira de os desenvolvedores determinarem os recursos do cliente permite que eles criem 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 com suporte, permitindo que os desenvolvedores personalizem as experiências de autenticação e os fluxos de trabalho 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, você precisa chamar PublicKeyCredential.getClientCapabilities(). A promessa retornada é resolvida para um objeto que contém recursos, cada um indicando a disponibilidade com true ou false. Se o capability 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á consentiu com a criação.

conditionalGet

O navegador pode fazer a autenticação mostrando chaves de acesso como parte de uma 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 possa criar uma credencial e autenticá-la entre dispositivos usando o protocolo híbrido. Isso normalmente significa que o navegador pode mostrar um código QR para que o usuário possa digitalizá-lo e fazer login com um smartphone que tenha uma credencial.

passkeyPlatformAuthenticator

O navegador pode criar uma credencial e fazer a autenticação com ela usando um autenticador de verificação de plataforma 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 fazer a autenticação com ela que não corresponde ao RP ID, desde que seja 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 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 chave de acesso, para que ele possa manter 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 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 ofereça suporte ao 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 tem o prefixo extension: seguido pelo nome da extensão. Consulte os identificadores de extensão da WebAuthn definidos na IANA para nomes de extensões.

Saiba mais

Para saber mais sobre chaves de acesso, consulte Fazer login sem senha com chaves de acesso.