Để biết thêm thông tin chi tiết, bạn có thể xem mã bản minh họa nhà cung cấp dịch vụ email mô phỏng và tham khảo các bước của tổ chức phát hành trong đề xuất API Xác minh email và Giao thức Xác minh email.
Là một tổ chức phát hành, bạn không cần đăng ký bản dùng thử theo nguyên gốc hoặc cung cấp mã thông báo vì trang web của bên Relying Party sẽ kích hoạt hành vi của trình duyệt. Đảm bảo rằng các điểm cuối của bạn được định cấu hình để phản hồi những yêu cầu đó.
Định cấu hình tính năng khám phá tổ chức phát hành
Để cho phép trình duyệt tự động khám phá các điểm cuối xác minh khi một địa chỉ email thuộc miền của bạn được chọn, hãy hiển thị cấu hình của bạn bằng DNS và điểm cuối HTTP .well-known.
Thiết lập bản ghi uỷ quyền DNS
Định cấu hình bản ghi DNS TXT trên miền email của bạn để uỷ quyền xác minh cho giá trị nhận dạng của tổ chức phát hành. Các giá trị nhận dạng này có thể sử dụng cùng một miền, tuỳ thuộc vào cơ sở hạ tầng của bạn.
Định dạng bản ghi: _email-verification.<email-domain>
Ví dụ về tệp vùng:
_email-verification.example.com IN TXT "iss=accounts.issuer.example"
Giá trị iss= phải là tên máy chủ lưu trữ chuẩn, viết thường (ví dụ: iss=accounts.issuer.example) không có lược đồ (https://), cổng, đường dẫn hoặc ký tự viết hoa. Chrome từ chối các bản ghi có chứa thành phần không phải tên máy chủ.
Lưu trữ một điểm cuối .well-known/email-verification
Lưu trữ tệp siêu dữ liệu JSON trên miền của công ty phát hành theo đường dẫn /.well-known/.
Tệp này trình bày các chức năng phát hành và thuật toán ký mật mã mà cơ sở hạ tầng của bạn hỗ trợ.
Điểm cuối: https://<issuer-domain>/.well-known/email-verification
Ví dụ về phản hồi:
{
"issuer": "https://accounts.issuer.example",
"issuance_endpoint": "https://accounts.issuer.example/email-verification/issuance",
"jwks_uri": "https://accounts.issuer.example/.well-known/vc-public-jwks",
"signing_alg_values_supported": ["Ed25519", "EdDSA", "ES256"]
}
Thuộc tính siêu dữ liệu:
issuer: Nguồn gốc của đơn vị phát hành (https://<issuer-domain>, không có dấu gạch chéo ở cuối). Phải khớp từng byte với nguồn gốc phân phát tệp siêu dữ liệu.issuance_endpoint: URL loại HTTPS nhận các yêu cầu phát hành mã thông báoPOST.jwks_uri: URL loại HTTPS phân phát Bộ khoá web JSON công khai (JWKS).signing_alg_values_supported: Mảng các thuật toán ký JWS được hỗ trợ.
Lưu trữ một điểm cuối .well-known/web-identity
Có thể bạn đã triển khai thêm một tài nguyên JSON .well-known trong Federated Credentials (FedCM) API. Tài nguyên này cung cấp các đường liên kết đến điểm cuối tài khoản và URL đăng nhập của bạn.
Điểm cuối: https://<domain>/.well-known/web-identity
Ví dụ về phản hồi:
{
"accounts_endpoint": "https://accounts.issuer.example/accounts",
"login_url": "https://accounts.issuer.example/login"
}
Sử dụng điểm cuối tài khoản
Điểm cuối tài khoản từ FedCM API cung cấp danh sách các tài khoản đã đăng nhập tại thời điểm này. Ví dụ sau đây cho thấy một phản hồi tối thiểu. Để biết thêm thông tin, hãy tham khảo hướng dẫn triển khai nhà cung cấp danh tính.
Điểm cuối: như được chỉ định trong .well-known/web-identity
Sau đây là ví dụ về phản hồi:
{
"accounts": [
{
"id": "demo-example",
"name": "Demo User",
"email": "demo@example.com",
"given_name": "Demo"
}
]
}
Tích hợp với Login Status API
Người dùng phải có một phiên hoạt động với nhà cung cấp và bạn phải báo hiệu điều đó cho trình duyệt bằng Login Status API (API Trạng thái đăng nhập).
Khi người dùng đăng nhập hoặc đăng xuất thành công, hãy phân phát tiêu đề phản hồi HTTP phù hợp:
Set-Login: logged-in
Set-Login: logged-out
Ngoài ra, hãy cập nhật trạng thái bằng JavaScript trong bối cảnh ứng dụng web:
navigator.login.setStatus("logged-in");
navigator.login.setStatus("logged-out");
Xử lý yêu cầu phát hành
issuance_endpoint của bạn nhận được một yêu cầu application/json POST chứa khoá email và tiêu đề Chữ ký thông báo HTTP cho Signature, Signature-Input và Signature-Key.
Sử dụng thư viện hỗ trợ tiêu đề có cấu trúc và Chữ ký thông báo HTTP cho môi trường của bạn. Trong Node.js, bạn có thể dùng structured-headers và http-message-sig.
Định dạng yêu cầu đầy đủ:
POST /email-verification/issuance HTTP/1.1
Host: provider.example
Accept: application/json
Content-Digest: sha-256=:aBc123aBc123aBc123aBc123aBc123=:
Content-Type: application/json
Sec-Fetch-Dest: email-verification
Signature: sig=:+dEf567dEf567/dEf567dEf567dEf567/dEf567==:
Signature-Input: sig=("@method" "@authority" "@path" "content-digest" "signature-key");created=1786455840
Signature-Key: sig=hwk;alg="Ed25519";crv="Ed25519";kty="OKP";x="gHi890_gHi890_gHi890"
{email: "demo@example.com"}
Phân tích cú pháp và xác thực yêu cầu:
- Xác thực phiên: Xác thực cookie phiên của bên thứ nhất được gửi cùng với yêu cầu. Người dùng phải được xác thực.
- Tiêu đề
Sec-Fetch-Dest: Đặt thànhemail-verification. - Chữ ký thông báo HTTP: Xác minh chữ ký yêu cầu bằng khoá công khai tạm thời trong
Signature-Keyvà xác thựcContent-Digest. Từ Chrome 156, tiêu đềSignature-Keysẽ bao gồmalg="Ed25519"trong các tham sốhwk; chấp nhận"Ed25519"và"EdDSA", đồng thời cho phép các phiên bản Chrome cũ bỏ quaalg. - Tải trọng: Nội dung JSON chứa chuỗi
emailđược yêu cầu để xác minh.
Phản hồi về việc phát hành
Sau khi xác thực thành công phiên và mã thông báo yêu cầu, hãy tạo một JWT Tiết lộ có chọn lọc (SD-JWT) đã ký và được trả về dưới dạng JSON bằng cách sử dụng các thư viện thích hợp cho nền tảng của bạn. Ví dụ: đối với Node, bạn có thể sử dụng @sd-jwt/core và jose.
Định dạng tải trọng thô sẽ có dạng như sau:
{
"iss": "https://accounts.issuer.example",
"iat": 1780272000,
"exp": 1780272300,
"cnf": {
"jwk": {
"kty": "EC",
"crv": "P-256",
"x": "pUbLiCKeY123pUbLiCKeY123pUbLiCKeY123",
"y": "pUbLiCKeY456pUbLiCKeY456pUbLiCKeY456"
}
},
"email": "demo@example.com",
"email_verified": true
}
Tạo, ký và trả về mã thông báo:
import { importJWK, CompactSign } from "jose";
import { SDJwtInstance } from "@sd-jwt/core";
import crypto from "node:crypto";
// Issuer private key from secure storage
const privateKey = await importJWK(PRIVATE_KEY_JWK, "EdDSA");
const origin = url.origin;
const currentTime = Math.floor(Date.now() / 1000);
const evtPayload = {
iss: origin,
iat: currentTime,
exp: currentTime + 300, // 5 minutes
cnf: {
jwk: browserJwk,
},
email: payload.email, // exactly as received in payload
email_verified: true,
};
const sdJwt = new SDJwtInstance({
signer: async (data) => {
const [headerB64, payloadB64] = data.split(".");
const header = JSON.parse(Buffer.from(headerB64, "base64url").toString());
const payload = Buffer.from(payloadB64, "base64url");
const signed = await new CompactSign(payload).setProtectedHeader(header).sign(privateKey);
return signed.split(".").pop()!;
},
signAlg: "EdDSA",
hasher: async (data, alg) => {
const nodeAlg = alg.replace("-", "");
return new Uint8Array(crypto.createHash(nodeAlg).update(data).digest());
},
hashAlg: "sha-256",
saltGenerator: async () => crypto.randomBytes(16).toString("base64url"),
});
const issuanceToken = await sdJwt.issue(evtPayload, undefined, {
header: {
alg: "EdDSA",
kid: PRIVATE_KEY_JWK.kid,
typ: "evt+jwt",
},
});
return sendResponse({ issuance_token: issuanceToken, }, 200);
Phần nội dung phản hồi thu được sẽ có dạng như sau:
{
"issuance_token": "tOkEn123tOkEn123tOkEn123...~"
}
Sau khi bạn tạo và ký mã xác minh email, trình duyệt sẽ chuyển mã này đến trang web của bên xác minh để xác thực.
Khắc phục sự cố
Nếu trình duyệt không liên hệ với các điểm cuối của bạn hoặc từ chối mã thông báo đã phát hành, hãy kiểm tra các vấn đề thường gặp sau:
Trình duyệt không bao giờ gọi accounts_endpoint hoặc issuance_endpoint
- Chưa đặt trạng thái đăng nhập: Chrome chỉ truy vấn các điểm cuối của bạn nếu biết người dùng đã đăng nhập. Đảm bảo quy trình đăng nhập của bạn đặt tiêu đề HTTP
Set-Login: logged-inhoặc gọinavigator.login.setStatus("logged-in"). - Cookie của phiên bị chặn (
SameSite=None): Trình duyệt tìm nạpaccounts_endpointvàissuance_endpointcủa bạn từ một bên Relying Party trên một trang web khác. Vì đây là các yêu cầu trên nhiều trang web, nên cookie của phiên của bạn phải bao gồmSameSite=None; Secure. CookieSameSite=Laxhoạt động khi kiểm thử trên trình xác minh cùng trang web, nhưng bị bỏ qua trên các yêu cầu trên nhiều trang web. - Không khớp tài khoản hoặc thông tin khám phá: Xác minh rằng
_email-verification.<email-domain>trả về một bản ghi TXT duy nhất có tên máy chủ chuẩn viết thường (iss=<issuer-domain>, không cóhttps://, cổng, đường dẫn hoặc ký tự viết hoa), cả hai điểm cuối.well-knownđều trả vềContent-Type: application/json,.well-known/email-verificationcóissuerkhớp vớihttps://<issuer-domain>từng byte và phản hồiaccounts_endpointbao gồm một tài khoản cóemailkhớp với địa chỉ đã nhập. - Thuật toán ký không được hỗ trợ trong
.well-known/email-verification: Chrome 154 và 155 yêu cầu"EdDSA"trongsigning_alg_values_supported, trong khi Chrome 156 trở lên và thông số kỹ thuật của IETF hỗ trợ"Ed25519". Quảng cáo cả["Ed25519", "EdDSA"]trong quá trình chuyển đổi để Bản ổn định của Chrome không từ chối siêu dữ liệu khám phá của bạn.
Không xác thực được yêu cầu phát hành
- Cách viết tiêu đề
Sec-Fetch-Dest: Chrome 154 trở lên gửiSec-Fetch-Dest: email-verification(có dấu gạch nối), trong khi Chrome 153 gửiemailverification(không có dấu gạch nối). Chấp nhận cả hai giá trị trong quá trình triển khai. - Chữ ký thông báo HTTP (
@authority) không khớp sau một proxy: Khi xác minh chữ ký RFC 9421, thành phần@authoritysẽ phản ánh máy chủ công khai. Nếu máy chủ của bạn nằm sau một proxy ngược hoặc trình cân bằng tải, hãy tạo lại URL xác minh bằngX-Forwarded-Host(hoặc nguồn gốc công khai của bạn) thay vì tên máy chủ nội bộ, đồng thời tính toánContent-Digesttrên các byte nội dung yêu cầu thô trước khi phân tích cú pháp JSON.
Trình duyệt từ chối issuance_token được trả về
- Xác nhận quyền sở hữu
emailđã sửa đổi hoặc chuẩn hoá: Kể từ Chrome 156, trình duyệt sẽ kiểm tra để đảm bảo xác nhận quyền sở hữu EVTemailkhớp vớiemailđược yêu cầu theo từng byte. Nếu phần phụ trợ của bạn chuẩn hoá địa chỉ theo định dạng tài khoản chuẩn (chẳng hạn như trả vềFirst.Last@example.comkhifirst.LAST@example.comđược yêu cầu), Chrome sẽ loại bỏ mã thông báo. So khớp yêu cầu với tài khoản của người dùng, nhưng trả về chính xác chuỗiemailnhận được trong nội dung yêu cầu. - Thiếu dấu ngã ở cuối (
~): Ngay cả khi không có thông tin công bố,issuance_tokenphải là một SD-JWT hợp lệ kết thúc bằng dấu ngã ở cuối (<Issuer-signed-JWT>~) để trình duyệt có thể thêm<KB-JWT>. isshoặccnf.jwkkhông khớp: Đảm bảo thông báo xác nhận quyền sở hữuisscủa EVT là nguồn gốc HTTPS chính xác (https://<issuer-domain>, không có dấu gạch chéo ở cuối) khớp với siêu dữ liệu.well-known/email-verificationcủa bạn vàcnf.jwknhúng khoá công khai tạm thời của trình duyệt từ tiêu đềSignature-Key.