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.
- Registrati per l'origin trial
- Pubblica il token dell'origin trial
- Dominio dell'emittente:
issuer.example - Registrante della prova dell'origine:
https://issuer.example - Origine JavaScript:
https://issuer.example(ohttps://app.issuer.examplecon 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"eautocomplete="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.
- Imposta
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:
- Analizza il token utilizzando una libreria SD-JWT.
- Convalida i valori previsti e le richieste di sessione.
- Verifica la delega DNS.
- Scopri i metadati dell'emittente e recupera JWKS.
- 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 esseretrue.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) eexp(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:
- Convalida la firma dell'emittente sull'EVT rispetto a JWKS recuperato.
- Convalida la firma del browser sul KB-JWT utilizzando la chiave pubblica effimera in
cnf.jwk. - Verifica l'associazione delle chiavi (
aud,noncee l'hash del digestsd_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-Trialo 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) enoncenon 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
kidmancante: la richiestakid(ID chiave) nell'intestazione EVT e JWKS è facoltativa (ad esempio, Gmail omettekid). Sekidè assente, scorri tutte le chiavi candidate injwks_uridell'emittente anziché non riuscire a trovare un ID chiave. - Identificatori dell'algoritmo (
Ed25519eEdDSA): a partire da Chrome 156, Chrome utilizza l'identificatore dell'algoritmoEd25519completamente specificato (RFC 9864) per le intestazionicnf.jwkeKB-JWT, mentre gli emittenti e le librerie possono specificareEd25519oEdDSA(insieme aES256). 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 richiestaissEVT è un'origine HTTPS completa (https://accounts.issuer.example, senza barra finale). Aggiungi il prefissohttps://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
noncevisualizzato 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 richiestaaudè 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
emailbyte 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.comperfirst.last@example.com). Utilizza un confronto senza distinzione tra maiuscole e minuscole quando fai corrispondere la richiestaemaildel token al valore del modulo inviato.