Wenn Sie die E‑Mail-Bestätigung auf Ihrer Website implementieren möchten, aktualisieren Sie das Formular-Markup, um das Token anzufordern, und fügen Sie die serverseitige Validierung für eingehende Tokens hinzu.
Für den Ursprungstest registrieren
Auf Websites, die überprüft werden sollen, muss der Ursprungstest konfiguriert sein.
- Für den Ursprungstest registrieren
- Stellen Sie das Ursprungstest-Token bereit
Ab Chrome 154 werden Ursprungstests von Drittanbietern mit einer wichtigen Einschränkung unterstützt: Der registrierte Ursprung für den Test muss für den Aussteller derselbe sein. Beispiel:
- Ausstellerdomain:
issuer.example - Registrierter für den Ursprungstest:
https://issuer.example - JavaScript-Ursprung:
https://issuer.example(oderhttps://app.issuer.examplemit Subdomain-Abgleich)
Formularfelder konfigurieren
Fügen Sie Ihrem Formular für die E‑Mail-Einreichung ein ausgeblendetes Tokenfeld hinzu:
<input
type="email"
name="email-address"
autocomplete="email">
<input
type="hidden"
name="token"
autocomplete="email-verification-token"
nonce="rAnD0m-VaLuE">
Feldanforderungen:
- E‑Mail-Feld: Legen Sie
type="email"undautocomplete="email"fest, damit Chrome die Adresse automatisch ausfüllen und erkennen kann. - Attribute des Tokenfelds:
- Legen Sie
autocomplete="email-verification-token"fest: Chrome erkennt dieses Feld, um das Token bei der Einreichung einzufügen. - Legen Sie
nonce="<VALUE>"fest: Die Website muss eine eindeutige sitzungsgebundene Nonce bereitstellen, um die Formulareinreichung zu bestätigen.
- Legen Sie
E‑Mail-Bestätigungstoken (EVT) validieren
Wenn der Nutzer das Formular einreicht, erhält Ihr Server die E‑Mail-Adresse und das Token aus dem ausgeblendeten Feld. Ein leeres Tokenfeld bedeutet, dass der Browser oder Anbieter EVP nicht unterstützt oder der Nutzer die Bestätigung übersprungen hat. In diesem Fall sollten Sie auf Ihr vorhandenes Bestätigungsverfahren zurückgreifen, z. B. das Senden eines Einmalpassworts oder eines Magic Link.
Wenn ein Token vorhanden ist, validieren Sie es so:
- Analysieren Sie das Token mit einer SD-JWT-Bibliothek.
- Validieren Sie die erwarteten Werte und Sitzungsansprüche.
- Überprüfen Sie die DNS-Delegierung.
- Suchen Sie nach Metadaten des Ausstellers und rufen Sie JWKS ab.
- Überprüfen Sie kryptografische Signaturen und die Schlüsselbindung.
1. Token analysieren
Das Token verwendet das Format RFC 9901: Selective Disclosure JWT
(SD-JWT+KB). Verwenden Sie die entsprechenden Bibliotheken für Ihre Plattform, um das Token zu analysieren und zu validieren.
Für Node können Sie beispielsweise
@sd-jwt/core und
jose verwenden. In der Rohform sieht das so aus: ein vom Aussteller signiertes JWT, gefolgt von null oder mehr Offenlegungen und einem Key Binding JWT. Die einzelnen Komponenten sind durch eine Tilde getrennt:
<Issuer-signed EVT>~<Disclosure 1>~...~<Disclosure N>~<Key Binding JWT>
In der aktuellen Implementierung enthält das Token keine Offenlegungen
(<Issuer-signed EVT>~<Key Binding JWT>). Das kann sich in Zukunft jedoch ändern.
Decodieren Sie das Token mit der Bibliothek:
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;
Wenn verifier.example demo@provider.example bestätigt, sieht das decodierte Token so aus:
{
"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. Erwartete Werte und Sitzungsansprüche validieren
Prüfen Sie, ob die grundlegenden Werte in der Nutzlast mit den von Ihnen angegebenen und erwarteten Werten übereinstimmen:
email_verified: Musstruesein.email: Muss mit der im Formular eingereichten E‑Mail-Adresse übereinstimmen.aud(Zielgruppe): Muss mit dem Ursprung Ihrer Website übereinstimmen.nonce: Muss mit der in Ihrem Formular angegebenen Nonce übereinstimmen.iat(ausgestellt am) undexp(Ablaufdatum): Prüfen Sie, ob das Token innerhalb des gültigen Zeitraums liegt und nicht abgelaufen ist.
3. DNS-Delegierung überprüfen
Überprüfen Sie den DNS-Eintrag _email-verification für die E‑Mail-Adressdomain. Für demo@gmail.com fragen Sie beispielsweise den TXT-Eintrag _email-verification.gmail.com ab. Für diesen Anbieter gibt die Abfrage den Standort des Kontos zurück, also accounts.google.com.
$ dig +short TXT _email-verification.gmail.com
"iss=accounts.google.com"
Prüfen Sie, ob das Ausstellerschema https:// ist und ob https://<domain> mit
dem iss Anspruch im EVT übereinstimmt.
4. EVT-Signatur überprüfen
Rufen Sie die Metadaten des Ausstellers unter
https://<issuer>/.well-known/email-verification ab:
{
"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"]
}
Wenn die Metadaten ein Feld issuer enthalten, prüfen Sie, ob es bytegenau mit dem iss
Anspruch im EVT übereinstimmt. Rufen Sie das JSON Web Key Set unter jwks_uri ab.
Verwenden Sie Ihre SD-JWT-Bibliothek, um das Tokenpaket zu überprüfen. Die Bibliothek koordiniert die Validierung:
- Die Signatur des Ausstellers im EVT wird mit dem abgerufenen JWKS validiert.
- Die Signatur des Browsers im KB-JWT wird mit dem kurzlebigen öffentlichen Schlüssel in
cnf.jwkvalidiert. - Die Schlüsselbindung (
aud,nonceund der Digest-Hashsd_hash) wird überprüft.
Beispiel für die Bestätigungslogik 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");
}
Wenn alle Schritte erfolgreich sind, haben Sie die E‑Mail-Adresse beim Anbieter bestätigt. Wenn die Bestätigung fehlschlägt, senden Sie dem Nutzer über Ihren normalen Ablauf eine Bestätigungs-E‑Mail.
Fehlerbehebung
Wenn die Bestätigung fehlschlägt oder der Browser kein Token bereitstellt, prüfen Sie die folgenden häufigen Probleme:
Tokenfeld bei der Einreichung leer
- Registrierung für den Ursprungstest: Prüfen Sie, ob der
Origin-TrialHeader oder das<meta>Tag auf der Seite bereitgestellt wird und ob das Token nicht abgelaufen ist. Tokens, die vor der Verlängerung für Chrome 160 generiert wurden, laufen am 17. November 2026 ab. Bei Ursprungstests von Drittanbietern (Chrome 154 und höher) muss der registrierte Ursprung des Tests für den Aussteller derselbe sein (https://<issuer-domain>). Sie können den Status des Ursprungstests und das Ablaufdatum des Tokens auf einer Website in den Entwicklertools unter Anwendung > Frames > (entsprechenden Frame auswählen) > Ursprungstests prüfen. - Formular-Markup: Sowohl
<input type="email" autocomplete="email">als auch<input type="hidden" autocomplete="email-verification-token" nonce="...">müssen sich im selben<form>-Element befinden (nicht isoliert über Shadow DOM -Grenzen hinweg) undnoncedarf nicht leer sein. - Frühe Einreichung oder wiederverwendete Seite: Der Browser ruft das Token im Hintergrund ab, nachdem die E‑Mail-Adresse eingegeben oder automatisch ausgefüllt wurde. Wenn Sie das Formular einreichen, bevor die Anfrage abgeschlossen ist, bleibt das Token leer. Das kann passieren, wenn der Nutzer nach der Eingabe seiner E‑Mail-Adresse die Eingabetaste drückt, um das Formular einzureichen.
- Voraussetzungen für Browser und Anbieter: Der Nutzer muss im selben Browserprofil bei einem
teilnehmenden Anbieter angemeldet sein und in den Chrome-Einstellungen (
chrome://settings/contactInfo) die Option Bestätigte E‑Mail-Adresse aktiviert haben.
Überprüfung der Ausstellersignatur schlägt fehl
- Fehlender
kid-Header: Der Anspruchkid(Schlüssel-ID) im EVT-Header und JWKS ist optional (z. B. wirdkidin Gmail ausgelassen). Wennkidfehlt, durchlaufen Sie alle Kandidatenschlüssel in derjwks_urides Ausstellers, anstatt bei der Suche nach der Schlüssel-ID einen Fehler zu verursachen. - Algorithmuskennungen (
Ed25519undEdDSA): Ab Chrome 156 verwendet Chrome die vollständig angegebene AlgorithmuskennungEd25519(RFC 9864) fürcnf.jwk- undKB-JWT-Header, während Aussteller und Bibliotheken entwederEd25519oderEdDSA(zusammen mitES256) angeben können. Achten Sie darauf, dass Ihre JWK-Import- und Bestätigungslogik beide Kennungen akzeptiert. - Format des Ausstellerursprungs (
iss): Der DNS-TXT-Eintrag (_email-verification.<domain>) enthält einen einfachen Hostnamen (iss=accounts.issuer.example), während der EVT-iss-Anspruch ein vollständiger HTTPS- -Ursprung ist (https://accounts.issuer.example, ohne nachgestellten Schrägstrich). Fügen Sie dem DNS-Eintrag vor dem Vergleichhttps://voran.
Validierung der Schlüsselbindung (KB-JWT) schlägt fehl
- Nicht übereinstimmende oder abgelaufene Nonce: Prüfen Sie, ob die
noncein der<input>mit der aktiven Sitzungs-Nonce auf Ihrem Server übereinstimmt und nicht durch einen anderen Tab überschrieben oder durch eine vorherige Anfrage verwendet wurde. - Nicht übereinstimmende Zielgruppe (
aud): Der Anspruchaudist der HTTPS-Ursprung des Bestätigers (https://verifier.exampleohne Pfad oder nachgestellten Schrägstrich).
Vergleich des E‑Mail-Anspruchs (email) schlägt fehl
- Groß-/Kleinschreibung und Kanonisierung: In Chrome 156 und höher wird der Anspruch
emailbytegenau so zurückgegeben, wie er im Formular eingegeben wurde. In früheren Browserversionen oder bei Anbietern kann jedoch eine kanonisierte Adresse zurückgegeben werden (z. B.First.Last@example.comfürfirst.last@example.com). Verwenden Sie beim Abgleich desemail-Anspruchs des Tokens mit dem eingereichten Formularwert einen Vergleich ohne Berücksichtigung der Groß-/Kleinschreibung.