لتنفيذ عملية تأكيد عنوان البريد الإلكتروني على موقعك الإلكتروني، عليك تعديل ترميز النموذج لطلب الرمز المميّز وإضافة التحقّق على صعيد الخادم للرموز المميّزة الواردة.
التسجيل في مرحلة التجربة والتقييم
يجب أن تكون المواقع الإلكترونية التي تُجري عملية التحقّق قد ضبطت مرحلة التجربة والتقييم على موقعها الإلكتروني.
اعتبارًا من الإصدار 154 من Chrome، أصبحت المراحل التجريبية والتقييمية من المصدر التابعة لجهات خارجية متاحة مع تحذير مهم: يجب أن يكون المصدر المسجَّل للمرحلة التجريبية والتقييمية من الموقع الإلكتروني نفسه لجهة الإصدار. على سبيل المثال:
- نطاق جهة الإصدار:
issuer.example - صاحب التسجيل في OT:
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 هذا الحقل لتعبئة الرمز المميّز عند إرسال النموذج. - Set
nonce="<VALUE>": يجب أن يوفّر الموقع الإلكتروني رقمًا فريدًا يُستخدم مرة واحدة ومرتبطًا بالجلسة للتحقّق من إرسال النموذج.
- اضبط القيمة على
التحقّق من صحة الرمز المميّز لتأكيد عنوان البريد الإلكتروني (EVT)
عندما يرسل المستخدم النموذج، يتلقّى خادمك عنوان البريد الإلكتروني والرمز المميّز من الحقل المخفي. يشير حقل الرمز المميز الفارغ إلى أنّ المتصفّح أو مقدّم الخدمة لا يتيح ميزة EVP، أو أنّ المستخدم تخطّى عملية التحقّق. في حال حدوث ذلك، عليك الرجوع إلى عملية التحقّق الحالية، مثل إرسال كلمة مرور صالحة لمرة واحدة أو رابط سحري.
إذا كان الرمز المميّز متوفّرًا، تحقَّق من صحته على النحو التالي:
- حلِّل الرمز المميّز باستخدام مكتبة SD-JWT.
- التحقّق من صحة القيم المتوقّعة ومطالبات الجلسة
- التحقّق من تفويض نظام أسماء النطاقات
- استكشاف البيانات الوصفية لجهة الإصدار واسترداد JWKS
- التحقّق من التوقيعات المشفّرة وربط المفاتيح
1. تحليل الرمز المميّز
يستخدم الرمز المميّز تنسيق RFC 9901: Selective Disclosure JWT
(SD-JWT+KB). استخدِم المكتبات المناسبة لنظامك الأساسي من أجل تحليل الرمز المميّز والتحقّق من صحته.
على سبيل المثال، بالنسبة إلى Node، يمكنك استخدام
@sd-jwt/core وjose. في شكله الأولي، يبدو هذا على النحو التالي: رمز JWT موقَّع من جهة الإصدار، متبوعًا بصفر أو أكثر من الإفصاحات، وينتهي برمز 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: يجب أن تكون القيمةtrue. -
email: يجب أن يتطابق مع عنوان البريد الإلكتروني الذي تم إرساله في النموذج. -
aud(الجمهور): يجب أن يتطابق مع مصدر موقعك الإلكتروني. -
nonce: يجب أن يتطابق مع الرمز الفريد المقدَّم في النموذج. -
iat(تاريخ الإصدار) وexp(تاريخ انتهاء الصلاحية): تأكَّد من أنّ الرمز المميّز يقع ضمن الفترة الزمنية الصالحة ولم تنتهِ صلاحيته.
3- التحقّق من تفويض نظام أسماء النطاقات
تحقَّق من سجلّ نظام أسماء النطاقات _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 من 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). بالنسبة إلى مراحل التجربة والتقييم التابعة لجهات خارجية (الإصدار 154 من Chrome والإصدارات الأحدث)، يجب أن يكون مصدر التجربة المسجَّل هو نفسه الموقع الإلكتروني لجهة الإصدار (https://<issuer-domain>). يمكنك فحص حالة مرحلة التجربة والتقييم وانتهاء صلاحية الرمز المميّز على موقع إلكتروني في "أدوات مطوّري البرامج" ضمن التطبيق > الإطارات > (اختيار الإطار ذي الصلة) > مراحل التجربة والتقييم. - ترميز النموذج: يجب أن يكون كل من
<input type="email" autocomplete="email">و<input type="hidden" autocomplete="email-verification-token" nonce="...">ضمن عنصر<form>نفسه (وليس بشكل منفصل على مستوى حدود Shadow DOM)، ويجب ألا يكونnonceفارغًا. - الإرسال المبكر أو الصفحة المُعاد استخدامها: يجلب المتصفّح الرمز المميّز في الخلفية بعد إدخال عنوان البريد الإلكتروني أو ملئه تلقائيًا. سيؤدي إرسال الرمز المميّز قبل اكتمال الطلب إلى تركه فارغًا. يمكن أن يحدث هذا إذا ضغط المستخدم على "Return" (رجوع) لإرسال النموذج بعد إدخال بريده الإلكتروني.
- المتطلبات الأساسية للمتصفّح ومقدّم الخدمة: يجب أن يكون المستخدم مسجّلاً الدخول إلى مقدّم خدمة مشارك في ملف المتصفّح نفسه وأن يكون خيار البريد الإلكتروني الذي تم التحقّق منه مفعّلاً في إعدادات Chrome (
chrome://settings/contactInfo).
تعذُّر التحقّق من توقيع جهة الإصدار
- عدم توفّر عنوان
kid: إنّ مطالبةkid(معرّف المفتاح) في عنوان EVT وJWKS اختيارية (على سبيل المثال، يحذف Gmailkid). في حال عدم توفّرkid، يمكنك تكرار جميع المفاتيح المرشحة فيjwks_uriلجهة الإصدار بدلاً من تعذُّر البحث عن معرّف المفتاح. - معرّفات الخوارزميات (
Ed25519وEdDSA): بدءًا من الإصدار 156 من Chrome، يستخدم Chrome معرّف الخوارزميةEd25519المحدّد بالكامل (RFC 9864) لرأسَيcnf.jwkوKB-JWT، بينما قد تحدّد جهات الإصدار والمكتبات إماEd25519أوEdDSA(إلى جانبES256). يُرجى التأكّد من أنّ منطق استيراد والتحقّق من JWK يقبل كلا المعرّفَين. - تنسيق مصدر جهة الإصدار (
iss): يحتوي سجلّ TXT لنظام أسماء النطاقات (_email-verification.<domain>) على اسم مضيف مجرّد (iss=accounts.issuer.example)، بينما يكون الادعاءissفي EVT مصدر HTTPS كاملاً (https://accounts.issuer.example، بدون شرطة مائلة لاحقة). أضِف البادئةhttps://إلى قيمة سجلّ نظام أسماء النطاقات قبل المقارنة.
تعذُّر التحقّق من صحة ربط المفتاح (KB-JWT)
- عدم تطابق الرمز الخاص أو انتهاء صلاحيته: تأكَّد من أنّ الرمز
nonceالمعروض في<input>يتطابق مع الرمز الخاص للجلسة النشطة على خادمك ولم يتم استبداله بعلامة تبويب أخرى أو استخدامه في طلب سابق. - عدم تطابق الجمهور (
aud): المطالبةaudهي مصدر HTTPS الخاص بجهة التحقّق (https://verifier.example، بدون مسار أو شرطة مائلة لاحقة).
تعذُّر مقارنة مطالبة البريد الإلكتروني (email)
- حالة الأحرف والتوحيد: يعرض الإصدار 156 من Chrome والإصدارات الأحدث مطالبة
emailبايت ببايت كما تم إدخالها في النموذج، ولكن قد تعرض إصدارات المتصفّح السابقة أو مقدّمو الخدمة عنوانًا موحّدًا (على سبيل المثال،First.Last@example.comلـfirst.last@example.com). استخدِم مقارنة غير حساسة لحالة الأحرف عند مطابقة مطالبةemailالخاصة بالرمز المميّز مع قيمة النموذج المرسَلة.