تنفيذ مقدّم خدمة البريد الإلكتروني (جهة الإصدار)

لمزيد من التفاصيل، يمكنك الاطّلاع على الرمز البرمجي التجريبي لمزوِّد خدمة البريد الإلكتروني الوهمي والرجوع إلى خطوات جهة الإصدار في اقتراحات واجهة برمجة التطبيقات لتأكيد عنوان البريد الإلكتروني وبروتوكول تأكيد عنوان البريد الإلكتروني.

بصفتك جهة إصدار، لست بحاجة إلى الاشتراك في مرحلة التجربة والتقييم أو تقديم رمز مميّز لأنّ موقع الطرف المعتمِد يشغّل سلوك المتصفّح. تأكَّد من أنّ نقاط النهاية تم إعدادها للاستجابة لهذه الطلبات.

ضبط إعدادات ميزة "اكتشاف جهة الإصدار"

للسماح للمتصفّحات باكتشاف نقاط نهاية التحقّق تلقائيًا عند اختيار عنوان بريد إلكتروني ينتمي إلى نطاقك، يمكنك عرض إعداداتك باستخدام نظام أسماء النطاقات ونقطة نهاية 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-Key alg="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 153 emailverification (بدون واصلة). يجب قبول كلتا القيمتين أثناء طرح التغيير.
  • عدم تطابق توقيع رسالة HTTP‏ (@authority) خلف خادم وكيل: عند التحقّق من توقيع RFC 9421، يعكس المكوّن @authority المضيف المتاح للجميع. إذا كان الخادم الخاص بك يقع خلف خادم وكيل عكسي أو جهاز موازنة الحمل، أعِد إنشاء عنوان URL لتأكيد رقم الهاتف باستخدام X-Forwarded-Host (أو المصدر العام) بدلاً من اسم المضيف الداخلي، واحتسِب Content-Digest على وحدات بايت نص الطلب الأوّلي قبل تحليل JSON.

يرفض المتصفّح issuance_token الذي تم إرجاعه

  • مطالبة email معدَّلة أو تم تحويلها إلى عنوان URL أساسي: اعتبارًا من الإصدار 156 من Chrome، يتحقّق المتصفّح من تطابق مطالبة EVT email مع email المطلوب بايت ببايت. إذا كان الخلفية الأساسية تعمل على تسوية العنوان إلى تنسيق حساب أساسي (مثل عرض First.Last@example.com عند طلب first.LAST@example.com)، سيتجاهل Chrome الرمز المميز. يجب مطابقة الطلب مع حساب المستخدم، ولكن يجب عرض سلسلة email نفسها التي تم تلقّيها في نص الطلب.
  • عدم توفّر علامة التلدة اللاحقة (~): حتى في حال عدم توفّر أي إفصاحات، يجب أن يكون issuance_token رمز SD-JWT صالحًا ينتهي بعلامة تلدة لاحقة (<Issuer-signed-JWT>~) ليتمكّن المتصفّح من إلحاق <KB-JWT>.
  • عدم تطابق iss أو cnf.jwk: تأكَّد من أنّ مطالبة EVT iss هي المصدر الدقيق لبروتوكول HTTPS (https://<issuer-domain>، بدون شرطة مائلة لاحقة) الذي يتطابق مع البيانات الوصفية لـ .well-known/email-verification، وأنّ cnf.jwk يضمّن المفتاح العام المؤقت للمتصفّح من العنوان Signature-Key.