Implémentation du tiers de confiance

Pour implémenter la validation par e-mail sur votre site, mettez à jour le balisage de votre formulaire afin de demander le jeton et ajoutez une validation côté serveur pour les jetons entrants.

S'inscrire à la phase d'évaluation

Les sites de validation doivent avoir configuré l'essai Origin Trial sur leur site.

À partir de Chrome 154, les essais Origin Trial tiers sont compatibles avec une mise en garde importante : l'origine enregistrée pour l'essai Origin Trial doit être sur le même site que l' émetteur. Exemple :

  • Domaine de l'émetteur : issuer.example
  • Inscrit à la phase d'évaluation : https://issuer.example
  • Origine JavaScript : https://issuer.example (ou https://app.issuer.example avec correspondance de sous-domaine)

Configurer les champs de formulaire

Ajoutez un champ de jeton masqué à votre formulaire d'envoi d'e-mails :

<input
  type="email"
  name="email-address"
  autocomplete="email">
<input
  type="hidden"
  name="token"
  autocomplete="email-verification-token"
  nonce="rAnD0m-VaLuE">

Exigences concernant les champs :

  • Champ "E-mail" : définissez type="email" et autocomplete="email" pour que Chrome puisse saisir automatiquement et reconnaître l'adresse.
  • Attributs du champ de jeton:
    • Définissez autocomplete="email-verification-token" : Chrome identifie ce champ pour renseigner le jeton lors de l’envoi.
    • Définissez nonce="<VALUE>" : le site doit fournir un nonce unique lié à la session pour valider l'envoi du formulaire.

Valider le jeton de validation de l'adresse e-mail (JVE)

Lorsque l'utilisateur envoie le formulaire, votre serveur reçoit l'adresse e-mail et le jeton du champ masqué. Un champ de jeton vide indique que le navigateur ou le fournisseur ne sont pas compatibles avec la validation par e-mail, ou que l'utilisateur a ignoré la validation. Dans ce cas, revenez à votre procédure de validation existante, par exemple en envoyant un code secret à usage unique ou un lien magique.

Si un jeton est présent, validez-le comme suit :

  1. Analysez le jeton à l'aide d'une bibliothèque SD-JWT.
  2. Validez les valeurs attendues et les revendications de session.
  3. Vérifiez la délégation DNS.
  4. Découvrez les métadonnées de l'émetteur et récupérez les JWKS.
  5. Vérifiez les signatures cryptographiques et la liaison de clé.

1. Analyser le jeton

Le jeton utilise le format RFC 9901 : Selective Disclosure JWT (SD-JWT+KB). Utilisez les bibliothèques appropriées pour votre plate-forme afin d'analyser et de valider le jeton. Par exemple, pour Node, vous pouvez utiliser @sd-jwt/core et jose. Sous sa forme brute, il se présente comme suit : un JWT signé par l'émetteur, suivi de zéro ou plusieurs divulgations, et se terminant par un JWT de liaison de clé, chaque composant étant séparé par un tilde :

<Issuer-signed EVT>~<Disclosure 1>~...~<Disclosure N>~<Key Binding JWT>

Dans l'implémentation actuelle, le jeton ne contient aucune divulgation (<Issuer-signed EVT>~<Key Binding JWT>). Toutefois, cela peut changer à l'avenir.

Décodez le jeton avec la bibliothèque :

import { decodeSdJwtSync } from "@sd-jwt/core";
import { createHash } from "node:crypto";
const hasher = (data, alg) =>
  createHash(alg === "sha-256" ? "sha256" : alg)
    .update(data)
    .digest();
const decoded = decodeSdJwtSync(rawToken, hasher);
const evtPayload = decoded.jwt.payload;
const kbPayload = decoded.kbJwt?.payload;

Si verifier.example valide demo@provider.example, le jeton décodé se présente comme suit :

{
  "evtJwtDecodedHeader": {
    "typ": "evt+jwt",
    "alg": "EdDSA",
    "kid": "issuer-key-id"
  },
  "evtJwtDecodedPayload": {
    "iss": "https://provider.example",
    "iat": 12345678901,
    "exp": 12345679901,
    "cnf": {
      "jwk": {
        "kty": "OKP",
        "crv": "Ed25519",
        "x": "pUbLiCkEy123pUbLiCkEy123pUbLiCkEy123"
      }
    },
    "email": "demo@provider.example",
    "email_verified": true
  },
  "kbJwtDecodedHeader": {
    "alg": "EdDSA",
    "typ": "kb+jwt"
  },
  "kbJwtDecodedPayload": {
    "aud": "https://verifier.example",
    "iat": 12345678901,
    "nonce": "rAnDoM123rAnDoM123rAnDoM123rAnDoM123",
    "sd_hash": "hAsH456hAsH456hAsH456hAsH456hAsH456"
  },
  "disclosures": []
}

2. Valider les valeurs attendues et les revendications de session

Vérifiez que les valeurs de base de la charge utile correspondent aux valeurs que vous avez fournies et attendues :

  • email_verified : doit être true.
  • email : doit correspondre à l'adresse e-mail envoyée dans le formulaire.
  • aud (audience) : doit correspondre à l'origine de votre site.
  • nonce : doit correspondre au nonce fourni dans votre formulaire.
  • iat (délivré à) et exp (expiration) : vérifiez que le jeton se trouve dans sa période de validité et qu'il n'a pas expiré.

3. Vérifier la délégation DNS

Vérifiez l'enregistrement DNS _email-verification pour le domaine de l'adresse e-mail. Par exemple, pour demo@gmail.com, interrogez l'enregistrement TXT _email-verification.gmail.com. Pour ce fournisseur, la requête renvoie l'emplacement du fournisseur de compte, à savoir accounts.google.com.

$ dig +short TXT _email-verification.gmail.com
"iss=accounts.google.com"

Vérifiez que le schéma de l'émetteur est https:// et que https://<domain> correspond à la revendication iss dans le JVE.

4. Vérifier la signature du JVE

Récupérez les métadonnées de découverte de l'émetteur à partir de https://<issuer>/.well-known/email-verification :

{
  "issuer": "https://accounts.google.com",
  "issuance_endpoint": "https://accounts.google.com/gsi/email-verification/issue",
  "jwks_uri": "https://verifiablecredentials-pa.googleapis.com/.well-known/vc-public-jwks",
  "signing_alg_values_supported": ["Ed25519", "EdDSA"]
}

Si les métadonnées incluent un champ issuer, vérifiez qu'il correspond à la iss revendication dans le JVE octet par octet. Récupérez le JSON Web Key Set à partir de jwks_uri.

Utilisez votre bibliothèque SD-JWT pour vérifier le package de jetons. La bibliothèque coordonne la validation :

  1. Validation de la signature de l'émetteur sur le JVE par rapport aux JWKS récupérés.
  2. Validation de la signature du navigateur sur le KB-JWT à l'aide de la clé publique éphémère dans cnf.jwk.
  3. Vérification de la liaison de clé (aud, nonce et hachage de résumé sd_hash).

Exemple de logique de validation dans Node.js :

import { SDJwtInstance } from "@sd-jwt/core";
import { importJWK, compactVerify } from "jose";
import { createHash } from "node:crypto";
const allowedAlgs = ["Ed25519", "EdDSA", "ES256"];
const evtAlg = decoded.jwt.header.alg;
const kbAlg = decoded.kbJwt?.header.alg;
if (!allowedAlgs.includes(evtAlg) || !allowedAlgs.includes(kbAlg)) {
  throw new Error("Unsupported signing algorithm");
}
const hasher = (data, alg) =>
  createHash(alg === "sha-256" ? "sha256" : alg)
    .update(data)
    .digest();
const sdJwt = new SDJwtInstance({ hasher });
sdJwt.config({
  hasher,
  // Verifier for the Issuer-signed EVT
  verifier: async (data, sig) => {
    const token = `${data}.${sig}`;
    const header = decoded.jwt.header;
    // Match by kid if present, or iterate across matching algorithm keys
    const keysToTry = header.kid
      ? jwksData.keys.filter(k => k.kid === header.kid)
      : jwksData.keys;
    for (const jwk of keysToTry) {
      try {
        const pubKey = await importJWK(jwk, jwk.alg || evtAlg);
        await compactVerify(token, pubKey);
        return true;
      } catch {
        // Try next candidate key
      }
    }
    return false;
  },
  // Verifier for the Key Binding JWT (KB-JWT)
  kbVerifier: async (data, sig) => {
    try {
      const browserJwkKey = evtPayload.cnf?.jwk;
      if (!browserJwkKey) return false;
      const pubKey = await importJWK(browserJwkKey, kbAlg);
      await compactVerify(`${data}.${sig}`, pubKey);
      return true;
    } catch {
      return false;
    }
  },
});
// The library automatically verifies EVT signature, KB-JWT signature, audience, nonce, and sd_hash
const result = await sdJwt.verify(rawToken, {
  kb: {
    expectedNonce: sessionNonce,
    expectedAudience: "https://example.com",
    required: true,
  },
});
const verifiedPayload = result.payload;
if (
  verifiedPayload.email_verified !== true ||
  verifiedPayload.email?.toLowerCase() !== submittedEmail.toLowerCase()
) {
  throw new Error("Token email does not match submitted email");
}

Si toutes les étapes aboutissent, vous avez validé l'adresse e-mail auprès du fournisseur. Si la validation échoue, revenez à l'envoi d'un e-mail de confirmation à l'utilisateur à l'aide de votre flux normal.

Dépannage

Si la validation échoue ou si le navigateur ne fournit pas de jeton, vérifiez les problèmes courants suivants :

Le champ de jeton est vide lors de l'envoi

  • Inscription à l'essai Origin Trial : vérifiez que l'en-tête Origin-Trial ou la balise <meta> est diffusée sur la page et que le jeton n'a pas dépassé sa date d'expiration (les jetons générés avant l'extension Chrome 160 expirent le 17 novembre 2026). Pour les essais Origin Trial tiers (Chrome 154 et versions ultérieures), l'origine de l'essai Origin Trial enregistré doit être sur le même site que l'émetteur (https://<issuer-domain>). Vous pouvez inspecter l'état de l'essai Origin Trial et l'expiration du jeton sur un site dans les Outils de développement sous Application > Frames > (sélectionnez le frame approprié) > Essais Origin Trial.
  • Balisage de formulaire : <input type="email" autocomplete="email"> et <input type="hidden" autocomplete="email-verification-token" nonce="..."> doivent se trouver dans le même élément <form> (et non isolés au-delà des limites du Shadow DOM ), et nonce ne doit pas être vide.
  • Envoi anticipé ou page réutilisée : le navigateur récupère le jeton en arrière-plan une fois l'e-mail saisi ou rempli automatiquement. Si l'envoi est effectué avant la fin de la requête, le jeton reste vide. Cela peut se produire si l'utilisateur appuie sur la touche Entrée pour envoyer le formulaire après avoir saisi son adresse e-mail.
  • Prérequis du navigateur et du fournisseur : l'utilisateur doit être connecté à un fournisseur participant dans le même profil de navigateur et avoir activé l'option Adresse e-mail validée dans les paramètres Chrome (chrome://settings/contactInfo).

Échec de la validation de la signature de l'émetteur

  • En-tête kid manquant : la revendication kid (ID de clé) dans l'en-tête JVE et les JWKS est facultative (par exemple, Gmail omet kid). Si kid est absent, parcourez toutes les clés candidates dans le jwks_uri de l'émetteur au lieu d' échouer lors d'une recherche d'ID de clé.
  • Identifiants d'algorithme (Ed25519 et EdDSA) : à partir de Chrome 156, Chrome utilise l'identifiant d'algorithme Ed25519 entièrement spécifié (RFC 9864) pour les en-têtes cnf.jwk et KB-JWT, tandis que les émetteurs et les bibliothèques peuvent spécifier Ed25519 ou EdDSA (avec ES256). Assurez-vous que votre logique d'importation et de validation JWK accepte les deux identifiants.
  • Format d'origine de l'émetteur (iss) : l'enregistrement DNS TXT (_email-verification.<domain>) contient un nom d'hôte nu (iss=accounts.issuer.example), tandis que la revendication iss du JVE est une origine HTTPS complète (https://accounts.issuer.example, sans barre oblique finale). Ajoutez le préfixe https:// à la valeur de l'enregistrement DNS avant de comparer.

Échec de la validation de la liaison de clé (KB-JWT)

  • Nonce non correspondant ou expiré : assurez-vous que le nonce affiché dans le <input> correspond au nonce de session actif sur votre serveur et qu'il n'a pas été remplacé par un autre onglet ni consommé par une requête précédente.
  • Non-concordance de l'audience (aud) : la revendication aud est l'origine HTTPS du validateur (https://verifier.example, sans chemin ni barre oblique finale).

Échec de la comparaison de la revendication d'e-mail (email)

  • Casse et canonisation : Chrome 156 et versions ultérieures renvoient la revendication email octet par octet telle qu'elle a été saisie dans le formulaire, mais les versions antérieures du navigateur ou les fournisseurs peuvent renvoyer une adresse canonisée (par exemple, First.Last@example.com pour first.last@example.com). Utilisez une comparaison non sensible à la casse lorsque vous faites correspondre la revendication email du jeton à la valeur du formulaire envoyé.