Capacidades do Cliente WebAuthn

Passkeys Cheat Sheet — dev-focused WebAuthn reference. Trusted by Ally, Stanford CS & more.

Get Cheat Sheet

O WebAuthn é o padrão moderno por trás das passkeys. Em vez de depender das senhas tradicionais, ele utiliza criptografia de chave pública, permitindo que os usuários se autentiquem com passkeys, que podem incluir biometria (como impressões digitais ou reconhecimento facial) ou chaves de segurança físicas. Essa mudança não apenas melhora a segurança, mas também torna a experiência do usuário muito mais fluida, eliminando a dor de cabeça de gerenciar senhas.

O padrão WebAuthn Nível 3 introduz novas capacidades do cliente (que podem ser obtidas através da API do navegador getClientCapabilities()), com o objetivo de dar aos desenvolvedores e plataformas mais controle e flexibilidade ao implementar passkeys. Essas atualizações trazem melhorias que simplificam o processo de integração de passkeys em vários dispositivos, navegadores e plataformas, garantindo uma jornada mais consistente.

Neste artigo, vamos responder às seguintes perguntas:

1. O que são as capacidades do cliente WebAuthn?
2. Quais capacidades do cliente WebAuthn existem?
3. Como as capacidades do cliente WebAuthn melhoram as implementações de passkeys?
4. Por que essas capacidades são importantes para desenvolvedores e gerentes de produto?

No final, você entenderá como esses recursos podem ajudar a criar fluxos de autenticação seguros e perfeitos, que se alinham às expectativas modernas dos usuários.

As capacidades do cliente WebAuthn são um conjunto de recursos que permitem aos navegadores e plataformas comunicar quais funcionalidades do WebAuthn eles suportam. Em termos simples, elas agem como uma "lista de verificação de recursos" que informa aos sites quais métodos de autenticação e configurações estão disponíveis no dispositivo do usuário. Isso nos permite adaptar os fluxos de autenticação com base nessas capacidades, garantindo uma experiência mais segura e sem atritos.

Por exemplo, se um navegador indicar que suporta autenticação biométrica (como o Touch ID), podemos criar nossos fluxos de login para oferecer a opção de entrar com a impressão digital. Por outro lado, se o navegador não suportar determinados recursos, podemos fornecer opções alternativas, como uma senha ou SMS OTP. Na prática, caminhos de capacidade não suportados ou interrompidos ainda podem aparecer como falhas genéricas do navegador, então é uma boa ideia mapear esses resultados para uma classificação explícita de erro do WebAuthn.

O padrão WebAuthn Nível 3 traz diversas novas capacidades do cliente que tornam as implementações de passkeys mais versáteis e amigáveis. O primeiro suporte para a chamada de API getClientCapabilities() surgiu no Safari 17.4.

Para detectar o suporte no navegador, o seguinte trecho de código pode ser útil:

// Verifica se o PublicKeyCredential é suportado no navegador atual
if (typeof PublicKeyCredential === "undefined") {
    console.log("PublicKeyCredential não é suportado neste navegador.");
}
 
// Verifica se o método getClientCapabilities existe no PublicKeyCredential
if (typeof PublicKeyCredential.getClientCapabilities === "function") {
    try {
        let capabilities = await PublicKeyCredential.getClientCapabilities();
        console.log(capabilities);
    } catch (error) {
        console.error("Erro ao obter capacidades do cliente:", error);
    }
} else {
    console.log("getClientCapabilities não é suportado neste navegador");
}

O getClientCapabilities() permite que sites e aplicativos consultem o cliente (por exemplo, navegador ou dispositivo) para descobrir quais recursos do WebAuthn ele suporta. Ao entender as capacidades do cliente, podemos otimizar os fluxos de autenticação para aproveitar os recursos disponíveis, como a autenticação biométrica, e fornecer métodos alternativos se algumas capacidades estiverem ausentes.

Subscribe to our Passkeys Substack for the latest news.

Subscribe

Aqui está uma visão mais detalhada das capacidades do cliente WebAuthn e como elas impactam a integração de passkeys:

O conditionalCreate permite a criação automática de passkeys com base em condições específicas. Um aplicativo pode usar essa capacidade para criar uma passkey automaticamente durante o preenchimento automático de senhas se o gerenciador de senhas tiver suporte correspondente. Esse recurso ajuda a impulsionar a adoção de passkeys e seu uso subsequente, fazendo uma transição automática das senhas para passkeys sem esforço para o usuário.

Semelhante ao conditionalCreate, o conditionalGet aciona os logins com passkey automaticamente. Isso é muito útil em cenários em que queremos habilitar a melhor UX possível de passkey, tornando o login não apenas sem senha, mas também sem nome de usuário (os usuários simplesmente clicam na passkey selecionada em um modal ou menu suspenso e se autenticam). Ao usar essa capacidade, garantimos que a autenticação com passkey ocorra apenas quando apropriado, minimizando prompts desnecessários e melhorando a experiência.

O hybridTransport garante que as passkeys possam ser usadas em diferentes dispositivos, permitindo uma autenticação cruzada perfeita (via QR codes e Bluetooth). Por exemplo, um usuário pode usar uma passkey armazenada no smartphone para fazer login em um serviço no desktop. Isso permite uma autenticação segura sem a necessidade de transferir passkeys manualmente ou depender de métodos de login convencionais em cada dispositivo, promovendo uma experiência unificada.

Autenticadores de plataforma, como Windows Hello, Face ID ou Touch ID, são integrados diretamente aos dispositivos e oferecem uma experiência de passkey mais rápida, suave e segura, permitindo que os usuários se autentiquem com biometria ou outro método nativo do dispositivo (como um PIN).

O userVerifyingPlatformAuthenticator garante que a autenticação com passkey envolva a verificação de usuário, como a leitura ativa de uma impressão digital ou o reconhecimento facial, adicionando uma camada extra de segurança.

A capacidade relatedOrigins permite uma autenticação fluida em diferentes domínios pertencentes à mesma organização (por exemplo, amazon.com e amazon.de). Se uma empresa gerencia vários domínios ou tem diferentes subdomínios, os usuários podem fazer login uma vez e acessar todas as propriedades sem precisarem se reautenticar em cada uma. Isso simplifica bastante a vida do usuário, reduz o atrito e é especialmente valioso para empresas em ambientes internacionais ou com plataformas de multisserviços.

O método signalAllAcceptedCredentials(options) fornece a lista completa de IDs de credenciais WebAuthn de um determinado usuário. As Relying Parties do WebAuthn devem usar este método em vez de signalUnknownCredential() quando o usuário estiver autenticado, pois não há risco de vazamento de privacidade. Ele oferece uma visão abrangente das credenciais de chave pública de um usuário, incluindo alterações recentes que podem não ter sido atualizadas nos autenticadores atualmente conectados.

Vamos dar uma olhada em um exemplo. Um usuário (userId: A) tem 2 passkeys com Credential IDs que codificam em Base64URL para X e Y. Então, o usuário exclui a passkey X nas configurações da conta do serviço web (example.com), o que significa que a chave pública é excluída. Agora, execute o seguinte trecho:

PublicKeyCredential.signalAllAcceptedCredentials({
    rpId: "example.com",
    userId: "A", // WebAuthn User Handle em Base64URL.
    allAcceptedCredentialIds: ["Y"],
});

Se o autenticador estiver disponível no momento da execução do código acima, ele excluirá ou ocultará a passkey X das futuras cerimônias de autenticação. No entanto, o autenticador pode não estar conectado na hora, então é recomendado que as relying parties executem esse código periodicamente, como a cada login.

Passkeys não presentes no allAcceptedCredentialIds serão removidas ou ocultadas, possivelmente de forma irreversível. Portanto, é essencial que as relying parties prestem atenção para que Credential IDs válidos nunca sejam removidos da lista. Se uma Credential ID válida for removida acidentalmente, a relying party deve incluí-la imediatamente em outra chamada signalAllAcceptedCredentials(options) o mais rápido possível para "revelar" a passkey. Se a passkey não estiver apenas oculta, mas removida, não há muito o que fazer para consertar.

Experiment with passkey flows in the Passkeys Debugger.

Try for Free

O método signalCurrentUserDetails(options) sinaliza o nome atual do usuário e o WebAuthn Display Name. Quando signalCurrentUserDetails(options) é chamado, o cliente segue um conjunto definido de etapas para executar essa ação.

Veja um exemplo. Um usuário com User ID WebAuthn A atualiza seu nome nas configurações de conta de um site (example.com). Em seguida, a relying party pode executar o seguinte código:

PublicKeyCredential.signalCurrentUserDetails({
    rpId: "example.com",
    userId: "A", // User ID em Base64URL.
    name: "Novo nome de usuário",
    displayName: "Novo display name",
});

O autenticador atualizará então os metadados da passkey salva localmente. A grande vantagem é que, em solicitações futuras de Conditional UI / preenchimento automático de passkey, o menu suspenso ou a seleção do Conditional UI mostrará o nome e o WebAuthn Display Name já atualizados.

O método signalUnknownCredential(options) avisa que um Credential ID WebAuthn não é reconhecido pela Relying Party, por exemplo, se a passkey foi excluída pelo usuário. Ao contrário do signalAllAcceptedCredentials(options), este método não exige o envio de toda a lista de IDs aceitos e do User Handle, prevenindo assim possíveis vazamentos de privacidade para chamadores não autenticados.

Veja um exemplo. Um usuário exclui uma passkey com Credential ID X nas configurações da conta de um site (example.com). No entanto, a chave privada ainda está disponível no dispositivo do usuário. Isso significa que em futuras requisições de login de Conditional UI / preenchimento automático de passkey (com uma lista allowCredentials vazia), essa passkey ainda poderá ser selecionada. A tentativa de login irá falhar, já que a chave pública foi excluída, então a relying party deve executar:

PublicKeyCredential.signalUnknownCredential({
    rpId: "example.com",
    credentialId: "X", // Credential ID que o usuário acabou de tentar, em Base64URL
});

O autenticador irá então excluir ou ocultar a passkey com o Credential ID X das próximas cerimônias de autenticação.

Como o padrão WebAuthn Nível 3 ainda está na fase de rascunho (draft), a adoção dessas novas capacidades de cliente ainda não é totalmente ampla. Diferentes navegadores têm implementado gradualmente esses recursos, mas o suporte varia. Abaixo está uma visão geral atualizada da disponibilidade nos principais navegadores citados:

O ritmo da adoção provavelmente irá acelerar à medida que o Nível 3 amadurecer e mais navegadores lançarem essas funcionalidades. Se você quiser ver quantos usuários podem tirar proveito do getClientCapabilities() agora mesmo, confira dados do mundo real usando o State of Passkeys (gratuito). Fique de olho nas notas de lançamento dos navegadores e na documentação relevante para se planejar para uma compatibilidade mais ampla.

See how many people actually use passkeys.

View Adoption Data

Como desenvolvedor, você pode se perguntar o que essa nova detecção de capacidades do WebAuthn significa para você e como usá-la em seu aplicativo. Abaixo, separamos algumas recomendações de uso.

Contudo, lembre-se de que nem todos os navegadores já suportam a API getClientCapabilities() (até novembro de 2024). Há um polyfill disponível aqui, que pode ser usado como um tapa-buraco até que todos os navegadores se atualizem.

Use o getClientCapabilities() no início do seu código para detectar os recursos suportados pelo cliente logo no início do carregamento da página ou do fluxo de autenticação. Isso permitirá que você personalize a experiência de forma dinâmica, fornecendo os recursos de passkey que funcionam naquele dispositivo ou navegador. Por exemplo, impulsionando a autenticação de plataforma quando suportada, ou oferecendo métodos alternativos (como SMS OTPs ou chaves de segurança de hardware) quando não for.

Se você estiver adicionando passkeys a um site ou aplicativo que atualmente usa senhas, o recurso conditionalCreate pode ser um verdadeiro impulsionador para a sua adoção de passkeys. Nos bastidores, durante o preenchimento automático de senhas com um gerenciador compatível (apenas o Apple Passwords suporta isso até outubro de 2024), uma passkey é gerada automaticamente e será priorizada em preenchimentos futuros.

Para ter não apenas uma alta adoção, mas também um uso frequente do login com passkey, tente verificar se o dispositivo ou navegador pode usar a Conditional UI / Passkey Autofill consultando o conditionalGet. Dessa forma, você incentiva os usuários a usar a passkey criada para seus logins, já que ela é sugerida ativamente pelo sistema operacional ou navegador e exige ainda menos esforço do que preencher uma senha.

Utilize o hybridTransport para habilitar a autenticação entre dispositivos (via QR code e Bluetooth), permitindo que os usuários façam login de forma prática a partir de seus smartphones, mesmo se estiverem acessando o seu serviço em um desktop.

As capacidades do cliente WebAuthn representam um passo significativo para fechar as lacunas atuais no uso de passkeys. Neste artigo, abordamos as principais perguntas sobre elas:

1. O que são as capacidades do cliente WebAuthn? Explicamos como esses recursos permitem que navegadores e plataformas informem seu suporte a funcionalidades específicas, dando a nós desenvolvedores mais controle sobre os fluxos de autenticação.
2. Quais capacidades existem? Fornecemos uma visão geral dos novos recursos do padrão Nível 3, incluindo getClientCapabilities, conditionalCreate, hybridTransport e mais.
3. Como elas melhoram as implementações de passkeys? Discutimos como essas capacidades otimizam a integração, melhoram o uso entre dispositivos e aumentam a segurança.
4. Por que isso importa para os desenvolvedores? Esses recursos ajudam a criar experiências de autenticação contínuas e seguras que se alinham com as expectativas dos usuários modernos, tornando a implementação mais fácil e eficaz.

Incentivamos você a explorar os novos recursos do WebAuthn Nível 3 e a se manter atualizado sobre a adoção deles pelos navegadores. Se você estiver buscando implementar passkeys e aproveitar essas capacidades avançadas, entre em contato conosco para obter orientação especializada e suporte.

Sobre a Corbado

Corbado é a Passkey Intelligence Platform para times de CIAM que rodam autenticação consumer em escala. Mostramos o que logs de IDP e ferramentas genéricas de analytics não enxergam: quais dispositivos, versões de SO, navegadores e gerenciadores de credenciais suportam passkeys, por que os registros não viram logins, onde o fluxo WebAuthn falha e quando uma atualização de SO ou navegador quebra silenciosamente o login — tudo sem substituir Okta, Auth0, Ping, Cognito ou seu IDP interno. Dois produtos: Corbado Observe adiciona observabilidade para passkeys e qualquer outro método de login. Corbado Connect entrega passkeys gerenciados com analytics integrado (junto ao seu IDP). VicRoads roda passkeys para mais de 5M de usuários com Corbado (+80% de ativação de passkey). Fale com um especialista em Passkeys →