لمزيد من التفاصيل، يمكنك الاطّلاع على الرمز البرمجي التجريبي لمزوِّد خدمة البريد الإلكتروني الوهمي والرجوع إلى خطوات جهة الإصدار في اقتراحات واجهة برمجة التطبيقات لتأكيد عنوان البريد الإلكتروني وبروتوكول تأكيد عنوان البريد الإلكتروني.
بصفتك جهة إصدار، لست بحاجة إلى الاشتراك في مرحلة التجربة والتقييم أو تقديم رمز مميّز لأنّ موقع الطرف المعتمِد يشغّل سلوك المتصفّح. تأكَّد من أنّ نقاط النهاية تم إعدادها للاستجابة لهذه الطلبات.
ضبط إعدادات ميزة "اكتشاف جهة الإصدار"
للسماح للمتصفّحات باكتشاف نقاط نهاية التحقّق تلقائيًا عند اختيار عنوان بريد إلكتروني ينتمي إلى نطاقك، يمكنك عرض إعداداتك باستخدام نظام أسماء النطاقات ونقطة نهاية HTTP لـ .well-known.
ضبط سجلّ تفويض نظام أسماء النطاقات
اضبط سجلّ TXT لنظام أسماء النطاقات على نطاق بريدك الإلكتروني الذي يفوّض سلطة التحقّق إلى معرّف الجهة المُصدرة. يمكن أن تستخدم هذه المعرّفات النطاق نفسه حسب البنية الأساسية لديك.
تنسيق السجلّ: _email-verification.<email-domain>
مثال على ملف المنطقة:
_email-verification.example.com IN TXT "iss=accounts.issuer.example"
يجب أن تكون قيمة iss= اسم مضيف أساسيًا صغير الأحرف (على سبيل المثال،
iss=accounts.issuer.example) بدون مخطط (https://) أو منفذ أو مسار أو
أحرف كبيرة. يرفض Chrome السجلّات التي تتضمّن مكوّنات غير اسم المضيف.
استضافة نقطة نهاية .well-known/email-verification
استضافة ملف بيانات وصفية بتنسيق JSON على نطاق الجهة المصدرة ضمن المسار /.well-known/
يوضّح هذا الملف إمكانات الإصدار وخوارزميات التوقيع المشفّر التي تتيحها البنية الأساسية لديك.
نقطة النهاية: https://<issuer-domain>/.well-known/email-verification
مثال على الرد:
{
"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"]
}
سمات البيانات الوصفية:
-
issuer: مصدر جهة الإصدار (https://<issuer-domain>، بدون شرطة مائلة في النهاية) يجب أن يتطابق مع المصدر الذي يتم عرض ملف البيانات الوصفية منه بايت ببايت. issuance_endpoint: عنوان URL الذي يستخدم HTTPS ويتلقّى طلباتPOSTإصدار الرموز المميّزة.-
jwks_uri: عنوان URL يستخدم HTTPS ويعرض مجموعة مفاتيح الويب JSON (JWKS) العلنية. signing_alg_values_supported: مصفوفة من خوارزميات توقيع JWS المتوافقة.
استضافة نقطة نهاية .well-known/web-identity
قد تكون نفّذت بالفعل مورد JSON إضافي لـ .well-known كجزء من Federated Credentials (FedCM) API. يوفّر هذا المرجع روابط تؤدي إلى نقطة نهاية حساباتك وعنوان URL لصفحة تسجيل الدخول.
نقطة النهاية: https://<domain>/.well-known/web-identity
مثال على الردّ:
{
"accounts_endpoint": "https://accounts.issuer.example/accounts",
"login_url": "https://accounts.issuer.example/login"
}
استخدام نقطة نهاية للحسابات
تقدّم نقطة نهاية الحسابات من واجهة برمجة التطبيقات FedCM قائمة بالحسابات التي تم تسجيل الدخول إليها في الوقت الحالي. يعرض المثال التالي الحد الأدنى من الاستجابة. لمزيد من التفاصيل، يُرجى الرجوع إلى دليل تنفيذ موفِّر الهوية.
نقطة النهاية: كما هو محدّد في .well-known/web-identity
في ما يلي مثال على الردّ:
{
"accounts": [
{
"id": "demo-example",
"name": "Demo User",
"email": "demo@example.com",
"given_name": "Demo"
}
]
}
الدمج مع Login Status API
يجب أن تكون لدى المستخدم جلسة نشطة مع مقدّم الخدمة، ويجب أن تشير إلى ذلك للمتصفّح باستخدام Login Status API.
عندما يسجّل المستخدم دخوله أو خروجه بنجاح، اعرض عنوان استجابة HTTP المطابق:
Set-Login: logged-in
Set-Login: logged-out
بدلاً من ذلك، يمكنك تعديل الحالة باستخدام JavaScript في سياق تطبيق الويب:
navigator.login.setStatus("logged-in");
navigator.login.setStatus("logged-out");
التعامل مع طلبات الإصدار
يتلقّى issuance_endpoint طلب application/json POST يحتوي على مفتاح email وعناوين توقيعات رسائل HTTP لكل من Signature وSignature-Input وSignature-Key.
استخدِم مكتبة تتوافق مع العناوين المنظَّمة وتوقيعات رسائل HTTP في بيئتك. في Node.js، يمكنك استخدام
structured-headers و
http-message-sig.
تنسيق الطلب الكامل:
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"}
تحليل الطلب والتحقّق من صحته:
- مصادقة الجلسة: يمكنك التحقّق من صحة ملفات تعريف الارتباط للجلسة الخاصة بالطرف الأول التي تم إرسالها مع الطلب. يجب أن يتم إثبات هوية المستخدم.
- عنوان
Sec-Fetch-Dest: اضبطه علىemail-verification. - توقيعات رسائل HTTP: تحقَّق من توقيع الطلب باستخدام المفتاح العام المؤقت في
Signature-Keyوتحقَّق من صحةContent-Digest. بدءًا من الإصدار 156 من Chrome، يتضمّن عنوانSignature-Keyalg="Ed25519"في مَعلماتhwk، ويقبل"Ed25519"و"EdDSA"، ويسمح بإغفالalgفي إصدارات Chrome السابقة. - الحمولة: يحتوي نص JSON على سلسلة
emailالمطلوبة للتحقّق.
الردّ على طلب الإصدار
بعد التحقّق بنجاح من صحة الرمز المميّز للجلسة ورمز الطلب، أنشئ رمز JWT للتصريح الانتقائي موقّعًا يتم عرضه بتنسيق JSON باستخدام المكتبات المناسبة لمنصتك. على سبيل المثال، يمكنك استخدام
@sd-jwt/core و
jose مع Node.
يجب أن يكون تنسيق الحمولة الأولية مشابهاً لما يلي:
{
"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
}
أنشئ الرمز المميّز ووقِّعه وأرجِعه:
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);
يظهر نص الاستجابة الناتج مشابهًا لما يلي:
{
"issuance_token": "tOkEn123tOkEn123tOkEn123...~"
}
بعد إنشاء رمز تأكيد عنوان البريد الإلكتروني وتوقيعه، يرسله المتصفّح إلى الموقع الإلكتروني الخاص بجهة التحقّق من أجل التحقّق من صحته.
تحديد المشاكل وحلّها
إذا لم يتواصل المتصفّح مع نقاط النهاية أو رفض الرموز المميزة الصادرة، تحقَّق من المشاكل الشائعة التالية:
لا يستدعي المتصفّح أبدًا accounts_endpoint أو issuance_endpoint
- لم يتم ضبط حالة تسجيل الدخول: لا يطلب Chrome بيانات من نقاط النهاية إلا إذا كان يعرف أنّ المستخدم مسجّل الدخول. تأكَّد من أنّ عملية تسجيل الدخول تضبط عنوان HTTP
Set-Login: logged-inأو تستدعيnavigator.login.setStatus("logged-in"). - حظر ملفات تعريف الارتباط الخاصة بالجلسة (
SameSite=None): يسترد المتصفّحaccounts_endpointوissuance_endpointمن جهة معتمدة على موقع إلكتروني مختلف. بما أنّ هذه الطلبات من مواقع إلكترونية مختلفة، يجب أن يتضمّن ملف تعريف الارتباط للجلسة السمةSameSite=None; Secure. يعمل ملف تعريف الارتباطSameSite=Laxعند الاختبار على أداة التحقّق من تطابق الموقع الإلكتروني مع عنوان URL، ولكن يتم حذفه في الطلبات المُرسَلة من مواقع إلكترونية مختلفة. - عدم تطابق في عملية الاكتشاف أو الحساب: تأكَّد من أنّ
_email-verification.<email-domain>يعرض سجلّ TXT واحدًا يتضمّن اسم مضيف أساسي بأحرف صغيرة (iss=<issuer-domain>، بدونhttps://أو منفذ أو مسار أو أحرف كبيرة)، وأنّ نقطتَي النهاية.well-knownتعرضانContent-Type: application/json، وأنّ.well-known/email-verificationيتضمّنissuerيتطابق معhttps://<issuer-domain>بايت ببايت، وأنّ استجابةaccounts_endpointتتضمّن حسابًا يتطابق فيهemailمع العنوان الذي تم إدخاله. - خوارزمية التوقيع غير متوافقة مع
.well-known/email-verification: يتطلّب الإصداران 154 و155 من Chrome استخدام"EdDSA"فيsigning_alg_values_supported، بينما يتوافق الإصدار 156 من Chrome والإصدارات الأحدث ومواصفات IETF مع"Ed25519". الإعلان عن كليهما["Ed25519", "EdDSA"]أثناء عملية الانتقال حتى لا يرفض الإصدار الثابت من Chrome البيانات الوصفية الخاصة بالاكتشاف.
تعذُّر التحقّق من صحة طلب الإصدار
- طريقة كتابة عنوان
Sec-Fetch-Dest: يرسل الإصدار Chrome 154 والإصدارات الأحدثSec-Fetch-Dest: email-verification(مع واصلة)، بينما أرسل الإصدار Chrome 153emailverification(بدون واصلة). يجب قبول كلتا القيمتين أثناء طرح التغيير. - عدم تطابق توقيع رسالة HTTP (
@authority) خلف خادم وكيل: عند التحقّق من توقيع RFC 9421، يعكس المكوّن@authorityالمضيف المتاح للجميع. إذا كان الخادم الخاص بك يقع خلف خادم وكيل عكسي أو جهاز موازنة الحمل، أعِد إنشاء عنوان URL لتأكيد رقم الهاتف باستخدامX-Forwarded-Host(أو المصدر العام) بدلاً من اسم المضيف الداخلي، واحتسِبContent-Digestعلى وحدات بايت نص الطلب الأوّلي قبل تحليل JSON.
يرفض المتصفّح issuance_token الذي تم إرجاعه
- مطالبة
emailمعدَّلة أو تم تحويلها إلى عنوان URL أساسي: اعتبارًا من الإصدار 156 من Chrome، يتحقّق المتصفّح من تطابق مطالبة EVTemailمعemailالمطلوب بايت ببايت. إذا كان الخلفية الأساسية تعمل على تسوية العنوان إلى تنسيق حساب أساسي (مثل عرضFirst.Last@example.comعند طلبfirst.LAST@example.com)، سيتجاهل Chrome الرمز المميز. يجب مطابقة الطلب مع حساب المستخدم، ولكن يجب عرض سلسلةemailنفسها التي تم تلقّيها في نص الطلب. - عدم توفّر علامة التلدة اللاحقة (
~): حتى في حال عدم توفّر أي إفصاحات، يجب أن يكونissuance_tokenرمز SD-JWT صالحًا ينتهي بعلامة تلدة لاحقة (<Issuer-signed-JWT>~) ليتمكّن المتصفّح من إلحاق<KB-JWT>. - عدم تطابق
issأوcnf.jwk: تأكَّد من أنّ مطالبة EVTissهي المصدر الدقيق لبروتوكول HTTPS (https://<issuer-domain>، بدون شرطة مائلة لاحقة) الذي يتطابق مع البيانات الوصفية لـ.well-known/email-verification، وأنّcnf.jwkيضمّن المفتاح العام المؤقت للمتصفّح من العنوانSignature-Key.