Probando passkeys a través de un túnel: RP ID, orígenes y por qué las credenciales no te siguen desde localhost
Las passkeys creadas en localhost desaparecen tras un túnel. Aprende cómo funcionan RP ID y los orígenes de WebAuthn, y por qué un subdominio estable evita credenciales huérfanas.

Quick answer
Guía de RP ID y Orígenes para Passkeys a través de un Túnel: localhost tunnel answer
A localhost tunnel gives your local app a public HTTPS URL without opening router ports, which is useful for demos, QA, mobile testing, and provider callbacks.
How do I expose localhost without opening ports?
Use a reverse HTTPS tunnel. Your machine connects outbound to the tunnel service, and the public URL forwards requests back to your local app.
When should I use a localhost tunnel?
Use one for webhook testing, OAuth callbacks, client demos, QA previews, mobile device checks, and short-lived development reviews.
Construyes un flujo de passkeys en http://localhost:3000. El registro funciona, el inicio de sesión funciona, y ya te sientes listo. Luego abres un túnel para que un teléfono real pueda probarlo, y la pantalla de inicio de sesión no ofrece ningún passkey. No hay nada roto en el sentido habitual. El túnel está activo, el certificado es válido, el navegador está satisfecho. Tus credenciales simplemente están en otro lugar.
Los passkeys están ligados a un dominio, no a tu aplicación ni a tu portátil. Prueba a través de un túnel y el nombre de host del túnel se convierte en parte de tu credencial. Esta guía cubre las reglas, la configuración del backend y por qué un subdominio de túnel estable con nombre mantiene vivo el passkey de hoy para mañana.
La versión corta
- Un passkey pertenece a un único Relying Party ID (RP ID), que es un nombre de dominio.
localhosty el nombre de host del túnel son RP ID diferentes, por lo que sus credenciales nunca se cruzan. - El RP ID debe ser igual al nombre de host de la página o ser un dominio padre registrable del mismo. No puede ser un sufijo público como
com. - Tu servidor verifica el RP ID y el origen completo (esquema, host y puerto) por separado.
- Una URL de túnel aleatoria cambia ambos en cada ejecución, dejando huérfanas silenciosamente a todos los passkeys que registraste.
- Un subdominio de túnel estable y con nombre te proporciona un RP ID estable.
Qué es realmente un RP ID
Cada credencial WebAuthn se crea para un único RP ID, y cada solicitud se procesa en el contexto de uno. El explainer de Web Origin Related Requests del W3C lo describe esencialmente como un nombre de dominio. Un origen puede usar cualquier RP ID formado descartando cero o más etiquetas a la izquierda de su dominio efectivo, deteniéndose antes de un dominio de alto nivel efectivo. Así, una página en www.example.com puede usar www.example.com o example.com, pero no com.
A continuación, tres reglas prácticas:
- Regla de sufijo. El RP ID debe ser el dominio efectivo de la página o un sufijo de dominio registrable. Un RP ID que no sea un sufijo del origen actual hace que el navegador lance un
SecurityError. - Sin sufijos públicos. Los navegadores validan el RP ID contra la Public Suffix List, así que un sufijo simple como
comoco.ukes rechazado, mientras que un dominio real comoexample.comestá bien.localhostse acepta para desarrollo. - Contexto seguro. WebAuthn necesita HTTPS. La excepción de desarrollo cubre
localhosty direcciones de loopback, no una página HTTP simple en una dirección IP de LAN como192.168.1.42.
Un RP ID es una cadena de host simple. Incluir un esquema, puerto o ruta lo vuelve inválido: https://example.com, example.com:8443 y example.com/auth fallan, mientras que example.com es correcto.
Si dejas fuera rp.id de tus opciones, el navegador lo predetermina al dominio efectivo de la página que llama, que es el hostname completo. Ese valor por defecto es conveniente en localhost y peligrosamente silencioso en un túnel, porque la credencial queda restringida exactamente a ese host.
El estándar ya está asentado. El W3C publicó WebAuthn Level 3 como una Recomendación completa el 25 de agosto de 2026, sucediendo a Level 2 (abril de 2021), y el trabajo futuro se dirige a Level 4. Las reglas de RP ID anteriores no son nuevas en Level 3, así que nada en la promoción cambia la forma en que pruebas.
Por qué las credenciales de localhost no te siguen a un túnel
Una credencial creada mientras la página estaba en http://localhost:3000 se almacena bajo el RP ID localhost. Cuando abres https://my-app.tunnel.example y llamas a navigator.credentials.get(), el navegador busca credenciales cuyo RP ID coincida con my-app.tunnel.example (o un padre válido). No encuentra ninguna, así que el selector de passkeys aparece vacío o la llamada falla.
La guía de passkeys de Localtonet adopta la misma postura: trata las credenciales de localhost y las credenciales del hostname del túnel como entornos de prueba separados, y no esperes que una credencial registrada para localhost te autentique con un hostname del túnel. Ese es el modelo mental correcto. Un túnel no “reenvia” tu identidad de localhost. Le da a tu aplicación una nueva identidad pública, y WebAuthn la liga a esa identidad.
Dos otras cosas mantienen el estado antiguo. El autenticador (iCloud Keychain, Google Password Manager, Windows Hello, una llave de hardware) solo ofrece credenciales para el RP ID que coincide, y tu base de datos puede seguir teniendo claves públicas asociadas a un RP ID que ya no sirves.
Dos comprobaciones, dos lugares: RP ID y origen
Los fallos de passkey a través de un túnel a menudo se atribuyen a una incongruencia de origen cuando el problema real es el RP ID, o al revés. Se verifican en lugares distintos.
| Comprobación | Dónde ocurre | Qué debe coincidir |
|---|---|---|
| RP ID vs. nombre de host de la página | Navegador, antes de que empiece la ceremonia | rp.id es igual al hostname o a un padre registrable |
| hash de RP ID | Tu servidor, leyendo datos del authenticator | SHA-256 de tu RP ID configurado |
| Origen | Tu servidor, leyendo clientDataJSON |
Esquema exacto + host + puerto en tu lista de orígenes permitidos |
Las bibliotecas del servidor exponen estas como dos configuraciones. SimpleWebAuthn las llama rpID y expectedOrigin, py_webauthn usa rp.id y origin, y las bibliotecas de Java comúnmente usan relyingParty.id y origins. La guía de túneles de Corbado señala que la comparación de origen es sensible a mayúsculas y minúsculas e incluye el esquema, por lo que https://abc123.ngrok-free.app debe añadirse tal cual.
Para un túnel en https://pk-test.my-tunnel.dev, el RP ID es pk-test.my-tunnel.dev (sin esquema, puerto ni ruta) y el origen es https://pk-test.my-tunnel.dev. Poner https:// en el RP ID, o el nombre de host simple en la lista de orígenes, falla, y el error rara vez indica cuál.
El origen tampoco es la dirección a la que reenvía tu cliente de túnel. http://127.0.0.1:3000 es donde llega el tráfico, pero el origen público al que mira el navegador es lo que el servidor debe esperar. Si no estás seguro, ejecuta window.location.origin y window.location.hostname en la consola de la página tunelizada y copia esos valores en tu configuración.
La trampa de URL aleatoria
Aquí está el modo de fallo en su totalidad. Inicias un túnel que asigna un nombre de host aleatorio como crispy-fox-1234.example-tunnel.com. Registras un passkey. Mañana reinicias, y el host es quiet-owl-5678. Tu app es idéntica, pero el RP ID ha cambiado, así que ninguna de las credenciales de ayer aplica.
Lo que lo hace tan desagradable es la falta de una señal. El registro fue exitoso y la credencial existe en tu gestor de contraseñas y en tu base de datos. El inicio de sesión no muestra nada, o un NotAllowedError genérico, que los navegadores suelen mantener deliberadamente vago. También se acumulan huérfanos: los gestores de passkeys sincronizados conservan una entrada por cada nombre de host muerto hasta que las eliminas, y tu tabla credentials se llena con filas vinculadas a RP ID que ya no volverás a ver.
Qué tan común es esto depende de tu túnel:
- Cloudflare quick tunnels (
cloudflaredsin cuenta) te dan un nombre de host aleatorio tipo*.trycloudflare.comque dura hasta que detienes el proceso, y Cloudflare mismo los presenta como una forma de experimentar, sin garantía de tiempo de actividad. Un túnel named de Cloudflare necesita una cuenta gratuita y un dominio en Cloudflare DNS, y te da un nombre de host que eliges y que no cambia. - ngrok cambió esto a su favor. Cada cuenta, incluidas las gratuitas, obtiene un dominio de desarrollo asignado (por ejemplo
your-assigned-name.ngrok-free.dev) que es estático a lo largo de reinicios del agente y permanece con la cuenta. No puedes renombrarlo. Elegir tu propio subdominio requiere el plan Hobbyist de pago, y la generación aleatoria de dominios no está disponible en el plan gratuito. Los endpoints gratuitos no tienen límite de tiempo, y los endpoints HTTPS gratuitos muestran a los visitantes una página intersticial en la primera carga, lo que vale la pena conocer antes de darle un teléfono a un compañero de equipo. - Túneles con subdominio con nombre, InstaTunnel entre ellos, te permiten elegir el nombre de host en la línea de comandos. La documentación del paquete de InstaTunnel muestra
instatunnel 3000 --subdomain myappproduciendohttps://myapp.instatunnel.my, y sus materiales promocionan subdominios personalizados en el nivel gratuito.
El punto no es cuál proveedor gana. Es que las pruebas de passkeys necesitan un nombre de host que elijas y mantengas.
Elige un nombre y úsalo en todas partes
La solución es simple en la mejor forma: elige un nombre de host una vez, luego deriva tu RP ID y origen a partir de él.
Paso 1: Reclama un subdominio estable
instatunnel 3000 --subdomain pk-test
# https://pk-test.instatunnel.my
Con ngrok, usa en su lugar tu dominio de desarrollo asignado (mostrado bajo Dominios en el panel):
ngrok http 3000 --url https://<your-dev-domain>.ngrok-free.dev
Elige un nombre que suene a infraestructura de pruebas (pk-test, acme-passkeys-dev) para que nadie lo confunda con algo real.
Paso 2: Mantén la identidad en variables de entorno
# .env.tunnel
RP_ID=pk-test.instatunnel.my
RP_ORIGIN=https://pk-test.instatunnel.my
# .env.local
RP_ID=localhost
RP_ORIGIN=http://localhost:3000
No los construyas a partir de las cabeceras de la solicitud. Tu aplicación está detrás de un proxy, por lo que el Host y las cabeceras reenviadas que ve pueden no coincidir con lo que usa el navegador, y confiar en las cabeceras proporcionadas por el cliente X-Forwarded-* de todas las fuentes solo para silenciar un error de origen es un problema de seguridad por sí mismo. La configuración es la fuente de verdad, y las cabeceras no lo son.
Paso 3: Conecta la configuración en tu biblioteca WebAuthn
import { generateRegistrationOptions, verifyRegistrationResponse }
from '@simplewebauthn/server';
const rpID = process.env.RP_ID;
const origin = process.env.RP_ORIGIN;
const options = await generateRegistrationOptions({
rpName: 'Passkey Test App',
rpID,
userName: user.email,
});
// más tarde, en la respuesta:
const verification = await verifyRegistrationResponse({
response,
expectedChallenge,
expectedOrigin: origin,
expectedRPID: rpID,
});
Los nombres de parámetros difieren ligeramente entre versiones de la biblioteca, así que revisa la documentación de tu versión. El principio no cambia: un RP ID, un origen, ambos desde la configuración, y el mismo RP ID en las opciones de registro, verificación de registro, opciones de autenticación y verificación de aserciones.
Paso 4: Usa el nombre de host completo como el RP ID
Para pruebas de túnel, el nombre de host completo es el RP ID más seguro. La documentación de ngrok dice que sus dominios base gestionados (ngrok-free.app, ngrok-free.dev y otros) están en la Public Suffix List, por lo que el dominio base en sí nunca puede ser tu RP ID. El nombre de host completo siempre es válido y no puede ampliar el alcance de la credencial. Un RP ID de padre más amplio solo tiene sentido en un dominio personalizado que controles, cuando compartir credenciales entre subdominios es una elección de diseño deliberada.
Paso 5: Verifica la configuración alrededor de la ceremonia
Un túnel cambia más que el nombre de host. Antes de culpar a WebAuthn, confirma:
- Sin URLs hardcodeadas de localhost. Si la página se carga a través del túnel pero las llamadas API siguen apuntando a
localhost, la ceremonia falla por motivos que parecen errores de passkey. - Las cookies sobreviven al nuevo origen. Los desafíos están ligados a una sesión. Si la cookie de sesión no se envía en la solicitud de finalización (dominio incorrecto, ajustes
SecureoSameSite), verás un desajuste de desafío aunque el autenticador haya hecho su trabajo. - Verificaciones de host del servidor de desarrollo. Algunos servidores de desarrollo rechazan nombres de host desconocidos. Permite ese nombre de host del túnel en lugar de deshabilitar la verificación globalmente.
Mantén separados los entornos de localhost y del túnel
Como las dos identidades no pueden compartir credenciales, deja de suponer que podrían.
- Almacena el RP ID con cada credencial. Una columna
rp_idte permite purgar por entorno en lugar de adivinar qué filas están muertas. - Usa cuentas de prueba separadas para localhost y las ejecuciones del túnel, para que preguntas como “¿por qué este usuario no puede iniciar sesión?” tengan respuesta.
- Borra las passkeys de prueba antiguas de tu gestor de contraseñas cuando retires un hostname. WebAuthn Nivel 3 define una API de Señal (Signal API) que permite a un sitio indicar al proveedor de passkeys qué credenciales siguen siendo válidas, y Chrome y Edge la han implementado desde la versión 132 (enero de 2025). Pero la llamada solo funciona para el RP ID desde el que realmente se sirve la página, por lo que puede limpiar credenciales obsoletas en tu hostname actual del túnel, no en hostnames que ya no existan.
- Usa solo usuarios desechables. Si un subdominio de túnel puede ser reclamado por otra persona después de que lo elimines, no pongas cuentas reales detrás de él.
En el hostname actual, un inicio de sesión fallido para una credencial que tu servidor ya no conoce es el lugar natural para señalizar:
// credentialId: el ID base64url que el navegador acaba de presentar
if (PublicKeyCredential.signalUnknownCredential) {
await PublicKeyCredential.signalUnknownCredential({
rpId: process.env.RP_ID,
credentialId,
});
}
Siempre detecta la funcionalidad primero, porque el soporte varía según el navegador y la plataforma.
Cuando algo falla: una tabla de depuración
| Síntoma | Causa probable | Solución |
|---|---|---|
SecurityError en create() o get() |
rp.id no es el nombre de host de la página o un padre registrable de éste, o la página no es un contexto seguro |
Establece rp.id al nombre de host del túnel, o omítelo deliberadamente; usa la URL HTTPS |
| Selector de passkey vacío en el túnel | La credencial fue registrada bajo localhost o una URL de túnel anterior |
Registra de nuevo bajo el nombre de host actual |
NotAllowedError |
Prompt cancelado, timeout, o no hay un autenticador o credencial usable | Verifica la consola y el bloqueo de pantalla del dispositivo, y luego confirma que el RP ID coincide con el registro |
| El servidor indica origen inesperado | La lista de orígenes carece de la cadena exacta https://host |
Añade el origen completo, incluyendo el esquema |
| Desajuste de hash de RP ID en el servidor | El rpID del servidor difiere del que usó el navegador |
Haz que ambos lean de la misma variable de entorno |
| Funciona en escritorio, no en teléfono | El teléfono accedió a la app mediante HTTP sobre una IP de LAN | Usa la URL del túnel HTTPS en el teléfono |
| Desafío ausente o descoordinado | La cookie de sesión no se envía, o el desafío se almacena en un proceso y se verifica en otro | Corrige la configuración de cookies para el host público; usa una sesión compartida o caché |
| Aparece el prompt, pero el registro falla | La verificación del servidor (origen, hash del RP ID, desafío) lo rechazó | Lee el error estructurado de tu biblioteca, no solo el resultado del navegador |
Para qué sirve un túnel y qué no
Un túnel se gana su lugar para pruebas con dispositivos reales. La guía de ngrok de Corbado explica por qué las pruebas solo por Wi‑Fi fallan: un origin HTTP en una IP de LAN no es un contexto seguro, por lo que el navegador no ejecutará la ceremonia WebAuthn. Una URL pública HTTPS soluciona eso y te permite revisar autenticadores de plataforma en iOS, Android, Windows y macOS, desde un teléfono con datos móviles o un portátil en cualquier red.
Es la herramienta equivocada para automatización repetible. La pestaña WebAuthn de las DevTools de Chrome y el dominio WebAuthn del Chrome DevTools Protocol ofrecen autenticadores virtuales, y Selenium expone la misma idea a través de su API de Virtual Authenticator, que sigue el modelo de automatización WebAuthn del W3C. Playwright y Puppeteer pueden manejar el mismo dominio CDP. Permiten que CI registre y verifique passkeys de forma headless contra localhost, pero no pueden reproducir la UI de autenticador de plataforma, la sincronización del proveedor de passkeys ni las peculiaridades de dispositivos reales. Una división razonable: autenticadores virtuales en localhost para CI, y un nombre de host de túnel estable con autenticadores reales para la matriz de dispositivos.
Las Related Origin Requests no rescatan URLs aleatorias
Related Origin Requests (ROR) permiten que otros orígenes usen tu RP ID. El host del RP ID publica un archivo JSON en https://{RP ID}/.well-known/webauthn con un arreglo origins, y el navegador revisa esa lista antes de permitir una solicitud cuyo origin no coincida con el RP ID. Sin soporte de ROR, el navegador lanza un SecurityError.
El soporte se ha ampliado. Chrome (128) y Safari lo soportan, y Firefox lo añadió en la versión 152, lanzada el 16 de junio de 2026. Chrome limita la lista a cinco etiquetas distintas, donde una etiqueta es el nombre eTLD+1: example.co.uk y example.de cuentan como example, por lo que ocupan una ranura. Todos los sitios también deben compartir una base de datos de cuentas, ya que ROR solo permite que una credencial se autentique entre orígenes que ya comparten un directorio de usuarios.
Es tentador verlo como una forma de evitar cambiar las URL de túnel. No lo es: el archivo debe ser servido por el host del RP ID y listar cada origen, por lo que tendrías que editarlo cada vez que cambia un hostname aleatorio. Vale la pena probar ROR solo si tu diseño de producción lo usa, y entonces dos nombres de túnel estables (uno como host del RP ID y otro como origen relacionado) te permiten ensayar.
Preguntas frecuentes
¿Puedo usar una passkey registrada en localhost en mi URL de túnel?
No. El RP ID es localhost para la primera y el hostname del túnel para la segunda. Regístrala de nuevo bajo el hostname del túnel.
¿Puedo establecer el RP ID en el dominio base del proveedor del túnel?
Normalmente no. Si el dominio base está en la Public Suffix List, como lo están los dominios gestionados de ngrok, los navegadores lo rechazan. Usa el nombre de host completo.
¿Por qué mis passkeys desaparecieron tras reiniciar el túnel?
Si el túnel asignó un nuevo hostname aleatorio, tu RP ID cambió. Las credenciales antiguas aún existen, pero solo para el hostname antiguo.
¿Necesito una nueva credencial si renombro el subdominio de mi túnel?
Sí. Un nuevo hostname es un nuevo RP ID, así que registra una credencial de prueba nueva. Un RP ID no puede editarse en una credencial existente.
Conclusión
Las passkeys prueban aquello para lo que la mayoría de túneles no fueron diseñados a preservar: una identidad pública estable. Trata localhost y tu túnel como dos entornos separados, mantiene el RP ID y el origen en la configuración, y dale al túnel un hostname que no cambie. Así, la passkey que registres el lunes seguirá funcionando el viernes, y tus fallos apuntarán a errores reales en lugar de un hostname que cambió durante la noche.
Fuentes
- Alianza FIDO: WebAuthn Nivel 3 es ahora una recomendación de W3C
- W3C Web Authentication Nivel 3
- Explicador de WebAuthn de W3C: Related Origin Requests
- web.dev: Permitir reutilización de passkeys entre tus sitios con Related Origin Requests
- Notas de la versión de Firefox 152
- MojoAuth: Related Origin Requests across ccTLDs
- MojoAuth: Choosing Your RP ID
- Chrome for Developers: API de Señal de WebAuthn
- Corbado: Prueba de Passkeys desde Localhost con ngrok
- Localtonet: Prueba de passkeys WebAuthn a través de un túnel HTTPS de localhost
- Documentación de ngrok: Dominios
- Documentación de ngrok: Límites del plan gratuito
- Blog de ngrok: Dominios de desarrollo estáticos para todos los usuarios de ngrok
- Documentación de Cloudflare Sandbox: Quick vs. named tunnels
- Flavio Copes: La guía completa de Cloudflare Quick Tunnels
- Documentación de Selenium: Autenticador virtual
- README del paquete InstaTunnel
Related InstaTunnel pages
Continue from this article into the most relevant product guides and workflows.
Related Topics
Keep building with InstaTunnel
Read the docs for implementation details or compare plans before you ship.