Tester les passkeys via un tunnel : RP ID, origines et pourquoi les identifiants ne vous suivent pas depuis localhost
Les passkeys créés sur localhost disparaissent derrière un tunnel. Découvrez comment le RP ID et les origines de WebAuthn fonctionnent, et pourquoi un sous-domaine stable empêche les identifiants orphelins.

Quick answer
Test des passkeys via un tunnel : guide RP ID et Origine: 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.
Vous concevez un flux de passkeys sur http://localhost:3000. L’inscription et la connexion fonctionnent, et vous vous sentez prêt. Puis vous ouvrez un tunnel pour qu’un vrai téléphone puisse l’essayer, et l’écran de connexion n’offre aucun passkey. Rien n’est cassé au sens habituel. Le tunnel est actif, le certificat est valide, le navigateur est satisfait. Vos identifiants vivent tout simplement ailleurs.
Les passkeys sont liées à un domaine, pas à votre application ni à votre ordinateur portable. Testez via un tunnel et le nom d’hôte du tunnel devient une partie de votre identifiant. Ce guide couvre les règles, la configuration côté serveur et pourquoi un sous-domaine tunnel stable permet de garder vivants les passkeys d’aujourd’hui pour demain.
Version courte
- Un passkey appartient à un seul RP ID, qui est un nom de domaine.
localhostet le nom d’hôte du tunnel sont des RP ID différents, leurs identifiants ne se croisent jamais. - Le RP ID doit être identique au nom d’hôte de la page ou être un suffixe de domaine parent enregistrable. Il ne peut pas s’agir d’un suffixe public tel que
com. - Votre serveur vérifie le RP ID et l’origine complète (schéma, hôte et port) séparément.
- Une URL de tunnel aléatoire change les deux à chaque exécution, laissant silencieusement orphelins tous les passkeys que vous avez enregistrés.
- Un sous-domaine tunnel stable et nommé vous donne un RP ID stable.
Ce qu’est réellement un RP ID
Chaque credential WebAuthn est créé pour un seul RP ID, et chaque requête est traitée dans le contexte de celui-ci. L’explainer des Related Origin Requests du W3C le décrit essentiellement comme un nom de domaine. Une origine peut utiliser n’importe quel RP ID formé en supprimant zéro ou plusieurs étiquettes à partir de la gauche de son domaine effectif, en s’arrêtant avant un domaine de premier niveau effectif. Ainsi, une page sur www.example.com peut utiliser www.example.com ou example.com, mais pas com.
Trois règles pratiques suivent:
- Suffix rule. Le RP ID doit être le domaine effectif de la page ou un suffixe de domaine enregistrable. Un RP ID qui n’est pas un suffixe de l’origine actuelle entraîne une
SecurityErrordu navigateur. - Pas de suffixes publics. Les navigateurs valident le RP ID par rapport à la Public Suffix List, donc un suffixe nu comme
comouco.ukest rejeté, tandis qu’un vrai domaine commeexample.comest acceptable.localhostest accepté pour le développement. - Contexte sécurisé. WebAuthn nécessite HTTPS. L’exception de développement couvre
localhostet les adresses de loopback, pas une page HTTP simple sur une adresse IP LAN comme192.168.1.42.
Un RP ID est une chaîne d’hôte nue. Inclure un schéma, un port ou un chemin le rend invalide : https://example.com, example.com:8443 et example.com/auth échouent tous, tandis que example.com est correct.
Si vous laissez rp.id de côté, le navigateur le définit par défaut sur le domaine effectif de la page appelante, qui est le nom d’hôte complet. Cette valeur par défaut est pratique sur localhost et dangereuse discrètement sur un tunnel, car le credential est alors limité à exactement cet hôte.
La norme est établie. Le W3C a publié WebAuthn Niveau 3 en tant que recommandation complète le 25 août 2026, succédant au Niveau 2 (avril 2021), avec des évolutions futures vers le Niveau 4. Les règles RP ID ci-dessus ne sont pas nouvelles au Niveau 3, donc rien dans cette progression ne change votre méthode de test.
Pourquoi les identifiants localhost ne vous suivent pas dans un tunnel
Un credential créé lorsque la page était http://localhost:3000 est enregistré sous le RP ID localhost. Lorsque vous ouvrez https://my-app.tunnel.example et appelez navigator.credentials.get(), le navigateur recherche des identifiants dont le RP ID correspond à my-app.tunnel.example (ou un parent valide). Il n’en trouve aucun, donc le sélecteur de passkeys se vide ou l’appel échoue.
Le guide passkeys de Localtonet adopte la même position : traitez les identifiants localhost et les identifiants basés sur le nom d’hôte du tunnel comme des environnements de test séparés, et n’attendez pas qu’un identifiant enregistré pour localhost s’authentifie sous un nom d’hôte de tunnel. C’est le bon modèle mental. Un tunnel ne transmet pas votre identité locale. Il donne à votre application une nouvelle identité publique, et WebAuthn authentifie tout à cette identité.
Deux autres éléments maintiennent l’ancien état. L’authenticator (iCloud Keychain, Google Password Manager, Windows Hello, une clé matérielle) ne propose des identifiants que pour le RP ID correspondant, et votre base de données peut encore contenir des clés publiques associées à un RP ID que vous ne servez plus.
Deux vérifications, deux lieux : RP ID et Origine
Les échecs de passkeys via un tunnel sont souvent attribués à un « décalage d’origine » alors que le problème réel est le RP ID, ou l’inverse. Ils sont vérifiés à différents endroits.
| Vérification | Lieu d’exécution | Ce qui doit correspondre |
|---|---|---|
| RP ID vs. nom d’hôte de la page | Navigateur, avant le début de la cérémonie | rp.id égal au nom d’hôte ou à un parent enregistrable |
| Hachage du RP ID | Votre serveur, en lisant les données d’authentificateur | SHA-256 du RP ID configuré |
| Origine | Votre serveur, en lisant clientDataJSON |
Schéma exact + hôte + port dans votre liste d’origins autorisés |
Les bibliothèques côté serveur exposent cela comme deux réglages. SimpleWebAuthn les appelle rpID et expectedOrigin, py_webauthn utilise rp.id et origin, et les bibliothèques Java utilisent couramment relyingParty.id et origins. Le guide tunnel de Corbado note que la comparaison de l’origine est sensible à la casse et inclut le schéma, donc https://abc123.ngrok-free.app doit être ajoutée tel quel.
Pour un tunnel à https://pk-test.my-tunnel.dev, le RP ID est pk-test.my-tunnel.dev (sans schéma, port ou chemin) et l’origine est https://pk-test.my-tunnel.dev. Mettre https:// dans le RP ID, ou le nom d’hôte nu dans la liste des origines, échoue, et l’erreur indique rarement laquelle.
L’origine n’est pas non plus l’adresse vers laquelle votre client de tunnel transfère le trafic. http://127.0.0.1:3000 est l’endroit où le trafic se termine, mais l’origine publique côté navigateur que le serveur doit attendre. Si vous n’êtes pas sûr, exécutez window.location.origin et window.location.hostname dans la console de la page tunnelisée et copiez ces valeurs dans votre configuration.
Le piège de l’URL aléatoire
Voici le mode d’échec en entier. Vous démarrez un tunnel qui attribue un nom d’hôte aléatoire tel que crispy-fox-1234.example-tunnel.com. Vous enregistrez un passkey. Demain, vous redémarrez, et le nom d’hôte est quiet-owl-5678. Votre application est identique, mais le RP ID a changé, donc aucun des identifiants d’hier ne s’applique.
Ce qui rend cela pénible, c’est l’absence de signal. L’inscription a réussi, et l’identifiant existe dans votre gestionnaire de mots de passe et votre base de données. La connexion ne montre rien, ou une erreur générique NotAllowedError, que les navigateurs gardent volontairement vague. Les orphelins s’accumulent aussi : les gestionnaires de passkeys synchronisés conservent une entrée par nom d’hôte mort jusqu’à ce que vous les supprimiez, et votre table credentials se remplit de lignes liées à des RP IDs que vous ne reverrez jamais.
La fréquence dépend de votre tunnel :
- Cloudflare quick tunnels (
cloudflaredsans compte) vous donnent un nom d’hôte aléatoire*.trycloudflare.comqui dure tant que vous ne stoppez pas le processus, et Cloudflare les présente comme un moyen d’expérimentation, sans garantie de disponibilité. Un tunnel Cloudflare nommé nécessite un compte gratuit et un domaine sur Cloudflare DNS, et vous donne un nom d’hôte que vous choisissez qui ne change pas. - ngrok a changé cela en sa faveur. Chaque compte, y compris les gratuits, reçoit un domaine de développement attribué (par exemple
your-assigned-name.ngrok-free.dev) qui est statique lors des redémarrages de l’agent et reste lié au compte. Vous ne pouvez pas le renommer, toutefois. Choisir votre sous-domaine exige le plan Hobbyist payant, et la génération aléatoire de domaines n’est pas disponible sur le plan gratuit. Les points de terminaison gratuits n’ont pas de délai d’expiration, et les points de terminaison HTTPS gratuits affichent une page d’intermédiaire lors du premier chargement — ce qui vaut la peine de savoir avant de donner un téléphone à un collègue. - Tunnels à sous-domaines nommés, dont InstaTunnel, vous permettent de choisir le nom d’hôte sur la ligne de commande. La documentation du paquet InstaTunnel montre
instatunnel 3000 --subdomain myappproduisanthttps://myapp.instatunnel.my, et ses propres matériels font la promotion de sous-domaines personnalisés dans le niveau gratuit.
L’essentiel n’est pas de savoir quel fournisseur l’emporte. Ce qui compte, c’est que les tests de passkeys nécessitent un nom d’hôte que vous choisissez et que vous gardez.
Choisissez un seul nom et utilisez-le partout
La solution est ennuyeuse, mais efficace : choisissez un nom d’hôte une fois, puis dérivez votre RP ID et votre origine à partir de celui-ci.
Étape 1 : Réclamer un sous-domaine stable
instatunnel 3000 --subdomain pk-test
# https://pk-test.instatunnel.my
Avec ngrok, utilisez plutôt votre domaine de développement attribué (affiché sous Domaines dans le tableau de bord) :
ngrok http 3000 --url https://<your-dev-domain>.ngrok-free.dev
Choisissez un nom qui sonne comme une infrastructure de test (pk-test, acme-passkeys-dev) pour éviter que quelqu’un ne le prenne pour quelque chose de réel.
Étape 2 : Maintenir l’identité dans les variables d’environnement
# .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
N’utilisez pas ces valeurs à partir des en-têtes de requête. Votre application est derrière un proxy, donc l’en-tête Host et les en-têtes transférés qu’elle voit peuvent ne pas correspondre à ceux utilisés par le navigateur, et faire confiance aux en-têtes X-Forwarded-* fournis par n’importe quelle source juste pour éliminer une erreur d’origine pose un problème de sécurité à part entière. La configuration est la source de vérité ; les en-têtes ne le sont pas.
Étape 3 : Intégrer la configuration dans votre bibliothèque 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,
});
// plus tard, lors de la réponse:
const verification = await verifyRegistrationResponse({
response,
expectedChallenge,
expectedOrigin: origin,
expectedRPID: rpID,
});
Les noms de paramètres diffèrent légèrement selon les versions de la bibliothèque, vérifiez donc la docs de votre version. Le principe ne change pas : un seul RP ID, une seule origine, tous deux issus de la configuration, et le même RP ID dans les options d’enregistrement, la vérification d’enregistrement, les options d’authentification et la vérification d’assertion.
Étape 4 : Utiliser le nom d’hôte complet comme RP ID
Pour les tests de tunnel, le nom d’hôte complet est le RP ID le plus sûr. La documentation d’ngrok indique que ses domaines de base gérés (ngrok-free.app, ngrok-free.dev et d’autres) figurent sur la Public Suffix List, de sorte que le domaine de base lui-même ne peut jamais être votre RP ID. Le nom d’hôte complet est toujours valide et ne peut pas élargir la portée du credential. Un RP ID parent plus large n’a de sens que sur un domaine personnalisé que vous contrôlez, lorsque le partage d’identifiants entre sous-domaines est un choix de conception délibéré.
Étape 5 : Vérifier l’infrastructure autour de la cérémonie
Une URL de tunnel change plus que le nom d’hôte. Avant de blâmer WebAuthn, confirmez :
- Pas d’URL localhost codées en dur. Si la page se charge via le tunnel mais que les appels API ciblent toujours
localhost, la cérémonie échoue pour des raisons qui ressemblent à des erreurs de passkey. - Les cookies persistent avec la nouvelle origine. Les défis sont liés à une session. Si le cookie de session n’est pas envoyé lors de la requête de fin (mauvais domaine,
SecureouSameSite), vous verrez une incompatibilité de défi même si l’authentificateur a fait son travail. - Vérifications du nom d’hôte du serveur de développement. Certains serveurs de développement rejettent des noms d’hôte inconnus. Autorisez le nom d’hôte du tunnel plutôt que de désactiver la vérification globalement.
Conservez localhost et les environnements tunnel séparés
Puisque les deux identités ne peuvent pas partager les identifiants, cessez de les considérer comme susceptibles de le faire.
- Stockez le RP ID avec chaque identifiant. Une colonne
rp_idvous permet de purger par environnement plutôt que de deviner quelles lignes sont mortes. - Utilisez des comptes de test distincts pour localhost et les tunnels, afin que la question « pourquoi cet utilisateur ne peut-il pas se connecter ? » reste traçable.
- Supprimez les anciens passkeys de votre gestionnaire de mots de passe lorsque vous retirez un nom d’hôte. WebAuthn Niveau 3 définit une API Signal qui permet à un site d’indiquer au fournisseur de passkeys quelles identifiants sont encore valides, et Chrome et Edge l’ont déployée depuis la version 132 (janvier 2025). Mais l’appel ne fonctionne que pour le RP ID à partir duquel la page est réellement servie, il peut donc nettoyer les identifiants périmés sur votre nom d’hôte tunnel actuel, et non sur les noms d’hôte qui n’existent plus.
- Utilisez uniquement des utilisateurs éphémères. Si un sous-domaine de tunnel peut être réclamé par quelqu’un d’autre après que vous l’ayez abandonné, ne mettez pas de comptes réels derrière.
Sur le nom d’hôte actuel, une connexion échouée pour un identifiant que votre serveur ne connaît plus est l’endroit naturel pour signaler :
// credentialId: the base64url ID the browser just presented
if (PublicKeyCredential.signalUnknownCredential) {
await PublicKeyCredential.signalUnknownCredential({
rpId: process.env.RP_ID,
credentialId,
});
}
Toujours détecter les capacités en premier, car le support varie selon le navigateur et la plateforme.
Quand quelque chose échoue : tableau de débogage
| Symptôme | Cause probable | Correction |
|---|---|---|
SecurityError sur create() ou get() |
rp.id n’est pas le nom d’hôte de la page ou un parent enregistrable, ou la page n’est pas dans un contexte sécurisé |
Définissez rp.id sur le nom d’hôte du tunnel, ou omettez-le délibérément ; utilisez l’URL HTTPS |
| Sélecteur de passkey vide sur le tunnel | Le credential a été enregistré sous localhost ou une URL de tunnel plus ancienne |
Enregistrez à nouveau sous le nom d’hôte actuel |
NotAllowedError |
Invite annulée, délai, ou aucun authentificateur ou identifiant utilisable | Vérifiez la console et le verrouillage de l’appareil, puis confirmez que le RP ID correspond à l’enregistrement |
| Origine inattendue | La liste des origines ne contient pas la chaîne exacte https://host |
Ajoutez l’origine complète, incluant le schéma |
| Hachage du RP ID mismatch | Le rpID du serveur diffère de celui utilisé par le navigateur |
Assurez-vous que les deux lisent la même variable d’environnement |
| Fonctionne sur bureau, pas sur mobile | Le téléphone accède à l’app via HTTP sur une IP LAN | Utilisez l’URL du tunnel HTTPS sur le téléphone |
| Défi manquant ou mal assorti | Le cookie de session n’est pas envoyé, ou le défi stocké dans un processus et vérifié dans un autre | Corrigez les paramètres des cookies pour l’hôte public ; utilisez une session partagée ou un cache |
| Invitation apparait, l’enregistrement échoue | Vérification côté serveur (origine, hash du RP ID, défi) l’a rejetée | Lisez l’erreur structurée de votre bibliothèque, pas seulement le résultat du navigateur |
À quoi sert un tunnel, et ce qu’il n’est pas
Un tunnel mérite sa place pour les tests sur véritables appareils. Le guide ngrok de Corbado explique pourquoi les tests uniquement sur Wi‑Fi échouent : une origine HTTP sur une adresse IP LAN n’est pas un contexte sécurisé, donc le navigateur n’exécute pas la cérémonie WebAuthn. Une URL HTTPS publique corrige cela et vous permet de tester les authenticators sur iOS, Android, Windows et macOS, depuis un téléphone en données mobiles ou un ordinateur portable sur n’importe quel réseau.
Ce n’est pas l’outil adapté à l’automatisation répétitive. L’onglet WebAuthn des DevTools de Chrome et le domaine WebAuthn du Chrome DevTools Protocol proposent des authenticators virtuels, et Selenium expose la même idée via son API Virtual Authenticator, qui suit le modèle d’automatisation WebAuthn du W3C. Playwright et Puppeteer peuvent piloter le même domaine CDP. Ils permettent à CI d’enregistrer et d’affirmer les passkeys sans tête contre localhost, mais ils ne peuvent pas reproduire l’UI des authenticators de plateforme, la synchronisation du fournisseur de passkeys ou les bizarreries des appareils réels. Une répartition raisonnable : authenticators virtuels sur localhost pour CI, et un nom d’hôte stable avec de vrais authenticators pour la matrice d’appareils.
Les Related Origin Requests ne sauveront pas les URL aléatoires
Related Origin Requests (ROR) permettent à d’autres origines d’utiliser votre RP ID. L’hôte du RP ID publie un fichier JSON à https://{RP ID}/.well-known/webauthn avec un tableau origins, et le navigateur vérifie cette liste avant d’autoriser une requête dont l’origine ne correspond pas au RP ID. Sans prise en charge de ROR, le navigateur renvoie une SecurityError.
Le support s’est élargi. Chrome (128) et Safari le prennent en charge, et Firefox l’a ajouté dans la version 152, sortie le 16 juin 2026. Chrome limite la liste à cinq labels distincts, où un label est le nom eTLD+1 : example.co.uk et example.de comptent tous comme example, ils prennent donc un seul emplacement. Tous les sites doivent également partager une base de données de comptes, car ROR ne permet une authentification d’identifiant qu’entre origines qui partagent déjà un répertoire utilisateur.
Cela peut sembler être une solution pour éviter de changer les URLs du tunnel. Ce n’est pas le cas : le fichier doit être servi par l’hôte du RP ID et lister chaque origine, vous seriez donc amené à le modifier à chaque changement de nom d’hôte aléatoire. ROR mérite d’être testé seulement si votre conception de production l’utilise, et alors deux noms de tunnel stables (l’un comme l’hôte du RP ID, l’autre comme origine associée) vous permettent de vous entraîner.
FAQ
Puis-je utiliser un passkey enregistré sur localhost pour mon URL de tunnel ?
Non. Le RP ID est localhost pour le premier et le nom d’hôte du tunnel pour le second. Enregistrez à nouveau sous le nom d’hôte du tunnel.
Puis-je définir le RP ID sur le domaine de base du fournisseur du tunnel ?
Généralement non. Si le domaine de base est sur la Public Suffix List, comme les domaines gérés par ngrok, les navigateurs le rejettent. Utilisez le nom d’hôte complet.
Pourquoi mes passkeys ont-ils disparu après le redémarrage du tunnel ?
Si le tunnel a attribué un nouveau nom d’hôte aléatoire, votre RP ID a changé. Les anciens identifiants existent encore, mais uniquement pour l’ancien nom d’hôte.
Puis-je tester les passkeys sur mon téléphone sans tunnel ?
Seulement si la page est servie à partir d’un contexte sécurisé, ce qui signifie HTTPS ou une adresse de boucle locale. Une adresse LAN en HTTP pur ne convient pas, ce qui explique pourquoi un tunnel HTTPS public (ou une configuration de certificat local fiable) est nécessaire pour les tests sur appareil.
Ai-je besoin d’un nouvel identifiant si je renomme mon sous-domaine de tunnel ?
Oui. Un nouveau nom d’hôte est un nouveau RP ID, il faut donc enregistrer un nouveau passkey de test. Un RP ID ne peut pas être modifié sur un identifiant existant.
Conclusion
Les passkeys testent ce que la plupart des tunnels n’ont pas été conçus pour préserver, à savoir une identité publique stable. Considérez localhost et votre tunnel comme deux environnements distincts, conservez le RP ID et l’origine dans la configuration, et donnez au tunnel un nom d’hôte qui ne change pas. Alors le passkey enregistré lundi fonctionnera toujours vendredi, et vos échecs pointeront vers de vrais bugs plutôt que vers un nom d’hôte qui a changé du jour au lendemain.
Sources
- FIDO Alliance: WebAuthn Level 3 is now a W3C Recommendation
- W3C Web Authentication Level 3
- W3C WebAuthn explainer: Related Origin Requests
- web.dev: Allow passkey reuse across your sites with Related Origin Requests
- Firefox 152 release notes
- MojoAuth: Related Origin Requests across ccTLDs
- MojoAuth: Choosing Your RP ID
- Chrome for Developers: WebAuthn Signal API
- Corbado: Test Passkeys from Localhost with ngrok
- Localtonet: Test WebAuthn Passkeys Through a Localhost HTTPS Tunnel
- ngrok docs: Domains
- ngrok docs: Free plan limits
- ngrok blog: Static dev domains for all ngrok users
- Cloudflare Sandbox docs: Quick vs. named tunnels
- Flavio Copes: The complete guide to Cloudflare Quick Tunnels
- Selenium docs: Virtual Authenticator
- InstaTunnel package README
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.