Als u e-mailverificatie op uw site wilt implementeren, updatet u de formuliermarkering om de token aan te vragen en voegt u validatie aan de serverzijde toe voor inkomende tokens.
Registreren voor de origin trial
Voor de verificatie van sites moet de origin trial op de site zijn ingesteld.
Vanaf Chrome 154 worden origin trials van derden ondersteund met een belangrijke kanttekening: de geregistreerde origin voor de trial moet dezelfde site zijn als de uitgever. Voorbeeld:
- Domein van uitgever:
issuer.example - OT-registrant:
https://issuer.example - JavaScript-oorsprong:
https://issuer.example(ofhttps://app.issuer.examplemet overeenkomende subdomeinen)
Formuliervelden instellen
Voeg een verborgen tokenveld toe aan je e-mailinzendingsformulier:
<input
type="email"
name="email-address"
autocomplete="email">
<input
type="hidden"
name="token"
autocomplete="email-verification-token"
nonce="rAnD0m-VaLuE">
Veldvereisten:
- E-mailveld: Stel
type="email"enautocomplete="email"in zodat Chrome het adres automatisch kan invullen en herkennen. - Kenmerken van tokenvelden:
- Instellen
autocomplete="email-verification-token": Chrome herkent dit veld om het token in te vullen bij de indiening. - Instellen
nonce="<VALUE>": De site moet een unieke, aan de sessie gebonden nonce bieden om de formulierinzending te verifiëren.
- Instellen
Valideer het e-mailverificatietoken (EVT).
Wanneer de gebruiker het formulier indient, ontvangt uw server het e-mailadres en de token uit het verborgen veld. Een leeg tokenveld geeft aan dat de browser of provider EVP niet ondersteunt of dat de gebruiker de verificatie heeft overgeslagen. Als dit gebeurt, val je terug op je bestaande verificatieproces, zoals het sturen van een OTP of een magische link.
Als er een token aanwezig is, valideer je deze als volgt:
- Parse de token met een SD-JWT-bibliotheek.
- Valideer de verwachte waarden en sessieclaims.
- Controleer de DNS-delegatie.
- Metadata van de uitgever ontdekken en JWKS ophalen.
- Verifieer cryptografische handtekeningen en sleutelbinding.
1. Het token parseren
De token gebruikt de indeling RFC 9901: Selective Disclosure JWT (SD-JWT+KB). Gebruik de juiste bibliotheken voor je platform om de token te parseren en te valideren.
Voor Node kun je bijvoorbeeld @sd-jwt/core en jose gebruiken. In de onbewerkte vorm ziet dit er zo uit: een door de uitgever ondertekende JWT, gevolgd door nul of meer bekendmakingen en eindigend met een sleutelbinding-JWT, waarbij elke component wordt gescheiden door een tilde:
<Issuer-signed EVT>~<Disclosure 1>~...~<Disclosure N>~<Key Binding JWT>
In de huidige implementatie bevat de token nul kennisgevingen (<Issuer-signed EVT>~<Key Binding JWT>). Dit kan in de toekomst veranderen.
Decodeer de token met de bibliotheek:
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;
Als verifier.example demo@provider.example verifieert, ziet de gedecodeerde token er ongeveer zo uit:
{
"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. Verwachte waarden en sessieclaims valideren
Controleer of de basiswaarden in de payload overeenkomen met de door jou verstrekte en verwachte waarden:
email_verified: Moettruezijn.email: Moet overeenkomen met het e-mailadres dat in het formulier is ingediend.aud(doelgroep): Moet overeenkomen met de oorsprong van uw site.nonce: Moet overeenkomen met de nonce die in uw formulier is ingevoerd.iat(uitgegeven op) enexp(verloopt op): Bevestig dat de token binnen de geldige periode valt en niet is verlopen.
3. DNS-overdracht verifiëren
Verifieer de _email-verification DNS-record voor het domein van het e-mailadres. Vraag bijvoorbeeld voor demo@gmail.com het _email-verification.gmail.com TXT-record op. Voor deze provider retourneert de query de locatie van de accountprovider, namelijk accounts.google.com.
$ dig +short TXT _email-verification.gmail.com
"iss=accounts.google.com"
Controleer of het uitgifte-schema https:// is en of https://<domain> overeenkomt met de iss-claim in de EVT.
4. De EVT-handtekening verifiëren
De discovery-metadata van de uitgever ophalen uit
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"]
}
Als de metadata een veld issuer bevat, controleert u of dit byte voor byte overeenkomt met de claim iss in de EVT. Haal de set json-websleutels op uit jwks_uri.
Gebruik je SD-JWT-bibliotheek om het tokenpakket te verifiëren. De bibliotheek coördineert de validatie:
- De handtekening van de uitgever op de EVT valideren aan de hand van de opgehaalde JWKS.
- De handtekening van de browser op de KB-JWT valideren met de tijdelijke openbare sleutel in
cnf.jwk. - De sleutelbinding verifiëren (
aud,nonceen de digest-hashsd_hash).
Voorbeeld van verificatielogica 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");
}
Als alle stappen zijn gelukt, heb je het e-mailadres laten verifiëren door de provider. Als de verificatie mislukt, valt u terug op het sturen van een bevestigingsmail naar de gebruiker via uw normale proces.
Problemen oplossen
Als de verificatie mislukt of de browser geen token verstrekt, controleert u de volgende veelvoorkomende problemen:
Het tokenveld is leeg bij het indienen
- Origin trial-registratie: Bevestig dat de
Origin-Trialheader of<meta>tag op de pagina wordt weergegeven en dat de token niet is verlopen (tokens die vóór de Chrome 160-extensie zijn gegenereerd, verlopen op 17 november 2026). Voor origin trials van derden (Chrome 154 en hoger) moet de geregistreerde origin trial same-site zijn voor de uitgever (https://<issuer-domain>). Je kunt de status van de origin trial en de vervaldatum van het token op een site inspecteren in DevTools onder Application > Frames > (selecteer het relevante frame) > Origin trials. - Formulieropmaak: Zowel
<input type="email" autocomplete="email">als<input type="hidden" autocomplete="email-verification-token" nonce="...">moeten in hetzelfde<form>-element staan (niet geïsoleerd over Shadow DOM-grenzen) ennoncemag niet leeg zijn. - Vroege inzending of hergebruikte pagina: De browser haalt de token op de achtergrond op nadat het e-mailadres is ingevoerd of automatisch is ingevuld. Als je het formulier indient voordat het verzoek is afgerond, blijft de token leeg. Dit kan gebeuren als de gebruiker op Return drukt om het formulier in te dienen nadat die het e-mailadres heeft ingevoerd.
- Vereisten voor browser en provider: De gebruiker moet in hetzelfde browserprofiel zijn ingelogd bij een deelnemende provider en Geverifieerd e-mailadres aan hebben staan in de Chrome-instellingen (
chrome://settings/contactInfo).
Verificatie van de handtekening van de uitgever mislukt
kid-header ontbreekt: De claimkid(sleutel-ID) in de EVT-header en JWKS is optioneel (Gmail laatkidbijvoorbeeld weg). Alskidontbreekt, doorloop je alle kandidaatsleutels in dejwks_urivan de uitgever in plaats van te mislukken bij het opzoeken van een sleutel-ID.- Algoritme-ID's (
Ed25519enEdDSA): Vanaf Chrome 156 gebruikt Chrome de volledig gespecificeerde algoritme-IDEd25519(RFC 9864) voorcnf.jwk- enKB-JWT-headers, terwijl uitgevende instanties en bibliothekenEd25519ofEdDSAkunnen specificeren (naastES256). Zorg dat je JWK-import- en verificatielogica beide ID's accepteert. - Oorsprongsindeling van uitgever (
iss): De DNS TXT-record (_email-verification.<domain>) bevat een kale hostnaam (iss=accounts.issuer.example), terwijl de EVT-claimisseen volledige HTTPS-oorsprong is (https://accounts.issuer.example, zonder afsluitende slash). Voeg het voorvoegselhttps://toe aan de waarde van de DNS-record voordat je deze vergelijkt.
Validatie van sleutelbinding (KB-JWT) mislukt
- Niet-overeenkomende of verlopen nonce: Zorg dat de
noncedie wordt gerenderd in de<input>overeenkomt met de actieve sessie-nonce op je server en niet is overschreven door een ander tabblad of is gebruikt door een eerder verzoek. - Doelgroep (
aud) komt niet overeen: Deaud-claim is de HTTPS-oorsprong van de verificateur (https://verifier.example, zonder pad of afsluitende slash).
Vergelijking van e-mailclaim (email) mislukt
- Hoofdletters en kleine letters en normalisatie: Chrome 156+ retourneert de claim
emailbyte voor byte zoals ingevoerd in het formulier, maar eerdere browserversies of providers kunnen een genormaliseerd adres retourneren (bijvoorbeeldFirst.Last@example.comvoorfirst.last@example.com). Gebruik een vergelijking die niet hoofdlettergevoelig is als je de claimemailvan het token vergelijkt met de ingediende formulierwaarde.