Passkeys e WebAuthn em 2026: Um Guia Prático de Implementação para Desenvolvedores Web
Passkeys prometem login sem senha sem armazenar segredos de senha, mas implementar WebAuthn corretamente requer mais do que chamar uma API do navegador. Aprenda como registro, autenticação, verificação do lado do servidor, credenciais descobríveis e recuperação de conta se encaixam em uma aplicação web segura.
As senhas têm sido o mecanismo de autenticação padrão para aplicações web por décadas. Elas também são uma fonte persistente de problemas de segurança.
Os usuários as reutilizam. Ataqueiros as roubam por meio de phishing. Os servidores devem proteger hashes de senha, gerenciar redefinições e se defender contra ataques de credential stuffing.
As passkeys oferecem uma abordagem fundamentalmente diferente.
Em vez de pedir que os usuários lembrem um segredo compartilhado, as passkeys usam criptografia de chave pública e um autenticador controlado pelo usuário. O navegador fornece uma interface padrão por meio da WebAuthn, enquanto o servidor verifica a evidência criptográfica de que a credencial correta foi usada.
A tecnologia não é mais experimental. A WebAuthn está amplamente disponível em navegadores modernos, e seus métodos convenientes em JSON simplificaram consideravelmente a integração.
Mas construir um login seguro com passkeys ainda requer um design backend cuidadoso.
Este guia explica a arquitetura, demonstra os fluxos do lado do navegador e identifica as verificações do lado do servidor que os desenvolvedores não devem ignorar.
1. O que exatamente é um passkey?
Uma passkey é uma credencial FIDO descoberta, usada para autenticar um usuário por meio de criptografia de chave pública.
Durante o registro, um autenticador cria um par de chaves criptográficas.
A chave privada permanece protegida pelo autenticador ou por sua ecossistema de gerenciamento de credenciais. O site recebe a chave pública correspondente e a associa à conta do usuário.
Durante a autenticação, o servidor emite um novo desafio. O autenticador assina os dados associados a esse desafio, e o servidor verifica a assinatura usando a chave pública armazenada.
Não há uma senha reutilizável enviada para o site.
Um autenticador pode ser um smartphone, um computador usando Windows Hello, uma chave de segurança de hardware ou um gerenciador de credenciais que suporte passkeys sincronizados.
Nem todos os passkeys são sincronizados entre dispositivos. Algumas credenciais permanecem vinculadas ao dispositivo, enquanto outras podem ser armazenadas com segurança em backup e disponibilizadas por meio de um provedor de credenciais.
As especificações FIDO são projetadas para resistir a phishing vinculando credenciais ao domínio do relying party. Dados biométricos, quando usados, são tratados localmente pelo dispositivo em vez de serem enviados para o site.
2. WebAuthn é a API do navegador por trás dos passkeys
A WebAuthn é a API da plataforma web que permite que sites criem e usem credenciais de chave pública.
Dois métodos do navegador formam a base:
navigator.credentials.create()
navigator.credentials.get()
O primeiro cria uma credencial. O segundo solicita autenticação usando uma credencial existente.
Ambos os métodos funcionam com a opção publicKey e exigem um contexto seguro, normalmente HTTPS.
Importante: o navegador não decide se o usuário foi autenticado. Ele retorna dados que o backend deve verificar.
Uma mensagem de prompt do navegador bem-sucedida não é prova de que um login deve ser aceito.
O servidor permanece responsável por verificar o desafio, a origem, o identificador do relying party e a evidência criptográfica.
3. Entenda a arquitetura completa
Uma implementação típica contém quatro componentes:
- A web application frontend, que invoca a WebAuthn.
- O backend da aplicação, que gera desafios e verifica respostas.
- O autenticador ou provedor de passkeys, que protege a chave privada.
- O banco de dados, que armazena metadados de credenciais e chaves públicas.
O fluxo de registro é: a web application solicita opções de registro; o backend gera um desafio e dados do usuário; o navegador e o autenticador criam uma credencial e um par de chaves; e o backend verifica o resultado e armazena a chave pública.
O servidor nunca deve confiar nos dados de registro apenas porque foram retornados pelo navegador.
Um cliente malicioso pode enviar solicitações HTTP arbitrárias sem usar o frontend esperado.
É por isso que a verificação pertence ao servidor.
4. Gere opções de registro no servidor
Antes de chamar a WebAuthn, o backend gera um desafio e opções de registro.
Um objeto de opções representativo parece isto:
{
"rp": {
"name": "Example Application",
"id": "example.com"
},
"user": {
"id": "dXNlci0xMjM",
"name": "alex@example.com",
"displayName": "Alex"
},
"challenge": "SERVER_GENERATED_BASE64URL_CHALLENGE",
"pubKeyCredParams": [
{
"type": "public-key",
"alg": -7
}
],
"authenticatorSelection": {
"residentKey": "required",
"userVerification": "required"
},
"attestation": "none",
"timeout": 300000
}
Isto é JSON ilustrativo, não uma resposta completa de produção.
Vários campos importam.
rp.id identifica o relying party. Por exemplo, example.com pode ser usado para subdomínios apropriados daquele domínio, sujeito às regras de validação de RP ID da WebAuthn.
user.id deve ser um identificador estável e opaco de conta codificado em base64url para transporte em JSON. Ele não deve expor informações pessoais desnecessárias.
challenge deve ser gerado usando uma fonte de randomização criptografamente segura no servidor.
residentKey: "required" solicita uma credencial descoberta, o que é necessário para a experiência com passkey.
userVerification: "required" solicita verificação local do usuário, como um PIN do dispositivo ou autenticação biométrica. O backend deve verificar posteriormente se essa verificação realmente ocorreu.
O guia de registro do lado do servidor do Google descreve esses campos e recomenda o uso de uma biblioteca WebAuthn mantida para gerar e validar dados de registro.
5. Crie o passkey em JavaScript
Navegadores modernos fornecem um método útil:
PublicKeyCredential.parseCreationOptionsFromJSON()
Ele converte uma representação JSON que contém campos binários codificados em base64url para a estrutura esperada pela WebAuthn.
Isso evita escrever lógica personalizada de conversão de base64url para ArrayBuffer para cada campo.
Aqui está uma função de registro simplificada do lado do navegador:
async function registerPasskey() {
const optionsResponse = await fetch(
'/api/passkeys/register/options',
{
method: 'POST',
credentials: 'same-origin',
headers: {
'Content-Type': 'application/json',
'X-CSRF-Token': csrfToken
}
}
);
if (!optionsResponse.ok) {
throw new Error('Unable to start registration');
}
const optionsJson = await optionsResponse.json();
const publicKey =
PublicKeyCredential.parseCreationOptionsFromJSON(
optionsJson
);
const credential = await navigator.credentials.create({
publicKey
});
if (!credential) {
throw new Error('No credential was created');
}
const verifyResponse = await fetch(
'/api/passkeys/register/verify',
{
method: 'POST',
credentials: 'same-origin',
headers: {
'Content-Type': 'application/json',
'X-CSRF-Token': csrfToken
},
body: JSON.stringify(credential.toJSON())
}
);
if (!verifyResponse.ok) {
throw new Error('Registration verification failed');
}
return await verifyResponse.json();
}
A variável csrfToken representa um token anti-CSRF fornecido pela aplicação. O servidor deve validá-lo. O exemplo também assume que a página já está associada a um usuário autenticado com segurança.
O credential.toJSON() fornece uma representação em JSON do credencial retornado, evitando outra camada de serialização binária manual.
Essas conveniências estão disponíveis em navegadores atuais, embora aplicações que suportam versões mais antigas de navegadores ainda devam fornecer código de compatibilidade.
O código acima é apenas o lado do navegador. Ele não é uma implementação de autenticação completa.
6. O que o servidor deve verificar durante o registro
Quando o navegador retorna o novo credencial, o backend deve validá-lo antes de armazenar qualquer coisa.
Em mínimo, o processo de verificação deve estabelecer que:
- O desafio retornado corresponde ao gerado para esta tentativa de registro.
- O desafio é novo e não foi usado anteriormente.
- A origem informada corresponde a uma origem de aplicativo confiável explicitamente.
- Os dados do autenticador correspondem ao RP ID esperado.
- As condições exigidas de presença do usuário e verificação do usuário são satisfatórias.
- A chave pública e o identificador da credencial podem ser extraídos e validados.
- O registro está associado à conta autenticada correta.
Dependendo da política da aplicação, verificações adicionais podem incluir algoritmos suportados, unicidade de credenciais e requisitos de attestation.
Um registro bem-sucedido normalmente armazena:
| Campo | Propósito |
|---|---|
credential_id |
Identifica a credencial |
user_id |
Vincula-a a uma conta |
public_key |
Verifica assinaturas futuras |
sign_count |
Rastreia dados de contador do autenticador |
transports |
Dicas opcionais de transporte do autenticador |
created_at |
Carimbo de data e hora do registro |
last_used_at |
Gerenciamento da conta e auditoria |
backup_eligible / backup_state |
Metadados opcionais relacionados a backup |
A representação exata do banco de dados depende da biblioteca de verificação.
Não implemente parsing de CBOR, verificação de attestation ou validação de assinatura criptográfica do zero, a menos que tenha uma razão convincente e a expertise para mantê-la.
A especificação W3C define procedimentos detalhados de registro e verificação de autenticação.
7. Autentique um usuário existente
A autenticação segue uma estrutura semelhante, mas não cria um novo par de chaves.
O servidor gera um novo desafio e envia opções de autenticação para o navegador.
Para um login com passkey descoberta, essas opções podem conter:
{
"challenge": "NEW_SERVER_GENERATED_CHALLENGE",
"rpId": "example.com",
"userVerification": "required",
"timeout": 300000
}
O navegador pode então solicitar uma credencial:
async function authenticateWithPasskey() {
const optionsResponse = await fetch(
'/api/passkeys/login/options',
{
credentials: 'same-origin'
}
);
if (!optionsResponse.ok) {
throw new Error('Unable to start authentication');
}
const optionsJson = await optionsResponse.json();
const publicKey =
PublicKeyCredential.parseRequestOptionsFromJSON(
optionsJson
);
const credential = await navigator.credentials.get({
publicKey
});
if (!credential) {
throw new Error('Authentication was cancelled');
}
const verifyResponse = await fetch(
'/api/passkeys/login/verify',
{
method: 'POST',
credentials: 'same-origin',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify(credential.toJSON())
}
);
if (!verifyResponse.ok) {
throw new Error('Authentication failed');
}
return await verifyResponse.json();
}
Este exemplo assume que o backend associa o desafio emitido a uma transação de login anônima de curta duração, aplica rate limiting apropriado e estabelece uma nova sessão autenticada apenas após verificação bem-sucedida.
O servidor deve consultar o identificador da credencial, verificar a assinatura assinada com a chave pública armazenada, confirmar o desafio e a origem e impor sua política de verificação do usuário.
Somente então deveria estabelecer a sessão do usuário.
O parseRequestOptionsFromJSON() faz parte da API moderna da WebAuthn e remove a necessidade de decodificar manualmente campos binários em integrações comuns do lado do navegador.
8. Adicione passkeys a formulários de login existentes com mediação condicional
Uma das funcionalidades mais úteis da WebAuthn é a mediação condicional, às vezes chamada de preenchimento automático de passkey.
Em vez de mostrar imediatamente um diálogo separado para passkey, o navegador pode oferecer um passkey disponível junto com outras credenciais salvas quando o usuário interage com um campo de login.
A entrada HTML pode usar:
<input
type="text"
name="username"
autocomplete="username webauthn"
>
O aplicativo pode verificar o suporte:
const supported =
await PublicKeyCredential.isConditionalMediationAvailable();
if (supported) {
// Request authentication with mediation: 'conditional'.
}
Ao chamar o navigator.credentials.get(), o aplicativo usa:
{
publicKey,
mediation: 'conditional'
}
Para o preenchimento automático de credenciais descobertas, as opções do servidor não devem restringir o pedido a uma lista específica de identificadores de credenciais.
A mediação condicional é especialmente útil durante uma migração gradual de senhas porque os usuários não precisam lembrar se uma determinada conta tem uma passkey.
O navegador pode apresentar opções apropriadas na experiência familiar de login.
9. Por que as verificações de desafio e origem são essenciais
As passkeys são resistentes a phishing, mas isso não significa que uma aplicação possa ignorar seu protocolo de autenticação.
O desafio protege contra ataques de replay.
Sem um desafio novo e imprevisível, um atacante pode tentar reutilizar dados de autenticação de uma sessão anterior.
As verificações de origem e RP ID garantem que as credenciais estejam sendo usadas no contexto pretendido do site.
Por exemplo, uma passkey criada para example.com não pode simplesmente ser reutilizada por um site de phishing semelhante, como examp1e.com.
O navegador e o autenticador aplicam partes importantes dessa vinculação de domínio, enquanto o backend valida independentemente a evidência resultante.
Uma boa implementação usa desafios de curta duração, consome cada desafio uma vez e nunca aceita origens arbitrárias apenas porque compartilham um hostname com aparência familiar.
O MDN recomenda gerar desafios em um ambiente confiável e invalidá-los após um curto período, geralmente não mais que cerca de dez minutos.
10. Não interprete incorretamente os contadores de assinatura
Autenticadores WebAuthn podem incluir um contador de assinatura.
Historicamente, os contadores ajudaram a detectar autenticadores potencialmente clonados.
No entanto, nem todo autenticador mantém um contador significativo.
Algumas credenciais sempre relatam zero. Credenciais sincronizadas também podem complicar a interpretação do contador porque vários dispositivos podem usar cópias da mesma credencial.
A especificação W3C trata explicitamente o comportamento inesperado do contador como um possível sinal, não como prova definitiva de clonagem.
Portanto, os desenvolvedores não devem rejeitar cegamente um login cujo contador seja zero ou não tenha mudado.
Use o contador de acordo com o comportamento do autenticador, as orientações da biblioteca de verificação WebAuthn e a política de segurança da aplicação.
11. A recuperação de conta faz parte da segurança com passkeys
Uma implementação de passkey está incompleta sem uma estratégia de recuperação.
O que acontece quando um usuário perde um dispositivo?
O que se ele deletar seu único passkey?
O que se ele alterar os provedores de credenciais ou não conseguir acessar uma credencial sincronizada?
Um design sensato permite que os usuários registrem várias passkeys e as gerenciem em suas configurações de conta.
A interface de gerenciamento deve exibir nomes de credenciais reconhecíveis, datas de criação e informações recentes de uso quando disponíveis.
Os usuários devem ser capazes de revogar credenciais de que não confiam mais.
Mas o mecanismo de recuperação merece cuidado particular.
Se um atacante pode contornar a autenticação com passkeys por meio de um processo de recuperação fraco, a conta no geral só é tão segura quanto esse caminho de recuperação.
Para contas de maior risco, considere verificações de recuperação mais fortes, códigos de recuperação, autenticadores adicionais registrados e notificações sobre mudanças sensíveis na conta.
A orientação de UX do Google sobre passkeys recomenda estabelecer um método de recuperação e suportar várias passkeys quando apropriado.
12. Erros comuns de implementação
Vários erros minam repetidamente integrações com passkeys promissoras.
Tratar o sucesso do navegador como autenticação do servidor. Uma promessa navigator.credentials.get() resolvida não substitui a verificação criptográfica do lado do servidor.
Gerar desafios em JavaScript. Os desafios devem vir de um servidor confiável e estar vinculados à transação de autenticação apropriada.
Usar o RP ID incorreto. A delimitação de domínio é um recurso de segurança, não uma configuração cosmética. Ambientes de produção, staging e desenvolvimento local exigem configuração deliberada.
Assumir que todos os passkeys sincronizam. Credenciais vinculadas ao dispositivo permanecem uma parte importante do ecossistema.
Esquecer a revogação de credenciais. Os usuários precisam de uma maneira de remover um autenticador perdido ou comprometido da conta.
Criar um fallback fraco. Um login resistente a phishing perde muito do valor se a recuperação de conta puder ser explorada facilmente.
Ignorar navegadores antigos. Os métodos convenientes em JSON modernos reduzem a complexidade, mas aplicações com requisitos de navegadores mais antigos podem ainda precisar de código de compatibilidade.
Pular a proteção CSRF e de sessão. Operações de registro e gerenciamento de credenciais são alterações sensíveis à conta. Elas precisam das mesmas proteções de outras ações de conta de alto impacto.
Escrever verificação criptográfica personalizada desnecessariamente. Uma biblioteca de servidor WebAuthn mantida é geralmente uma escolha mais segura do que implementar a especificação diretamente.
13. Todo site deve substituir senhas imediatamente?
Nem necessariamente.
As passkeys podem melhorar tanto a usabilidade quanto a segurança, mas a estratégia de migração importa.
Para um novo aplicativo, o registro sem senha pode ser um padrão razoável se o produto tiver um fluxo de recuperação bem projetado e suportar suas plataformas de destino.
Para um aplicativo existente com milhares de usuários, a adoção incremental é muitas vezes mais segura.
Comece permitindo que usuários autenticados registrem passkeys em suas configurações de conta.
Então adicione o login com passkey ao lado do sistema de autenticação existente.
Introduza mediação condicional onde suportada.
Meça o sucesso do registro, falhas de autenticação, compatibilidade de dispositivos e solicitações de recuperação.
Finalmente, considere tornar as passkeys o método de autenticação preferido uma vez que a experiência do usuário e os mecanismos de recuperação sejam suficientemente maduros.
Um lançamento faseado também facilita a identificação de problemas específicos de navegadores sem bloquear usuários legítimos.
14. Checklist de prontidão para produção
Antes de habilitar as passkeys em produção, verifique o seguinte:
- Todas as operações WebAuthn ocorrem em um contexto seguro apropriado.
- Os RP IDs e origens confiáveis são configurados explicitamente.
- Os desafios são aleatórios criptograficamente, de curta duração e de uso único.
- O registro requer autorização de conta apropriada.
- A verificação do lado do servidor segue a especificação WebAuthn.
- As chaves públicas e identificadores de credenciais são armazenados com segurança.
- O login estabelece uma sessão somente após verificação bem-sucedida.
- As exigências de verificação do usuário são impostas no servidor.
- A remoção de credenciais e a recuperação de conta são protegidas.
- Várias credenciais por conta são suportadas quando apropriado.
- Falhas de autenticação e mudanças sensíveis à segurança da conta são monitoradas.
- Cenários mobile, desktop, cross-device e hardware-key são testados.
Essas verificações importam mais do que se a interface pode exibir um prompt biométrico atraente.
Conclusão: passkeys são uma arquitetura de autenticação, não apenas um recurso do navegador
A WebAuthn torna a autenticação com chave pública acessível para aplicações web comuns.
As APIs modernas do navegador removeram boa parte do trabalho de serialização que anteriormente tornava a integração com passkeys trabalhha.
Mas o navegador é apenas uma parte do sistema.
O trabalho real de implementação está na gestão de desafios, verificação do lado do servidor, armazenamento de credenciais, configuração de domínio, recuperação de conta e jornadas seguras do usuário.
Para desenvolvedores que constroem aplicações modernas em PHP, JavaScript, Python ou outros ambientes backend, as passkeys são cada vez mais motivo para considerar uma alternativa prática aos senhas tradicionais.
O melhor ponto de partida não é substituir um sistema de autenticação inteiro.
É implementar um fluxo completo de registro e login, corretamente verificado, e depois construir uma estratégia de migração segura em torno dele.