Orientación sobre las llaves de acceso

Funciones web: Autenticación web

Esta guía proporciona orientación de alta densidad y orientada a la acción para implementar la autenticación con llaves de acceso y la administración de credenciales seguras y sin importar el framework en aplicaciones web modernas.

1. Requisitos previos principales para las llaves de acceso

Las llaves de acceso se basan en la API de Web Authentication (WebAuthn), que impone restricciones de seguridad transversales estrictas que se deben cumplir antes de cualquier intento de implementación:

  • Contextos seguros: Los métodos de WebAuthn (navigator.credentials.create y navigator.credentials.get) están estrictamente restringidos a contextos seguros. Las aplicaciones DEBEN ejecutarse en https:// en producción o en http://localhost para el desarrollo local.
  • ID de la parte de confianza (RP): Cada credencial está vinculada a un ID de RP (básicamente, el nombre de dominio de la aplicación). El ID de RP que se pasa en las opciones del servidor DEBE coincidir con el nombre de dominio del origen actual o ser un sufijo válido de este (p.ej., example.com es válido para login.example.com). Las discrepancias generan excepciones de SecurityError en el cliente.

2. Advertencia sobre la UX de la AAGUID

El identificador único global de certificación del autenticador (AAGUID) es un identificador de 128 bits que se devuelve en los datos de certificación del registro y que representa el modelo o proveedor del autenticador (p.ej., el Administrador de contraseñas de Google, el llavero de iCloud o 1Password).

  • Solo sugerencias de UX: Las partes de confianza DEBEN usar el AAGUID exclusivamente para sugerencias de UX (como renderizar el nombre y el ícono del proveedor de llaves de acceso en una lista de administración para ayudar al usuario).
  • Sin dependencias de seguridad: Las aplicaciones NO DEBEN usar el AAGUID para tomar decisiones de seguridad criptográfica o de acceso. Actualmente, las llaves de acceso de la plataforma no proporcionan certificación criptográfica para sus AAGUID, lo que significa que los usuarios-agentes pueden alterarlas o simularlas.

3. Recomendaciones de bibliotecas independientes

Para la generación de opciones de FIDO2/WebAuthn de backend y la verificación de firmas, los desarrolladores DEBEN usar bibliotecas de código abierto verificadas por lenguaje en lugar de criptografía 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 de .NET para FIDO2 (github.com/abergs/fido2-net-lib)
  • Go: Biblioteca de WebAuthn para 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 referencia de casos de uso

Identifica el caso de uso correspondiente a continuación y obtén su guía de implementación completa. Cada caso de uso tiene APIs fundamentales (PublicKeyCredential.parseCreationOptionsFromJSON, parseRequestOptionsFromJSON, signalAllAcceptedCredentials, signalCurrentUserDetails, signalUnknownCredential, mediación condicional, control de AAGUID, etc.) que se documentan solo en la guía por caso de uso. NO omitas este paso de recuperación y NO sustituyas los wrappers de bibliotecas de terceros (como startAuthentication/startRegistration de SimpleWebAuthn) en el cliente. Llama directamente a las APIs nativas del navegador de WebAuthn. Las recomendaciones de bibliotecas de la sección 3 se aplican solo al lado del servidor (verificación de FIDO2 del backend).

Los detalles específicos de la implementación de llaves de acceso y WebAuthn se asignan a las siguientes guías: