---
url: 'https://www.corbado.com/es/blog/hoja-trucos-claves-acceso'
title: 'Hoja de trucos de claves de acceso para desarrolladores'
description: 'La guía para desarrolladores sobre WebAuthn y la implementación de claves de acceso. Descargue la hoja de trucos en PDF o utilice este sitio web.'
lang: 'es'
author: 'Lukas R.'
date: '2026-07-03T07:12:54.402Z'
lastModified: '2026-07-03T07:12:54.402Z'
keywords: 'hoja de trucos, claves de acceso, WebAuthn, guía de desarrolladores, passkeys'
category: 'Passkeys Implementation'
---
# Hoja de trucos de claves de acceso para desarrolladores
## Descargar gratis aquí
Descargue la **hoja de trucos de claves de acceso completa de forma gratuita** y obtenga toda la información.
- ✅ +4.000 descargas ya
- ✅ Solicitado por equipos de desarrollo en Ally, Kmart, Octopus [Energy](https://www.corbado.com/passkeys-for-energy) y Stanford CS
- ✅ Sin relleno de marketing: solo información técnica
## Key Facts
- La autenticación con claves de acceso utiliza dos **ceremonias**: registro (atestación) e inicio de sesión (aserción), cada una requiriendo un desafío aleatorio generado por el servidor y firmado por el autenticador.
- **PublicKeyCredentialCreationOptions** rige el registro de la clave de acceso, mientras que **PublicKeyCredentialRequestOptions** rige el inicio de sesión. Ambos objetos se generan en el lado del servidor y contienen el desafío que debe firmar el autenticador.
- **Conditional UI** muestra las claves de acceso disponibles como sugerencias de autocompletado, pero requiere credenciales descubribles (claves residentes) y no es compatible con todas las combinaciones de sistemas operativos y navegadores.
- El **Relying Party ID (rpID)** vincula una clave de acceso a un dominio: la autenticación solo tiene éxito cuando la URL coincide o es un subdominio que no pertenece a un sufijo público del rpID.
- Las claves de acceso utilizan **algoritmos COSE** para la generación de claves, con el algoritmo específico registrado en el atributo parsedCredentialPublicKey del objeto de atestación.
## 1. Ceremonias de WebAuthn
La autenticación con claves de acceso se basa en los dos procesos, también llamados ceremonias, **registro** (también conocido como la **fase de atestación**) e **inicio de sesión** (también conocido como la **fase de aserción**).\
Cada fase requiere un desafío aleatorio generado por el servidor, que es firmado por el autenticador y enviado de vuelta al servidor WebAuthn para verificar al usuario.
### 1.1 Registro (Atestación)
_La ceremonia de registro utiliza dos objetos centrales: PublicKeyCredentialCreationOptions y atestación._
[Watch on YouTube](https://www.youtube.com/watch?v=0hRYXHESA24)
### 1.2 Inicio de sesión (Aserción)
_La ceremonia de inicio de sesión utiliza dos objetos centrales: PublicKeyCredentialRequestOptions y aserción._
## 2. Objetos importantes
Para el registro y el inicio de sesión con claves de acceso, hay cuatro objetos principales:
- PublicKeyCredentialCreationOptions
- PublicKeyCredentialRequestOptions
- atestación
- aserción
Esta sección también explica el objeto authenticatorSelection, que se utiliza en PublicKeyCredentialCreationOptions.
### 2.1 Public Key Credential Creation Options
PublicKeyCredentialCreationOptions es el objeto central de la fase de atestación (Registro). Es creado y devuelto por el [servidor WebAuthn](#webauthn-server).
```json
{
"PublicKeyCredentialCreationOptions": {
"rp": {
"id": "passkeys.eu",
"name": "Corbado Passkeys Demo"
},
"user": {
"displayName": "john.doe",
"id": "dXNyLZ….DU10Tc",
"name": "john@doe.com"
},
"challenge": "888fix4Bus...pHHr3Y",
"pubKeyCredParams": [
{
"alg": -7,
"type": "public-key"
},
{
"alg": -257,
"type": "public-key"
}
],
"excludeCredentials": [],
"authenticatorSelection": {
"authenticatorAttachment": "platform",
"residentKey": "required",
"userVerification": "required"
},
"attestation": "none",
"extensions": {}
}
}
```
El objeto contiene estos atributos:
- **rp:** Identifica el Relying Party (= el servidor que busca autenticar al usuario), consulte la sección [4.2 Relying Party ID (rpID).](#relying-party-id)
- **user:** Contiene datos sobre la cuenta de usuario que solicita la atestación. El ID es una secuencia de bytes elegida por el Relying Party, que no debe contener información personal. En su lugar, el nombre de usuario o la dirección de correo electrónico se guarda en el atributo name o displayName. Lea más sobre esto en la sección [4.1 Esquema de base de datos.](#database-schema)
- **challenge:** Un BufferSource codificado en base64URL generado aleatoriamente que debe ser firmado por el autenticador.
- **pubKeyCredParams:** Atributos especificados de la credencial a crear, generalmente el/los algoritmo(s) compatible(s).
- **timeout:** Tiempo opcional en milisegundos que el cliente debe esperar para que se complete la llamada.
- **excludeCredentials:** Lista opcional de credenciales para limitar la creación de múltiples claves de acceso en un dispositivo.
- **authenticatorSelection:** Selección opcional del autenticador utilizado para el método, por ejemplo, si se requiere un residentKey. Consulte [2.5 authenticatorSelection](#authenticatorSelection).
- **attestation:** Se puede utilizar para solicitar que el objeto de atestación se transmita al Relying Party en una forma específica. Los valores posibles son none (predeterminado), indirect, direct y enterprise.
- **extensions:** Solicitud(es) opcional(es) para procesamiento adicional, como valores de retorno específicos. Por ejemplo:
- _credProbs_ solicita información sobre si la credencial creada es descubrible
- _prf_ permite al Relying Party usar las salidas de una función pseudoaleatoria (PRF) asociada con una credencial
### 2.2 Public Key Credential Request Options
PublicKeyCredentialRequestOptions es el objeto central de la fase de aserción (Inicio de sesión). Es creado y devuelto por el [servidor WebAuthn](#webauthn-server).
```json
{
"publicKeyCredentialRequestOptions": {
"challenge": "pT7HMA-…dFPHk",
"timeout": 500,
"rpId": "passkeys.eu",
"userVerification": "preferred",
"allowCredentials": [],
"extensions": []
}
}
```
El objeto contiene estos atributos:
- **challenge, timeout, extensions:** consulte [arriba](#creationoptions).
- **rpId:** El identificador del Relying Party para la solicitud de aserción, consulte la sección [4.2 Relying Party ID (rpID).](#relying-party-id)
- **allowCredentials:** Lista opcional de credenciales que están permitidas para la autenticación, indicando la preferencia de las llamadas en orden descendente. Esta lista estaría llena de PublicKeyCredentialDescriptors.
- **userVerification:** Valor opcional para especificar los requisitos para la verificación del usuario durante la operación. Los valores posibles son preferred (predeterminado), required o discouraged.
### 2.3 Atestación
Durante la ceremonia de **atestación** / registro, el autenticador devuelve esta **respuesta de registro**. Puede probar esto usted mismo en el [Passkeys Debugger](https://www.passkeys-debugger.io/).
```json
{
"authenticatorAttachment": "platform",
"id": "JKZbixUfKN_aZtimefYT-OjH5dw",
"rawId": "JKZbixUfKN_aZtimefYT-OjH5dw",
"response": {
"attestationObject": {
"fmt": "none",
"attStmt": {},
"authData": {
"rpIdHash": "PpZrl-Wqt-OFfBpyy2SraN1m7LT0GZORwGA7-6ujYkM",
"flags": {
"userPresent": true,
"userVerified": true,
"backupEligible": true,
"backupStatus": true,
"attestedData": true,
"extensionData": false
},
"counter": 0,
"aaguid": {
"raw": "fbfc3007-154e-4ecc-8c0b-6e020557d7bd",
"name": "iCloud Keychain"
},
"credentialID": "JKZbixUfKN_aZtimefYT-OjH5dw",
"credentialPublicKey": "pQECAyYgASFYIPWLalDzyxIDmAADvfK8iNM5To50kh7TyPH-teEz8RMdIlgg3D7bPIWQJ8z-WFn3zdYZzJw9c7mhPdmflQqD9vV7efA",
"parsedCredentialPublicKey": {
"keyType": "EC2 (2)",
"algorithm": "ES256 (-7)",
"curve": 1,
"x": "9YtqUPPLEgOYAAO98ryI0zlOjnSSHtPI8f614TPxEx0",
"y": "3D7bPIWQJ8z-WFn3zdYZzJw9c7mhPdmflQqD9vV7efA"
}
}
},
"clientDataJSON": {
"type": "webauthn.create",
"challenge": "k2p6f-upzP_hc6NZvmMAxiI0VSTeQIeXXVRGW62LTj0",
"origin": "https://www.passkeys-debugger.io",
"crossOrigin": false
},
"transports": ["hybrid", "internal"],
"authenticatorData": "PpZrl-Wqt-OFfBpyy2SraN1m7LT0GZORwGA7-6ujYkNdAAAAAPv8MAcVTk7MjAtuAgVX170AFCSmW4sVHyjf2mbYpnn2E_jox-XcpQECAyYgASFYIPWLalDzyxIDmAADvfK8iNM5To50kh7TyPH-teEz8RMdIlgg3D7bPIWQJ8z-WFn3zdYZzJw9c7mhPdmflQqD9vV7efA",
"publicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE9YtqUPPLEgOYAAO98ryI0zlOjnSSHtPI8f614TPxEx3cPts8hZAnzP5YWffN1hnMnD1zuaE92Z-VCoP29Xt58A",
"publicKeyAlgorithm": -7
},
"type": "public-key",
"clientExtensionResults": {}
}
```
La **atestación** contiene algunos componentes importantes como [attestationObject](#attestationObject), [algorithm](#algorithm) y los indicadores de [transport](#transport).
#### 2.3.1 attestationObject
Tomado de la [especificación WebAuthn del W3C](https://www.w3.org/TR/webauthn-2/#attestation-object)
El **attestationObject** es un objeto codificado en CBOR, que contiene información sobre las credenciales recién creadas, la clave pública y otros datos relevantes:
- **fmt** generalmente se evalúa como "none" para claves de acceso
- **attStmt** está vacío para las claves de acceso y se llena para otros autenticadores, por ejemplo, la clave de seguridad de hardware
- **authData** es un búfer de valores que contiene los siguientes datos:
Lea más sobre las [extensiones](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API/WebAuthn_extensions).
#### algoritmo
Las claves de acceso se generan con **algoritmos COSE**, indicando el algoritmo utilizado en el **atributo de algoritmo** de parsedCredentialPublicKey en el [objeto de atestación](#attestation).\
Aquí hay una descripción general de los algoritmos COSE más relevantes:
#### 2.3.2 transport
La propiedad **transports** indica los mecanismos a través de los cuales un autenticador puede comunicarse con un cliente. Algunas combinaciones de valores comunes de muestra son:
- **"transports": \["internal","hybrid"]**: Las claves de acceso se pueden utilizar desde el autenticador de la plataforma (por ejemplo, Face ID, Touch ID, Windows Hello) o a través de la autenticación entre dispositivos (usando código QR y Bluetooth).
- **"transports": \["internal"]**: Las claves de acceso solo se pueden utilizar desde el autenticador de la plataforma (por ejemplo, Face ID, Touch ID, Windows Hello)
- **Ninguna propiedad "transports" establecida:** comportamiento predeterminado que no da indicaciones
### 2.4 Aserción
Durante la ceremonia de **aserción** / inicio de sesión, el autenticador devuelve esta **respuesta de inicio de sesión**. Puede probar esto usted mismo en el [Passkeys Debugger](https://www.passkeys-debugger.io/).
```json
{
"id": "JKZbixUfKN_aZtimefYT-OjH5dw",
"rawId": "JKZbixUfKN_aZtimefYT-OjH5dw",
"type": "public-key",
"authenticatorAttachment": "platform",
"response": {
"authenticatorData": {
"rpIdHash": "PpZrl-Wqt-OFfBpyy2SraN1m7LT0GZORwGA7-6ujYkM",
"flags": {
"userPresent": true,
"userVerified": true,
"backupEligible": true,
"backupStatus": true,
"attestedData": false,
"extensionData": false
},
"counter": 0
},
"clientDataJSON": {
"type": "webauthn.get",
"challenge": "GCVkITWbe2l2dttsn_DgJYvH9QPHPDo0ygWgcgI6B7U",
"origin": "https://www.passkeys-debugger.io",
"crossOrigin": false,
"other_keys_can_be_added_here": "do not compare clientDataJSON against a template. See https://goo.gl/yabPex"
},
"signature": "MEQCIA-orC8N2KKWOxyY17BWP8lB-Be5to9btXRnJZf2SLhXAiBGxJe5Eu5LwOTbsyzAYmIXHOhlC3pN7s7Q1fRLvEW57g",
"userHandle": "_FKz1uwqmR_3yGq6hJntzoIFwFC_d1u_53YRELh0KlE"
}
}
```
La **aserción** contiene algunos componentes importantes como indicadores, firma y userHandle.
#### 2.4.1 flags
Aquí hay una descripción general de los **indicadores** más relevantes y sus combinaciones:
#### 2.4.2 signature
La **firma** se utiliza para verificar que el usuario que intenta iniciar sesión realmente tiene la clave privada. La firma se crea concatenando el authenticatorData y el clientDataHash (es decir, la versión SHA-256 de ClientDataJSON) y firmando el resultado con la clave privada (en el autenticador). Para verificar con la clave pública, también concatenamos authenticatorData y clientDataHash. Si el resultado de la verificación devuelve verdadero, la autenticación es exitosa.
#### 2.4.3 userHandle
El **userHandle** es el user_id real. Lea más sobre el user_id en la sección [**4.1 Esquema de base de datos.**](#database-schema)
### 2.5 authenticatorSelection
El objeto **authenticatorSelection** permite al servidor dictar configuraciones para el autenticador y la creación de credenciales con los siguientes valores:
#### 2.5.1 authenticatorAttachment
- **Platform:** El autenticador está conectado a la plataforma del cliente y, por lo tanto, no es extraíble.
- **Cross-platform:** El autenticador no está vinculado a la plataforma del cliente y se puede usar en múltiples dispositivos.
#### 2.5.2 residentKey
- **Required:** El autenticador debe crear una clave residente (si no es posible, la operación debería fallar).
- **Preferred:** El autenticador debería intentar crear una clave residente (si no es posible, debería crear una clave no residente).
- **Discouraged:** El autenticador debe crear una clave no residente (si no es posible, la operación debería fallar).
> **Claves residentes (también llamadas credenciales descubribles):** Las claves residentes se almacenan en el autenticador y se recuperan durante la autenticación. De esta manera, el cliente puede descubrir una lista de claves posibles, que es la razón por la que Conditional UI requiere claves residentes.
> **Claves no residentes (también llamadas credenciales no descubribles):** En el caso de claves no residentes, el ID de la credencial se almacena en el servidor y se proporciona durante la autenticación. El ID de la credencial es un [identificador opaco](https://www.w3.org/TR/webauthn-3/#sctn-credential-id) cuya estructura interna es específica de la implementación: los autenticadores pueden almacenar claves privadas directamente, usar envoltura de claves encriptadas o derivar claves de secretos internos. El mecanismo exacto varía según la implementación del autenticador.
#### 2.5.3 userVerification
- **Required:** La operación debería verificar al usuario.
- **Preferred:** La operación debería verificar al usuario, pero puede continuar sin ella (opción estándar)
- **Discouraged:** La operación no debería verificar al usuario.
> **Advertencia:** Si se establece en "**Preferred**", el usuario o su dispositivo pueden omitir la verificación de usuario en el proceso de autenticación (lea más en este [artículo](https://web.dev/articles/passkey-form-autofill)).
## 3. Conditional UI
**Conditional UI** (autocompletado de claves de acceso) muestra las claves de acceso disponibles en un menú desplegable de selección para el usuario, cuando un usuario tiene una clave residente registrada en el relying party. Mejora la usabilidad de las claves de acceso, pero requiere esfuerzos de desarrollo adicionales y no está disponible para todas las combinaciones de sistemas operativos / navegadores.
### 3.1 Flujo de inicio de sesión con Conditional UI
_Al igual que un inicio de sesión regular, Conditional UI también utiliza los objetos PublicKeyCredentialRequestOptions y aserción_
### 3.2 Compatibilidad de dispositivos
Conditional UI no está disponible en todas las combinaciones de sistemas operativos y navegadores (todavía). Aquí hay una descripción general de la cobertura actual del navegador (marzo de 2024):
Para obtener una descripción general actualizada, consulte [este sitio web.](https://caniuse.com/mdn-api_publickeycredential_isconditionalmediationavailable_static)
### 3.3 Ejemplos de código
#### 3.3.1 Método Conditional UI
Un código minimalista completo para un método de Conditional UI se ve así:
```html
Conditional UI
```
#### 3.3.2 Verificación de compatibilidad del navegador
Conditional UI solo funciona con **claves residentes** / credenciales descubribles\
Se recomienda proporcionar un **punto final de servidor diferente** para iniciar el inicio de sesión de Conditional UI.\
El cliente debe cumplir con varios requisitos:
- El navegador debe ser compatible con Conditional UI (consulte [3.2 Compatibilidad de dispositivos](#device-compatibility)).
- JavaScript debe estar habilitado y la página web debe proporcionar un campo de entrada HTML.
- Los parámetros de tiempo de espera deben descartarse
Para evitar errores, el servidor debe probar primero la disponibilidad del cliente con esta función:
En tráfico real, los problemas de detección y ciclo de vida a menudo surgen como `NotAllowedError` o `AbortError`. Use esta guía de errores de WebAuthn para la clasificación de lo esperado frente a lo inesperado, incluidos los errores de claves de acceso nativas del administrador de credenciales.
```javascript
// fuente: https://developer.mozilla.org/en-US/docs/Web/API/PublicKeyCredential/isConditionalMediationAvailable#examples
// La disponibilidad de `window.PublicKeyCredential` significa que WebAuthn se puede usar.
if (window.PublicKeyCredential && PublicKeyCredential.isConditionalMediationAvailable) {
// Comprobar si la mediación condicional está disponible.
const isCMA = await PublicKeyCredential.isConditionalMediationAvailable();
if (isCMA) {
// Llamar al punto final de inicio de autenticación WebAuthn
let options = await WebAuthnClient.getPublicKeyRequestOptions();
const credential = await navigator.credentials.get({
publicKey: options.publicKeyCredentialRequestOptions,
mediation: "conditional",
});
/*
...
*/
}
}
```
#### 3.3.3 Token de autocompletado en campos de entrada
El campo de entrada debe recibir un token de autocompletado HTML que indique al cliente que popule las claves de acceso en la solicitud en curso. Además de las claves de acceso, los tokens de autocompletado se pueden emparejar con tokens existentes, por ejemplo, nombres de usuario y contraseñas:
- autocomplete="username webauthn": además de mostrar las claves de acceso, esto también sugiere el autocompletado del nombre de usuario.
- autocomplete="current-password webauthn": además de mostrar las claves de acceso, esto también solicita el autocompletado de la contraseña.
```html
```
## 4. Servidor WebAuthn
### 4.1 Esquema de base de datos
No existe un esquema de base de datos obligatorio o estandarizado para los servidores WebAuthn. Sin embargo, este esquema de base de datos de ejemplo se puede usar para almacenar la información requerida y proporcionar todas las funcionalidades de un servidor WebAuthn:
_Los atributos en negrita son obligatorios para una implementación viable mínima, mientras que los demás solo son necesarios para funciones opcionales pero útiles._
#### 4.1.1 Datos relevantes para la autenticación
- **Credential ID:** Este es un ID único que genera el autenticador durante el registro de una clave de acceso. Se debe usar para buscar la cuenta de usuario real que está asociada con la clave de acceso. Además, el userHandle (del user_id) debería compararse para validar la cuenta utilizada para la autenticación. No use el atributo user.name para la comparación, ya que puede cambiar con el tiempo.
- **User ID (user_id):** ID único especificado por el Relying Party para representar una cuenta de usuario en su sistema. Se devuelve como userHandle dentro del objeto de aserción.
#### 4.1.2 Metadatos para mostrar y seleccionar claves de acceso:
- **User DisplayName (user.displayName):** Nombre legible y amigable para el usuario que generalmente es el nombre completo del usuario. Se muestra al usuario, pero no se usa durante la autenticación.
- **User Name (user.name):** Nombre único y legible que generalmente es una dirección de correo electrónico o un nombre de usuario. Se puede mostrar al usuario, pero no se usa durante la autenticación.
### 4.2 Relying Party ID (rpId)
El **Relying Party ID (rpID)** es un dominio almacenado dentro de la clave de acceso, que garantiza que la clave de acceso solo funcione para el dominio correcto (URL del navegador, consulte este artículo para aplicaciones nativas). Durante la autenticación, el rpID se compara con la URL del navegador y solo se permite en estos dos casos:
1. La URL coincide exactamente con el rpId O
2. La URL es un subdominio que coincide con el rpId y el dominio principal no está en la Lista de Sufijos Públicos
Aquí hay ejemplos de combinaciones (no) permitidas:
## 5. Sitios web y herramientas útiles
Aquí hay una lista de herramientas y sitios web útiles para implementar claves de acceso.
- [**Passkeys Debugger:**](https://www.passkeys-debugger.io/) Herramienta para depurar las respuestas de WebAuthn como JSON y probar las operaciones de WebAuthn con diferentes opciones.
- [**Glosario de claves de acceso:**](https://www.corbado.com/glossary) Explicación de los términos y conceptos relacionados con las claves de acceso
- [**Especificación WebAuthn:**](https://www.w3.org/TR/webauthn-2/) Esta es la especificación oficial de WebAuthn.
- [**Registro de dispositivos de Chrome:**](http://chrome://device-log) Herramienta para mostrar un registro de las operaciones de WebAuthn de su dispositivo (solo disponible en Chrome a través de `chrome://device-log`)
Para conocer estrategias sobre cómo optimizar la experiencia del usuario (UX) de sus claves de acceso más allá de la implementación técnica, consulte nuestras guías sobre las mejores prácticas de creación de claves de acceso y las mejores prácticas de inicio de sesión con claves de acceso.
Si desea implementar claves de acceso con solo unas pocas líneas de código en cualquier aplicación, también puede usar [Corbado Complete](https://docs.corbado.com/start) (para nuevas aplicaciones) o [Corbado Connect](https://www.corbado.com/enterprise) (para aplicaciones existentes)
## Preguntas frecuentes
### ¿Cómo implemento Conditional UI para el autocompletado de claves de acceso en mi aplicación web?
Conditional UI requiere verificar el soporte del navegador mediante `PublicKeyCredential.isConditionalMediationAvailable()` antes de iniciar la autenticación. El campo de entrada debe incluir el token HTML `autocomplete="username webauthn"` y el usuario debe tener una clave residente (credencial descubrible) registrada. Se recomienda un endpoint de servidor separado para manejar el flujo de inicio de sesión de Conditional UI.
### ¿Cuál es la cantidad mínima de datos que necesito almacenar en mi base de datos para admitir la autenticación WebAuthn?
Como mínimo, almacene el Credential ID, generado por el autenticador durante el registro, y el User ID (user_id), que se devuelve como userHandle en el objeto de aserción. Utilice el Credential ID para buscar la cuenta de usuario asociada y compare el userHandle para validar la autenticación. Evite usar user.name para la comparación, ya que puede cambiar con el tiempo.
### ¿Cuál es la diferencia entre claves residentes y claves no residentes en WebAuthn?
Las claves residentes (credenciales descubribles) se almacenan en el propio autenticador y se recuperan durante la autenticación, lo cual es necesario para que funcione Conditional UI. Las claves no residentes almacenan el Credential ID en el servidor y lo envían al autenticador durante la autenticación. El campo residentKey en authenticatorSelection controla este comportamiento con los valores "required", "preferred" o "discouraged".
### ¿Cómo funciona userVerification y cuáles son los riesgos de establecerlo en preferred?
El campo userVerification controla si el autenticador debe verificar al usuario durante el inicio de sesión, aceptando los valores "required", "preferred" (predeterminado) o "discouraged". Cuando se establece en "preferred", el usuario o su dispositivo pueden omitir la verificación por completo durante el proceso de autenticación, lo que podría debilitar la seguridad. Establecerlo en "required" garantiza que la verificación siempre se realice antes de que se complete la autenticación.