Để triển khai xác minh email trên trang web của bạn, hãy cập nhật đánh dấu biểu mẫu để yêu cầu mã thông báo và thêm xác thực phía máy chủ cho các mã thông báo đến.
Đăng ký bản dùng thử theo nguyên gốc
Các trang web xác minh phải định cấu hình bản dùng thử theo nguyên gốc trên trang web của mình.
Kể từ Chrome 154 bản dùng thử theo nguyên gốc của bên thứ ba được hỗ trợ với một lưu ý quan trọng: nguyên gốc đã đăng ký cho bản dùng thử phải là cùng trang web với tổ chức phát hành. Ví dụ:
- Miền của tổ chức phát hành:
issuer.example - Người đăng ký OT:
https://issuer.example - Nguyên gốc JavaScript:
https://issuer.example(hoặchttps://app.issuer.examplecó miền con khớp)
Định cấu hình các trường biểu mẫu
Thêm trường mã thông báo ẩn vào biểu mẫu gửi email:
<input
type="email"
name="email-address"
autocomplete="email">
<input
type="hidden"
name="token"
autocomplete="email-verification-token"
nonce="rAnD0m-VaLuE">
Yêu cầu về trường:
- Trường email: Đặt
type="email"vàautocomplete="email"để Chrome có thể tự động điền và nhận dạng địa chỉ. - Thuộc tính trường mã thông báo:
- Đặt
autocomplete="email-verification-token": Chrome xác định trường này trường để điền mã thông báo khi gửi. - Đặt
nonce="<VALUE>": Trang web phải cung cấp một nonce duy nhất liên kết với phiên để xác minh việc gửi biểu mẫu.
- Đặt
Xác thực mã thông báo xác minh email (EVT)
Khi người dùng gửi biểu mẫu, máy chủ của bạn sẽ nhận được địa chỉ email và mã thông báo từ trường ẩn. Trường mã thông báo trống cho biết trình duyệt hoặc nhà cung cấp không hỗ trợ EVP hoặc người dùng đã bỏ qua quy trình xác minh. Nếu trường hợp này xảy ra, hãy quay lại quy trình xác minh hiện có, chẳng hạn như gửi OTP hoặc đường liên kết đặc biệt.
Nếu có mã thông báo, hãy xác thực mã thông báo đó như sau:
- Phân tích cú pháp mã thông báo bằng thư viện SD-JWT.
- Xác thực các giá trị dự kiến và các yêu cầu về phiên.
- Xác minh việc uỷ quyền DNS.
- Khám phá siêu dữ liệu của tổ chức phát hành và tìm nạp JWKS.
- Xác minh chữ ký mật mã và liên kết khoá.
1. Phân tích cú pháp mã thông báo
Mã thông báo sử dụng định dạng RFC 9901: Selective Disclosure JWT
(SD-JWT+KB). Sử dụng các thư viện thích hợp cho nền tảng của bạn để phân tích cú pháp và xác thực mã thông báo.
Ví dụ: đối với Node, bạn có thể sử dụng
@sd-jwt/core và
jose. Ở dạng thô, mã thông báo này có dạng như sau: JWT do Tổ chức phát hành ký, tiếp theo là không hoặc nhiều Tiết lộ và kết thúc bằng JWT Liên kết khoá với mỗi thành phần được phân tách bằng dấu ngã:
<Issuer-signed EVT>~<Disclosure 1>~...~<Disclosure N>~<Key Binding JWT>
Trong quá trình triển khai hiện tại, mã thông báo chứa 0 tiết lộ
(<Issuer-signed EVT>~<Key Binding JWT>). Tuy nhiên, điều này có thể thay đổi trong tương lai.
Giải mã mã thông báo bằng thư viện:
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;
Nếu verifier.example xác minh demo@provider.example, thì mã thông báo đã giải mã sẽ có dạng tương tự như sau:
{
"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. Xác thực các giá trị dự kiến và các yêu cầu về phiên
Kiểm tra để đảm bảo rằng các giá trị cơ bản trong tải trọng khớp với các giá trị mà bạn cung cấp và dự kiến:
email_verified: Phải làtrue.email: Phải khớp với địa chỉ email được gửi trong biểu mẫu.aud(đối tượng): Phải khớp với nguyên gốc của trang web.nonce: Phải khớp với nonce được cung cấp trong biểu mẫu.iat(đã phát hành vào) vàexp(thời gian hết hạn): Xác nhận rằng mã thông báo nằm trong khoảng thời gian hợp lệ và chưa hết hạn.
3. Xác minh việc uỷ quyền DNS
Xác minh bản ghi DNS _email-verification cho miền địa chỉ email. Ví dụ: đối với demo@gmail.com, hãy truy vấn bản ghi TXT _email-verification.gmail.com. Đối với nhà cung cấp này, truy vấn sẽ trả về vị trí của nhà cung cấp tài khoản, tức là accounts.google.com.
$ dig +short TXT _email-verification.gmail.com
"iss=accounts.google.com"
Xác minh rằng lược đồ của tổ chức phát hành là https:// và https://<domain> khớp với
yêu cầu iss trong EVT.
4. Xác minh chữ ký EVT
Tìm nạp siêu dữ liệu khám phá của tổ chức phát hành từ
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"]
}
Nếu siêu dữ liệu bao gồm trường issuer, hãy xác minh rằng trường đó khớp với iss
yêu cầu trong EVT từng byte. Tìm nạp Bộ khoá web JSON từ jwks_uri.
Sử dụng thư viện SD-JWT để xác minh gói mã thông báo. Thư viện này điều phối quy trình xác thực:
- Xác thực chữ ký của tổ chức phát hành trên EVT dựa trên JWKS đã tìm nạp.
- Xác thực chữ ký của trình duyệt trên KB-JWT bằng khoá công khai tạm thời trong
cnf.jwk. - Xác minh liên kết khoá (
aud,noncevà hàm băm tóm tắtsd_hash).
Ví dụ về logic xác minh trong 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");
}
Nếu tất cả các bước đều thành công, bạn đã xác minh địa chỉ email với nhà cung cấp. Nếu không xác minh được, hãy quay lại quy trình gửi email xác nhận cho người dùng theo quy trình thông thường.
Khắc phục sự cố
Nếu không xác minh được hoặc trình duyệt không cung cấp mã thông báo, hãy kiểm tra các vấn đề thường gặp sau:
Trường mã thông báo bị trống khi gửi
- Đăng ký bản dùng thử theo nguyên gốc: Xác nhận rằng tiêu đề
Origin-Trialhoặc thẻ<meta>được phân phát trên trang và mã thông báo chưa qua ngày hết hạn (các mã thông báo được tạo trước khi tiện ích Chrome 160 hết hạn vào ngày 17 tháng 11 năm 2026). Đối với các bản dùng thử theo nguyên gốc của bên thứ ba (Chrome 154 trở lên), nguyên gốc dùng thử đã đăng ký phải là cùng trang web với tổ chức phát hành (https://<issuer-domain>). Bạn có thể kiểm tra trạng thái bản dùng thử theo nguyên gốc và thời gian hết hạn của mã thông báo trên một trang web trong Công cụ cho nhà phát triển trong phần Ứng dụng > Khung > (chọn khung có liên quan) > Bản dùng thử theo nguyên gốc. - Đánh dấu biểu mẫu: Cả
<input type="email" autocomplete="email">và<input type="hidden" autocomplete="email-verification-token" nonce="...">phải nằm trong cùng một phần tử<form>(không bị cô lập trên các ranh giới Shadow DOM ranh giới) vànoncekhông được trống. - Gửi sớm hoặc trang được dùng lại: Trình duyệt tìm nạp mã thông báo ở chế độ nền sau khi email được nhập hoặc tự động điền. Việc gửi trước khi yêu cầu hoàn tất sẽ khiến mã thông báo bị trống. Điều này có thể xảy ra nếu người dùng nhấn phím Return để gửi biểu mẫu sau khi nhập email.
- Điều kiện tiên quyết về trình duyệt và nhà cung cấp: Người dùng phải đăng nhập vào một
nhà cung cấp tham gia trong cùng một hồ sơ trình duyệt và bật Email
đã xác minh trong phần cài đặt Chrome (
chrome://settings/contactInfo).
Không xác minh được chữ ký của tổ chức phát hành
- Thiếu tiêu đề
kid: Yêu cầukid(Mã nhận dạng khoá) trong tiêu đề EVT và JWKS là không bắt buộc (ví dụ: Gmail bỏ quakid). Nếukidkhông có, hãy lặp lại tất cả các khoá ứng cử trongjwks_uricủa tổ chức phát hành thay vì không tìm được mã nhận dạng khoá. - Giá trị nhận dạng thuật toán (
Ed25519vàEdDSA): Kể từ Chrome 156, Chrome sử dụng giá trị nhận dạng thuật toánEd25519được chỉ định đầy đủ (RFC 9864) cho các tiêu đềcnf.jwkvàKB-JWT, trong khi các tổ chức phát hành và thư viện có thể chỉ địnhEd25519hoặcEdDSA(cùng vớiES256). Đảm bảo logic nhập và xác minh JWK của bạn chấp nhận cả hai giá trị nhận dạng. - Định dạng nguyên gốc của tổ chức phát hành (
iss): Bản ghi TXT DNS (_email-verification.<domain>) chứa tên máy chủ trần (iss=accounts.issuer.example), trong khi yêu cầuisscủa EVT là nguyên gốc HTTPS đầy đủ (https://accounts.issuer.example, không có dấu gạch chéo ở cuối). Thêm tiền tốhttps://vào giá trị bản ghi DNS trước khi so sánh.
Không xác thực được liên kết khoá (KB-JWT)
- Nonce không khớp hoặc đã hết hạn: Đảm bảo rằng
nonceđược hiển thị trong<input>khớp với nonce phiên hoạt động trên máy chủ của bạn và chưa bị ghi đè bởi một Tab khác hoặc được sử dụng bởi một yêu cầu trước đó. - Đối tượng (
aud) không khớp: Yêu cầuaudlà nguyên gốc HTTPS của trình xác minh (https://verifier.example, không có đường dẫn hoặc dấu gạch chéo ở cuối).
Không so sánh được yêu cầu email (email)
- Viết hoa và chuẩn hoá: Chrome 156 trở lên trả về yêu cầu
emailtừng byte như đã nhập trong biểu mẫu, nhưng các phiên bản trình duyệt hoặc nhà cung cấp trước đó có thể trả về địa chỉ đã chuẩn hoá (ví dụ:First.Last@example.comchofirst.last@example.com). Sử dụng quy trình so sánh không phân biệt chữ hoa chữ thường khi so khớp yêu cầuemailcủa mã thông báo với giá trị biểu mẫu đã gửi.