หากต้องการใช้การยืนยันอีเมลในเว็บไซต์ ให้อัปเดตมาร์กอัปของแบบฟอร์มเพื่อขอโทเค็นและเพิ่มการตรวจสอบฝั่งเซิร์ฟเวอร์สำหรับโทเค็นขาเข้า
ลงทะเบียนเข้าร่วมช่วงทดลองใช้จากต้นทาง
เว็บไซต์ที่ยืนยันแล้วต้องมีการกำหนดค่าช่วงทดลองใช้จากต้นทางในเว็บไซต์
- ลงทะเบียนเข้าร่วมช่วงทดลองใช้จากต้นทาง
- แสดงโทเค็นช่วงทดลองใช้จากต้นทาง
Chrome 154 เป็นต้นไปรองรับ ช่วงทดลองใช้จากต้นทางของบุคคลที่สาม โดยมี ข้อควรระวังที่สำคัญคือ ต้นทางที่ลงทะเบียนสำหรับช่วงทดลองใช้ต้องเป็นเว็บไซต์เดียวกันกับ ผู้ออก เช่น
- โดเมนของผู้ออก:
issuer.example - ผู้จดทะเบียน:
https://issuer.example - ต้นทาง JavaScript:
https://issuer.example(หรือhttps://app.issuer.exampleที่มีการจับคู่โดเมนย่อย)
กำหนดค่าฟิลด์ในแบบฟอร์ม
เพิ่มฟิลด์โทเค็นที่ซ่อนไว้ในแบบฟอร์มส่งอีเมล โดยทำดังนี้
<input
type="email"
name="email-address"
autocomplete="email">
<input
type="hidden"
name="token"
autocomplete="email-verification-token"
nonce="rAnD0m-VaLuE">
ข้อกำหนดของฟิลด์
- ฟิลด์อีเมล: ตั้งค่า
type="email"และautocomplete="email"เพื่อให้ Chrome ป้อนข้อความอัตโนมัติและจดจำที่อยู่อีเมลได้ - แอตทริบิวต์ของฟิลด์โทเค็น:
- ตั้งค่า
autocomplete="email-verification-token": Chrome จะระบุฟิลด์นี้ เพื่อป้อนโทเค็นเมื่อส่ง - ตั้งค่า
nonce="<VALUE>": เว็บไซต์ต้องระบุ Nonce ที่ไม่ซ้ำกันซึ่งผูกกับเซสชัน เพื่อยืนยันการส่งแบบฟอร์ม
- ตั้งค่า
ตรวจสอบโทเค็นการยืนยันอีเมล (EVT)
เมื่อผู้ใช้ส่งแบบฟอร์ม เซิร์ฟเวอร์ของคุณจะได้รับอีเมลและโทเค็นจากฟิลด์ที่ซ่อนไว้ ฟิลด์โทเค็นที่ว่างเปล่าบ่งชี้ว่าเบราว์เซอร์หรือผู้ให้บริการไม่รองรับ EVP หรือผู้ใช้ข้ามการยืนยัน หากเกิดกรณีนี้ ให้กลับไปใช้กระบวนการยืนยันตัวตนที่มีอยู่ เช่น การส่ง OTP หรือ Magic Link
หากมีโทเค็น ให้ตรวจสอบโทเค็นดังนี้
- แยกวิเคราะห์โทเค็นโดยใช้ไลบรารี SD-JWT
- ตรวจสอบค่าที่คาดไว้และการอ้างสิทธิ์ในเซสชัน
- ยืนยันการมอบสิทธิ์ DNS
- ค้นหาข้อมูลเมตาของผู้ออกและดึงข้อมูล JWKS
- ยืนยันลายเซ็นการเข้ารหัสและการผูกคีย์
1. แยกวิเคราะห์โทเค็น
โทเค็นใช้รูปแบบ RFC 9901: Selective Disclosure JWT
(SD-JWT+KB) ใช้ไลบรารีที่เหมาะสมกับแพลตฟอร์มของคุณเพื่อแยกวิเคราะห์และตรวจสอบโทเค็น
เช่น สำหรับ Node คุณสามารถใช้
@sd-jwt/core และ
jose ในรูปแบบดิบ โทเค็นจะมีลักษณะดังนี้ JWT ที่ลงนามโดยผู้ออก ตามด้วยการเปิดเผยข้อมูลตั้งแต่ 0 รายการขึ้นไป และปิดท้ายด้วย KB-JWT โดยแต่ละคอมโพเนนต์จะคั่นด้วยเครื่องหมายตัวหนอน
<Issuer-signed EVT>~<Disclosure 1>~...~<Disclosure N>~<Key Binding JWT>
ในการใช้งานปัจจุบัน โทเค็นจะไม่มีการเปิดเผยข้อมูล
(<Issuer-signed EVT>~<Key Binding JWT>) แต่อาจมีการเปลี่ยนแปลงใน
อนาคต
ถอดรหัสโทเค็นด้วยไลบรารี
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;
หาก verifier.example ยืนยัน demo@provider.example โทเค็นที่ถอดรหัสแล้วจะมีลักษณะคล้ายกับตัวอย่างต่อไปนี้
{
"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. ตรวจสอบค่าที่คาดไว้และการอ้างสิทธิ์ในเซสชัน
ตรวจสอบว่าค่าพื้นฐานในเพย์โหลดตรงกับค่าที่คุณระบุและค่าที่คาดไว้
email_verified: ต้องเป็นtrueemail: ต้องตรงกับอีเมลที่ส่งในแบบฟอร์มaud(ผู้รับ): ต้องตรงกับต้นทางของเว็บไซต์nonce: ต้องตรงกับ Nonce ที่ระบุในแบบฟอร์มiat(ออกเมื่อ) และexp(หมดอายุ): ยืนยันว่าโทเค็นอยู่ในช่วงเวลาที่ใช้งานได้และยังไม่หมดอายุ
3. ยืนยันการมอบสิทธิ์ DNS
ยืนยันระเบียน DNS _email-verification สำหรับโดเมนอีเมล เช่น สำหรับ demo@gmail.com ให้ค้นหาระเบียน TXT _email-verification.gmail.com สำหรับผู้ให้บริการรายนี้ การค้นหาจะแสดงตำแหน่งของผู้ให้บริการบัญชี ซึ่งก็คือ accounts.google.com
$ dig +short TXT _email-verification.gmail.com
"iss=accounts.google.com"
ยืนยันว่ารูปแบบของผู้ออกคือ https:// และ https://<domain> ตรงกับ
การอ้างสิทธิ์ iss ใน EVT
4. ยืนยันลายเซ็น EVT
ดึงข้อมูลเมตาการค้นพบของผู้ให้บริการจาก
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"]
}
หากข้อมูลเมตามีฟิลด์ issuer ให้ยืนยันว่าฟิลด์ดังกล่าวตรงกับการอ้างสิทธิ์ iss
ใน EVT แบบไบต์ต่อไบต์ ดึงข้อมูล JSON Web Key Set จาก jwks_uri
ใช้ไลบรารี SD-JWT เพื่อยืนยันแพ็กเกจโทเค็น ไลบรารีจะประสานงานการตรวจสอบดังนี้
- ตรวจสอบลายเซ็นของผู้ออกใน EVT กับ JWKS ที่ดึงข้อมูลมา
- ตรวจสอบลายเซ็นของเบราว์เซอร์ใน KB-JWT โดยใช้คีย์สาธารณะชั่วคราวใน
cnf.jwk - ยืนยันการผูกคีย์ (
aud,nonceและแฮชไดเจสต์sd_hash)
ตรรกะการยืนยันตัวอย่างใน 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");
}
หากทุกขั้นตอนสำเร็จ คุณจะยืนยันอีเมลกับผู้ให้บริการได้ หากการยืนยันไม่สำเร็จ ให้กลับไปส่งอีเมลยืนยันไปยังผู้ใช้โดยใช้โฟลว์ปกติ
การแก้ปัญหา
หากการยืนยันไม่สำเร็จหรือเบราว์เซอร์ไม่แสดงโทเค็น ให้ตรวจสอบปัญหาที่พบบ่อยต่อไปนี้
ฟิลด์โทเค็นว่างเปล่าเมื่อส่ง
- การลงทะเบียนช่วงทดลองใช้จากต้นทาง: ยืนยันว่ามีการแสดงส่วนหัว
Origin-Trialหรือ<meta>แท็กในหน้าเว็บ และโทเค็นยังไม่เลยวันที่หมดอายุ (โทเค็นที่สร้างขึ้นก่อนการขยายระยะเวลา Chrome 160 จะหมดอายุในวันที่ 17 พฤศจิกายน 2026) สำหรับช่วงทดลองใช้จากต้นทางของบุคคลที่สาม (Chrome 154 ขึ้นไป) ต้นทางที่ลงทะเบียนสำหรับช่วงทดลองใช้ ต้องเป็นเว็บไซต์เดียวกันกับผู้ออก (https://<issuer-domain>) คุณสามารถ ตรวจสอบสถานะช่วงทดลองใช้จากต้นทางและการหมดอายุของโทเค็นในเว็บไซต์ได้ใน DevTools ในส่วน แอปพลิเคชัน > เฟรม > (เลือกเฟรมที่เกี่ยวข้อง) > ช่วงทดลองใช้ จากต้นทาง - มาร์กอัปของแบบฟอร์ม: ทั้ง
<input type="email" autocomplete="email">และ<input type="hidden" autocomplete="email-verification-token" nonce="...">ต้องอยู่ในองค์ประกอบ<form>เดียวกัน (ไม่แยกกันตามขอบเขต Shadow DOM boundaries) และnonceต้องไม่ว่างเปล่า - การส่งก่อนกำหนดหรือหน้าเว็บที่ใช้ซ้ำ: เบราว์เซอร์จะดึงข้อมูลโทเค็นใน เบื้องหลังหลังจากป้อนหรือป้อนข้อความอัตโนมัติในอีเมล การส่งก่อนที่คำขอจะเสร็จสมบูรณ์จะทำให้โทเค็นว่างเปล่า กรณีนี้อาจเกิดขึ้นหากผู้ใช้กด Return เพื่อส่งแบบฟอร์มหลังจากป้อนอีเมล
- ข้อกำหนดเบื้องต้นของเบราว์เซอร์และผู้ให้บริการ: ผู้ใช้ต้องลงชื่อเข้าใช้
ผู้ให้บริการที่เข้าร่วมในโปรไฟล์เบราว์เซอร์เดียวกัน และเปิดใช้ อีเมล
ที่ยืนยันแล้ว ในการตั้งค่า Chrome (
chrome://settings/contactInfo)
การยืนยันลายเซ็นของผู้ออกไม่สำเร็จ
- ไม่มีส่วนหัว
kid: การอ้างสิทธิ์kid(รหัสคีย์) ในส่วนหัว EVT และ JWKS เป็นตัวเลือก (เช่น Gmail ละเว้นkid) หากไม่มีkidให้ วนซ้ำคีย์ผู้สมัครทั้งหมดในjwks_uriของผู้ออกแทนที่จะ ล้มเหลวในการค้นหารหัสคีย์ - ตัวระบุอัลกอริทึม (
Ed25519และEdDSA): ตั้งแต่ Chrome 156 เป็นต้นไป Chrome จะใช้ตัวระบุอัลกอริทึมEd25519ที่ระบุไว้อย่างครบถ้วน (RFC 9864) สำหรับส่วนหัวcnf.jwkและKB-JWTในขณะที่ผู้ออกและไลบรารีอาจระบุEd25519หรือEdDSA(พร้อมกับES256) ตรวจสอบว่าตรรกะการนำเข้าและการยืนยัน JWK ยอมรับตัวระบุทั้ง 2 รายการ - รูปแบบต้นทางของผู้ออก (
iss): ระเบียน DNS TXT (_email-verification.<domain>) มีชื่อโฮสต์เปล่า (iss=accounts.issuer.example) ในขณะที่การอ้างสิทธิ์issของ EVT เป็นต้นทาง HTTPS แบบเต็ม (https://accounts.issuer.exampleโดยไม่มีเครื่องหมายทับปิดท้าย) เติมคำนำหน้าhttps://ให้กับค่าระเบียน DNS ก่อนทำการเปรียบเทียบ
การตรวจสอบการผูกคีย์ (KB-JWT) ไม่สำเร็จ
- Nonce ไม่ตรงกันหรือหมดอายุ: ตรวจสอบว่า
nonceที่แสดงใน<input>ตรงกับ Nonce ของเซสชันที่ใช้งานอยู่ในเซิร์ฟเวอร์ และไม่ได้ถูกเขียนทับ โดยแท็บอื่นหรือใช้ไปกับคำขอก่อนหน้า - ผู้รับ (
aud) ไม่ตรงกัน: การอ้างสิทธิ์audคือต้นทาง HTTPS ของเครื่องมือตรวจสอบ (https://verifier.exampleโดยไม่มีเส้นทางหรือเครื่องหมายทับปิดท้าย)
การเปรียบเทียบการอ้างสิทธิ์อีเมล (email) ไม่สำเร็จ
- ตัวพิมพ์เล็กและตัวพิมพ์ใหญ่และการทำให้เป็นมาตรฐาน: Chrome 156 ขึ้นไปจะแสดงการอ้างสิทธิ์
emailแบบไบต์ต่อไบต์ตามที่ป้อนในแบบฟอร์ม แต่เบราว์เซอร์เวอร์ชันก่อนหน้าหรือผู้ให้บริการอาจแสดงที่อยู่ที่ทำให้เป็นมาตรฐานแล้ว (เช่นFirst.Last@example.comสำหรับfirst.last@example.com) ใช้การเปรียบเทียบแบบไม่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่เมื่อจับคู่การอ้างสิทธิ์emailของโทเค็นกับค่าแบบฟอร์มที่ส่ง