InstaTunnel
Basculer le menu de navigation
Tutorial
13 min read
80 views

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.

IT
InstaTunnel Team
Published by the InstaTunnel team | Editorial policy
Tester les passkeys via un tunnel : RP ID, origines et pourquoi les identifiants ne vous suivent pas depuis localhost

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. localhost et 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:

  1. 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 SecurityError du navigateur.
  2. Pas de suffixes publics. Les navigateurs valident le RP ID par rapport à la Public Suffix List, donc un suffixe nu comme com ou co.uk est rejeté, tandis qu’un vrai domaine comme example.com est acceptable. localhost est accepté pour le développement.
  3. Contexte sécurisé. WebAuthn nécessite HTTPS. L’exception de développement couvre localhost et les adresses de loopback, pas une page HTTP simple sur une adresse IP LAN comme 192.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 (cloudflared sans compte) vous donnent un nom d’hôte aléatoire *.trycloudflare.com qui 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 myapp produisant https://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, Secure ou SameSite), 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_id vous 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

Continue from this article into the most relevant product guides and workflows.

Related Topics

#passkeys#test passkeys localhost#passkeys tunnel#passkey testing#WebAuthn#WebAuthn localhost#WebAuthn testing#WebAuthn tunnel#RP ID#relying party ID#WebAuthn RP ID#passkey RP ID mismatch#passkey origin#WebAuthn origin validation#registrable domain suffix#passkey credentials localhost#passkeys not working localhost#passkey SecurityError#invalid RP ID#passkey HTTPS requirement#test passkeys HTTPS#passkeys ngrok#passkeys ngrok alternative#localhost tunnel#localhost tunneling#localhost tunnel tools#expose localhost to internet#stable subdomain tunnel#named subdomain tunnel#static tunnel URL#random tunnel URL problem#persistent tunnel URL#custom domain tunnel#tunnel public domain#passkey development environment#passkey local development#passkey dev environment setup#FIDO2#FIDO2 testing#FIDO2 localhost#passwordless authentication#passwordless login testing#passwordless development#WebAuthn API#navigator.credentials.create#navigator.credentials.get#passkey registration#passkey authentication flow#passkey credential storage#platform authenticator#security keys testing#Face ID passkey testing#Touch ID passkey testing#Windows Hello passkeys#mobile passkey testing#test passkeys on phone#developer authentication#authentication debugging#web authentication#secure tunnel developers

Keep building with InstaTunnel

Read the docs for implementation details or compare plans before you ship.

Share this article

More InstaTunnel Insights

Discover more tutorials, tips, and updates to help you build better with localhost tunneling.

Browse All Articles