Orientação sobre chaves de acesso

Recursos da Web: Autenticação da Web

Este guia oferece orientações práticas e detalhadas para implementar a autenticação por chave de acesso e o gerenciamento de credenciais de forma segura e independente de framework em aplicativos da Web modernos.

1. Pré-requisitos principais para chaves de acesso

As chaves de acesso dependem da API Web Authentication (WebAuthn), que impõe restrições de segurança transversais rigorosas que precisam ser atendidas antes de qualquer tentativa de implementação:

  • Contextos seguros: os métodos do WebAuthn (navigator.credentials.create e navigator.credentials.get) são estritamente controlados por contextos seguros. Os aplicativos PRECISAM ser executados em https:// na produção ou em http://localhost para desenvolvimento local.
  • ID da parte confiável (RP, na sigla em inglês): cada credencial está vinculada a um ID da RP (basicamente o nome de domínio do aplicativo). O ID da parte confiável transmitido nas opções do lado do servidor PRECISA corresponder ou ser um sufixo válido do nome de domínio da origem atual (por exemplo, example.com é válido para login.example.com). Incompatibilidades resultam em exceções SecurityError no lado do cliente.

2. A ressalva de UX do AAGUID

O identificador exclusivo global de atestado do autenticador (AAGUID, na sigla em inglês) é um identificador de 128 bits retornado nos dados de atestado de registro que representa o modelo/provedor do autenticador (por exemplo, Gerenciador de senhas do Google, Chaves do iCloud, 1Password).

  • Somente dicas de UX: as partes confiáveis PRECISAM usar o AAGUID exclusivamente para dicas de UX (como renderizar o nome e o ícone do provedor de chave de acesso em uma lista de gerenciamento para ajudar o usuário).
  • Sem dependências de segurança: os aplicativos NÃO PODEM usar o AAGUID para segurança criptográfica ou decisões de acesso. No momento, as chaves de acesso da plataforma não fornecem atestado criptográfico para os AAGUIDs, o que significa que eles podem ser alterados ou simulados por user agents.

3. Recomendações de bibliotecas separadas

Para a geração de opções de FIDO2/WebAuthn de back-end e a verificação de assinatura, os desenvolvedores PRECISAM usar bibliotecas de código aberto verificadas por idioma em vez de criptografia manual:

  • JavaScript/TypeScript: SimpleWebAuthn (github.com/MasterKale/SimpleWebAuthn)
  • Python: py_webauthn (github.com/duo-labs/py_webauthn)
  • Java: Java WebAuthn Server (github.com/Yubico/java-webauthn-server), WebAuthn4J (github.com/webauthn4j/webauthn4j)
  • .NET: biblioteca .NET para FIDO2 (github.com/abergs/fido2-net-lib)
  • Go: biblioteca WebAuthn Go (github.com/go-webauthn/webauthn)
  • Ruby: WebAuthn Ruby (github.com/cedarcode/webauthn-ruby)
  • PHP: WebAuthn Framework (github.com/web-auth/webauthn-framework)

4. Matriz de referência de casos de uso

Identifique o caso de uso correspondente abaixo e acesse o guia de implementação completo. Cada caso de uso tem APIs críticas (PublicKeyCredential.parseCreationOptionsFromJSON, parseRequestOptionsFromJSON, signalAllAcceptedCredentials, signalCurrentUserDetails, signalUnknownCredential, mediação condicional, processamento de AAGUID etc.) que são documentadas apenas no guia por caso de uso. NÃO pule essa etapa de recuperação e NÃO substitua wrappers de biblioteca de terceiros (como startAuthentication/startRegistration do SimpleWebAuthn) no cliente. Chame as APIs nativas do navegador WebAuthn diretamente. As recomendações de biblioteca na Seção 3 se aplicam apenas ao lado do servidor (verificação FIDO2 de back-end).

Os detalhes específicos de implementação de chaves de acesso e WebAuthn estão mapeados nos seguintes guias: