Implementazione della relying party

Per implementare la verifica email sul tuo sito, aggiorna il markup del modulo per richiedere il token e aggiungi la convalida lato server per i token in entrata.

Registrati per l'origin trial

I siti che eseguono la verifica devono avere l'origin trial configurato sul sito.

A partire da Chrome 154, le prove dell'origine di terze parti sono supportate con un'importante avvertenza: l'origine registrata per la prova deve essere dello stesso sito dell'emittente. Ad esempio:

  • Dominio dell'emittente: issuer.example
  • Registrante della prova dell'origine: https://issuer.example
  • Origine JavaScript: https://issuer.example (o https://app.issuer.example con corrispondenza del sottodominio)

Configura i campi del modulo

Aggiungi un campo token nascosto al modulo di invio dell'email:

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

Requisiti dei campi:

  • Campo email: imposta type="email" e autocomplete="email" in modo che Chrome possa compilare automaticamente e riconoscere l'indirizzo.
  • Attributi del campo token:
    • Imposta autocomplete="email-verification-token": Chrome identifica questo campo per inserire il token al momento dell'invio.
    • Imposta nonce="<VALUE>": il sito deve fornire un nonce univoco associato alla sessione per verificare l'invio del modulo.

Convalida il token di verifica email (EVT)

Quando l'utente invia il modulo, il server riceve l'indirizzo email e il token dal campo nascosto. Un campo token vuoto indica che il browser o il provider non supporta EVP oppure che l'utente ha saltato la verifica. In questo caso, torna alla procedura di verifica esistente, ad esempio inviando un OTP o un link magico.

Se è presente un token, convalidalo nel seguente modo:

  1. Analizza il token utilizzando una libreria SD-JWT.
  2. Convalida i valori previsti e le richieste di sessione.
  3. Verifica la delega DNS.
  4. Scopri i metadati dell'emittente e recupera JWKS.
  5. Verifica le firme crittografiche e l'associazione delle chiavi.

1. Analizza il token

Il token utilizza il formato RFC 9901: Selective Disclosure JWT (SD-JWT+KB). Utilizza le librerie appropriate per la tua piattaforma per analizzare e convalidare il token. Ad esempio, per Node puoi utilizzare @sd-jwt/core e jose. Nella sua forma non elaborata, si presenta così: un JWT firmato dall'emittente, seguito da zero o più divulgazioni e terminato con un JWT di associazione delle chiavi, con ogni componente separato da una tilde:

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

Nell'implementazione attuale, il token non contiene divulgazioni (<Issuer-signed EVT>~<Key Binding JWT>). Tuttavia, questo potrebbe cambiare in futuro.

Decodifica il token con la libreria:

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;

Se verifier.example verifica demo@provider.example, il token decodificato è simile al seguente:

{
  "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. Convalida i valori previsti e le richieste di sessione

Verifica che i valori di base nel payload corrispondano ai valori forniti e previsti:

  • email_verified: deve essere true.
  • email: deve corrispondere all'indirizzo email inviato nel modulo.
  • aud (pubblico): deve corrispondere all'origine del tuo sito.
  • nonce: deve corrispondere al nonce fornito nel modulo.
  • iat (emesso il) e exp (scadenza): verifica che il token sia all'interno della finestra temporale valida e che non sia scaduto.

3. Verifica la delega DNS

Verifica il record DNS _email-verification per il dominio dell'indirizzo email. Ad esempio, per demo@gmail.com, esegui una query sul record TXT _email-verification.gmail.com. Per questo provider, la query restituisce la posizione del provider dell'account, ovvero accounts.google.com.

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

Verifica che lo schema dell'emittente sia https:// e che https://<domain> corrisponda alla iss richiesta nell'EVT.

4. Verifica la firma EVT

Recupera i metadati di rilevamento dell'emittente da 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"]
}

Se i metadati includono un campo issuer, verifica che corrisponda alla iss richiesta nell'EVT byte per byte. Recupera il set di chiavi web JSON da jwks_uri.

Utilizza la libreria SD-JWT per verificare il pacchetto di token. La libreria coordina la convalida:

  1. Convalida la firma dell'emittente sull'EVT rispetto a JWKS recuperato.
  2. Convalida la firma del browser sul KB-JWT utilizzando la chiave pubblica effimera in cnf.jwk.
  3. Verifica l'associazione delle chiavi (aud, nonce e l'hash del digest sd_hash).

Esempio di logica di verifica in 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");
}

Se tutti i passaggi hanno esito positivo, hai verificato l'indirizzo email rispetto al provider. Se la verifica non va a buon fine, torna all'invio di un'email di conferma all'utente utilizzando il flusso normale.

Risoluzione dei problemi

Se la verifica non va a buon fine o il browser non fornisce un token, controlla i seguenti problemi comuni:

Il campo token è vuoto al momento dell'invio

  • Registrazione all'origin trial: verifica che l'intestazione Origin-Trial o il <meta> tag venga pubblicato nella pagina e che il token non abbia superato la data di scadenza (i token generati prima dell'estensione di Chrome 160 scadono il 17 novembre, 2026). Per gli origin trial di terze parti (Chrome 154 e versioni successive), l'origine dell'origin trial registrato deve essere dello stesso sito dell'emittente (https://<issuer-domain>). Puoi controllare lo stato dell'origin trial e la scadenza del token su un sito in DevTools in Applicazione > Frame > (seleziona il frame pertinente) > Origin trial.
  • Markup del modulo: sia <input type="email" autocomplete="email"> sia <input type="hidden" autocomplete="email-verification-token" nonce="..."> devono essere nello stesso elemento <form> (non isolati tra i limiti di Shadow DOM boundaries) e nonce non deve essere vuoto.
  • Invio anticipato o pagina riutilizzata: il browser recupera il token in background dopo che l'email è stata inserita o compilata automaticamente. Se invii prima del completamento della richiesta, il token rimane vuoto. Questo può accadere se l'utente preme Invio per inviare il modulo dopo aver inserito l'email.
  • Prerequisiti del browser e del provider: l'utente deve aver eseguito l'accesso a un provider partecipante nello stesso profilo del browser e deve aver attivato l'opzione Email verificata nelle impostazioni di Chrome (chrome://settings/contactInfo).

La verifica della firma dell'emittente non va a buon fine

  • Intestazione kid mancante: la richiesta kid (ID chiave) nell'intestazione EVT e JWKS è facoltativa (ad esempio, Gmail omette kid). Se kid è assente, scorri tutte le chiavi candidate in jwks_uri dell'emittente anziché non riuscire a trovare un ID chiave.
  • Identificatori dell'algoritmo (Ed25519 e EdDSA): a partire da Chrome 156, Chrome utilizza l'identificatore dell'algoritmo Ed25519 completamente specificato (RFC 9864) per le intestazioni cnf.jwk e KB-JWT, mentre gli emittenti e le librerie possono specificare Ed25519 o EdDSA (insieme a ES256). Assicurati che la logica di importazione e verifica JWK accetti entrambi gli identificatori.
  • Formato dell'origine dell'emittente (iss): il record TXT DNS (_email-verification.<domain>) contiene un nome host semplice (iss=accounts.issuer.example), mentre la richiesta iss EVT è un'origine HTTPS completa (https://accounts.issuer.example, senza barra finale). Aggiungi il prefisso https:// al valore del record DNS prima di confrontarlo.

La convalida dell'associazione delle chiavi (KB-JWT) non va a buon fine

  • Nonce non corrispondente o scaduto: assicurati che il nonce visualizzato in <input> corrisponda al nonce della sessione attiva sul server e che non sia stato sovrascritto da un'altra scheda o utilizzato da una richiesta precedente.
  • Mancata corrispondenza del pubblico (aud): la richiesta aud è l'origine HTTPS del verificatore (https://verifier.example, senza percorso o barra finale).

Il confronto della richiesta email (email) non va a buon fine

  • Combinazione di maiuscole e minuscole e canonizzazione: Chrome 156 e versioni successive restituiscono la richiesta email byte per byte come inserita nel modulo, ma le versioni precedenti del browser o i provider potrebbero restituire un indirizzo canonizzato (ad esempio, First.Last@example.com per first.last@example.com). Utilizza un confronto senza distinzione tra maiuscole e minuscole quando fai corrispondere la richiesta email del token al valore del modulo inviato.