O registro de passkey WebAuthn vincula credenciais à conta autenticada com opções de cerimônia descobrível, desafios limitados e caminhos de recuperação que não prometem extração da chave privada.
Status do pacote: Pacote de referência assistido por IA. A validação estática do pacote foi aprovada; cenários de implementação ainda não foram executados e revisão humana do domínio é necessária antes da adoção estável.
Decisão
Oferecer passkeys por meio de cerimônias WebAuthn alinhadas a padrões após autenticação primária, armazenar apenas material de credencial pública no servidor, impor expiração de desafios, tratar contadores de autenticadores como sinais de risco quando disponíveis e lidar com recuperação reestabelecendo confiança — não exportando chaves privadas.
Escopo
- Cerimônias de registro e autenticação para clientes de navegador contra um ID de relying party.
- Estados do ciclo de vida da credencial, revogação, tratamento de duplicatas e login com credenciais descobríveis.
- Prompt de inscrição para o usuário, rotulagem de passkeys sincronizadas e texto honesto para recuperação.
- Limites de taxa e sinais de auditoria para cerimônias falhas.
Fora deste bloco
- Hashing de senha, mecânica de cookie de sessão ou federação OAuth (veja blocos relacionados de sessão).
- Política de atestação empresarial além da escolha de
attestationdo perfil. - Provisionamento de módulo de segurança de hardware ou firmware personalizado de autenticador.
Contrato
- Desafios de registro são emitidos apenas para uma sessão já autenticada, a menos que um fluxo de recuperação documentado eleve explicitamente a confiança primeiro.
- Desafios expiram após o TTL do perfil; desafios expirados nunca criam credenciais.
- Credenciais armazenadas registram ID da credencial, chave pública, contagem de assinaturas, transportes e estado de backup; chaves privadas nunca tocam o armazenamento do servidor.
- Autenticação bem-sucedida registra o contador do autenticador quando suportado. Um contador diferente de zero que não aumenta é um possível sinal de clonagem tratado pela política de risco do perfil; autenticadores que reportam zero não são rejeitados apenas por não possuírem um contador utilizável.
- Registro duplicado com o mesmo ID de credencial é idempotente e não cria uma segunda linha ativa.
- Recuperação sem passkey usa o caminho do perfil (por exemplo, email mais MFA ou códigos de backup) e pode registrar uma nova passkey posteriormente; o texto não deve implicar que segredos de passkey podem ser baixados ou enviados por email.
- Recuperação registra um motivo. Um caminho de dispositivo perdido pode reter outras credenciais sob a política do perfil; suspeita de comprometimento segue um caminho separado que congela ou revoga credenciais afetadas e, por padrão, revoga todas as passkeys anteriores antes de nova inscrição.
- Quando é necessário step-up para adicionar uma passkey, a verificação do usuário deve ser bem-sucedida ou a credencial é descartada.
- Credenciais revogadas falham na autenticação imediatamente, mesmo que o cliente ainda possua o material da chave privada localmente.
Orientações de implementação
- Siga os formatos de cerimônia do W3C WebAuthn Level 3; prefira
residentKey: preferredquando login descobrível for desejado. - Alinhe
rpIdcom o domínio registrável efetivo; documente explicitamente quaisquer exceções de subdomínio. - Apresente orientações alinhadas ao FIDO de que passkeys sincronizadas dependem de provedores de plataforma, não de segredos exportáveis por aplicativos.
- Mantenha o tratamento de anomalias de contador separado da verificação de asserção. A resposta pode exigir step-up, suspender a credencial ou abrir revisão conforme o perfil de ameaça, mas não deve afirmar que todo contador inalterado prova replay.
- Mapeie estados em
passkey-states.yamlpara eventos de observabilidade para ferramentas de suporte.
Tratamento de falhas e salvaguardas
- Em falha de verificação, não vaze se um ID de credencial existe; use erros genéricos na camada de UI com códigos detalhados nos logs.
- Em cancelamento do autenticador, retorne um erro recuperável ao cliente sem contar como falha no servidor.
- Não agrupe perda e comprometimento em um único interruptor de recuperação. Um evento apenas de perda pode reter credenciais mantidas independentemente, enquanto suspeita de comprometimento de conta ou autenticador revoga por padrão todas as passkeys e sessões anteriores definidas pelo perfil do incidente.
- Limite a taxa de tentativas de registro por conta e IP para desacelerar enumeração e assédio.
Verificação e operações
- Monitore sucesso da cerimônia, expiração, anomalias de contador, respostas de política e inscrições de recuperação.
- Execute testes de conformidade contra um autenticador virtual em CI para caminho feliz e expiração de TTL.
- Revise o texto da UX trimestralmente para que não prometa demais a recuperação de segredos de passkey.
Suposições de adoção
- Nomes e valores numéricos em
example.yamlsão um perfil de adoção, não padrões universais. - Equipes devem escolher políticas de atestação, UV e recuperação apropriadas ao seu modelo de ameaça.