دليل المطوِّر حول استخدام Federated Credential Management API

تعرَّف على كيفية استخدام FedCM لإنشاء ميزة الاتحاد الذي يهدف إلى الحفاظ على الخصوصية.

FedCM (إدارة بيانات الاعتماد الفيدرالية) هي طريقة للحفاظ على الخصوصية في ما يتعلّق بخدمات الهوية الموحّدة (مثل "تسجيل الدخول باستخدام...") حيث يمكن للمستخدمين تسجيل الدخول إلى المواقع الإلكترونية بدون مشاركة معلوماتهم الشخصية مع خدمة الهوية أو الموقع الإلكتروني.

لمعرفة المزيد من المعلومات عن حالات استخدام FedCM API، وتدفقات المستخدمين، وخارطة طريق واجهة برمجة التطبيقات، راجِع مقدمة حول FedCM API.

بيئة تطوير FedCM

تحتاج إلى سياق آمن (HTTPS أو مضيف محلي) على كل من موفِّر الهوية والجهة المحظورة في Chrome لاستخدام FedCM.

رمز تصحيح الأخطاء في Chrome على نظام Android

يمكنك إعداد خادم وتشغيله محليًا لتصحيح أخطاء رمز FedCM. يمكنك الوصول إلى هذا الخادم في Chrome على جهاز Android متصل باستخدام كابل USB مع إعادة توجيه المنفذ.

يمكنك استخدام "أدوات مطوري البرامج" على الكمبيوتر المكتبي لتصحيح أخطاء Chrome على نظام التشغيل Android من خلال اتّباع التعليمات الواردة في تصحيح أخطاء أجهزة Android عن بُعد.

حظر ملفات تعريف الارتباط التابعة لجهات خارجية في Chrome

محاكاة الإيقاف التدريجي لملفات تعريف الارتباط التابعة لجهات خارجية من خلال ضبط Chrome لحظرها
محاكاة الإيقاف التدريجي لملفات تعريف الارتباط التابعة لجهات خارجية من خلال ضبط Chrome لحظرها

يمكنك اختبار طريقة عمل FedCM بدون ملفات تعريف الارتباط التابعة لجهات خارجية على Chrome قبل أن يتم فرضها فعليًا.

لحظر ملفات تعريف الارتباط التابعة لجهات خارجية، يمكنك استخدام وضع التصفّح المتخفي أو اختيار "حظر ملفات تعريف الارتباط التابعة لجهات خارجية" في إعدادات الكمبيوتر المكتبي على chrome://settings/cookies أو على الجهاز الجوّال من خلال الانتقال إلى الإعدادات > إعدادات الموقع الإلكتروني > ملفات تعريف الارتباط.

استخدام واجهة برمجة تطبيقات FedCM

يمكنك الدمج مع FedCM من خلال إنشاء ملف معروف وملف إعداد ونقاط نهاية لقائمة الحسابات وإصدار التأكيد والبيانات الوصفية للعميل إذا أردت.

وبعد ذلك، يعرض FedCM واجهات برمجة تطبيقات JavaScript التي يمكن للجهة المحظورة استخدامها لتسجيل الدخول باستخدام موفِّر الهوية.

إنشاء ملف معروف

لمنع أجهزة التتبُّع من إساءة استخدام واجهة برمجة التطبيقات، يجب عرض ملف معروف من خلال /.well-known/web-identity من eTLD+1 لموفِّر الهوية.

على سبيل المثال، إذا تم عرض نقاط نهاية موفِّر الهوية ضمن https://accounts.idp.example/، يجب أن تعرض هذه النقاط ملفًا معروفًا على https://idp.example/.well-known/web-identity بالإضافة إلى ملف إعداد موفِّر الهوية. إليك مثال على محتوى الملفات المعروفة:

{
  "provider_urls": ["https://accounts.idp.example/config.json"]
}

يجب أن يحتوي ملف JSON على السمة provider_urls مع مصفوفة من عناوين URL لملف إعداد موفِّر الهوية التي يمكن تحديدها كجزء من مسار configURL في navigator.credentials.get من خلال الجهات المحظورة. يقتصر عدد سلاسل عناوين URL في الصفيف على سلسلة واحدة، ولكن قد يتغير هذا الأمر بملاحظاتك في المستقبل.

إنشاء ملف إعداد ونقاط نهاية لموفِّر الهوية (IdP)

يوفِّر ملف إعداد موفِّر الهوية قائمة بنقاط النهاية المطلوبة للمتصفِّح. سيستضيف موفِّرو الهوية ملف الإعداد هذا ونقاط النهاية وعناوين URL المطلوبة. ويجب عرض جميع استجابات JSON باستخدام نوع المحتوى application/json.

يتم تحديد عنوان URL لملف الإعداد من خلال القيم المقدَّمة إلى طلب navigator.credentials.get الذي تم تنفيذه على جهة محظورة.

const credential = await navigator.credentials.get({
  identity: {
    context: 'signup',
    providers: [{
      configURL: 'https://accounts.idp.example/config.json',
      clientId: '********',
      nonce: '******'
    }]
  }
});
const { token } = credential;

حدِّد عنوان URL كاملاً لموقع ملف إعداد موفِّر الهوية باعتباره configURL. عند استدعاء navigator.credentials.get() على الجهة المحظورة، يجلب المتصفّح ملف الإعداد من خلال طلب GET بدون العنوان Origin أو العنوان Referer. لا يحتوي الطلب على ملفات تعريف الارتباط ولا يتّبع عمليات إعادة التوجيه. يؤدي ذلك إلى منع موفِّر الهوية (IdP) بشكل فعّال من معرفة المستخدم الذي أرسل الطلب والجهة المحظورة التي تحاول الاتصال. مثال:

GET /config.json HTTP/1.1
Host: accounts.idp.example
Accept: application/json
Sec-Fetch-Dest: webidentity

يتوقّع المتصفِّح استجابة JSON من موفِّر الهوية الذي يتضمّن الخصائص التالية:

الموقع الوصف
accounts_endpoint (مطلوب) عنوان URL لنقطة نهاية الحسابات.
client_metadata_endpoint (اختياري) عنوان URL لنقطة نهاية البيانات الوصفية للعميل.
id_assertion_endpoint (مطلوب) عنوان URL لنقطة نهاية تأكيد رقم التعريف.
disconnect (اختياري) عنوان URL لنقطة نهاية إلغاء الربط.
login_url (مطلوب) عنوان URL لصفحة تسجيل الدخول كي يتمكّن المستخدم من تسجيل الدخول إلى موفِّر الهوية (IdP).
branding (اختياري) عنصر يحتوي على خيارات متنوعة لبناء هوية العلامة التجارية.
branding.background_color (اختياري) خيار بناء هوية العلامة التجارية الذي يضبط لون خلفية الزر "متابعة كـ...". استخدِم بنية CSS ذات الصلة، وهي hex-color أو hsl() أو rgb() أو named-color.
branding.color (اختياري) خيار بناء هوية العلامة التجارية الذي يضبط لون نص الزر "متابعة كـ...". استخدِم بنية CSS ذات الصلة، وهي hex-color أو hsl() أو rgb() أو named-color.
branding.icons (اختياري) خيار بناء هوية العلامة التجارية الذي يضبط عنصر الرمز، ويتم عرضه في مربّع حوار تسجيل الدخول كائن الرمز هو مصفوفة تتضمّن مَعلمتَين:
  • url (مطلوب): عنوان URL لصورة الرمز. ولا يمكن استخدام صور SVG (رسومات موجّهة يمكن تغيير حجمها).
  • size (اختياري): أبعاد الرمز، التي يفترضها التطبيق أن تكون ذات دقة مربّعة وواحدة. يجب أن يكون هذا الرقم أكبر من أو يساوي 25.

يمكن للجهة المحظورة تعديل السلسلة في واجهة مستخدم مربّع حوار "المراسلة عبر السحابة الإلكترونية من Firebase" من خلال قيمة identity.context لـ navigator.credentials.get() لاستيعاب سياقات المصادقة المحدَّدة مسبقًا. يمكن أن تكون السمة الاختيارية أي مما يلي: "signin" (الخيار التلقائي) أو "signup" أو "use" أو "continue".

كيفية تطبيق العلامة التجارية على مربع حوار FedCM
كيفية تطبيق العلامة التجارية على مربّع حوار FedCM

في ما يلي مثال على نص استجابة من موفِّر الهوية:

{
  "accounts_endpoint": "/accounts.php",
  "client_metadata_endpoint": "/client_metadata.php",
  "id_assertion_endpoint": "/assertion.php",
  "disconnect_endpoint": "/disconnect.php",
  "login_url": "/login",
  "branding": {
    "background_color": "green",
    "color": "#FFEEAA",
    "icons": [{
      "url": "https://idp.example/icon.ico",
      "size": 25
    }]
  }
}

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

نقاط نهاية موفِّر الهوية
نقاط نهاية موفِّر الهوية

نقطة نهاية الحسابات

تعرض نقطة نهاية حسابات موفِّر الهوية قائمة بالحسابات التي سجّل المستخدم الدخول إليها حاليًا في موفِّر الهوية. إذا كان موفِّر الهوية يتيح استخدام حسابات متعددة، ستعرض نقطة النهاية هذه جميع الحسابات التي تم تسجيل الدخول إليها.

ويرسل المتصفِّح طلب GET مع ملفات تعريف الارتباط مع SameSite=None، ولكن بدون المَعلمة client_id أو العنوان Origin أو العنوان Referer. يمنع ذلك موفِّر الهوية بفعالية من معرفة الجهة المحظورة التي يحاول المستخدم تسجيل الدخول إليها. مثال:

GET /accounts.php HTTP/1.1
Host: accounts.idp.example
Accept: application/json
Cookie: 0x23223
Sec-Fetch-Dest: webidentity

وعند استلام الطلب، يجب على الخادم:

  1. تحقَّق من أنّ الطلب يحتوي على عنوان HTTP يتضمّن العنصر Sec-Fetch-Dest: webidentity.
  2. طابِق ملفات تعريف ارتباط الجلسة بأرقام تعريف الحسابات التي تم تسجيل الدخول إليها من قبل.
  3. الردّ بقائمة الحسابات

يتوقع المتصفّح استجابة JSON تتضمّن الموقع الإلكتروني accounts مع مصفوفة من معلومات الحساب تشمل السمات التالية:

الموقع الوصف
id (مطلوب) المعرّف الفريد للمستخدم
name (مطلوب) الاسم الأول واسم العائلة للمستخدم.
email (مطلوب) عنوان البريد الإلكتروني للمستخدم.
given_name (اختياري) الاسم الأول للمستخدم.
picture (اختياري) عنوان URL للصورة الرمزية للمستخدم
approved_clients (اختياري) مصفوفة من أرقام تعريف عملاء الجهة المحظورة التي سجّل المستخدم من خلالها.
login_hints (اختياري) هي مصفوفة من جميع أنواع الفلاتر المحتملة التي يتيحها موفِّر الهوية لتحديد حساب معيّن. يمكن أن يستدعي الجهة المحظورة navigator.credentials.get() باستخدام السمة loginHint لعرض الحساب المحدّد بشكل انتقائي.
domain_hints (اختياري) تمثّل هذه السمة مصفوفة لجميع النطاقات المرتبطة بالحساب. يمكن للجهة المحظورة طلب الرقم navigator.credentials.get() باستخدام السمة domainHint لفلترة الحسابات.

مثال على نص الاستجابة:

{
  "accounts": [{
    "id": "1234",
    "given_name": "John",
    "name": "John Doe",
    "email": "john_doe@idp.example",
    "picture": "https://idp.example/profile/123",
    "approved_clients": ["123", "456", "789"],
    "login_hints": ["demo1", "demo1@idp.example"]
  }, {
    "id": "5678",
    "given_name": "Johnny",
    "name": "Johnny",
    "email": "johnny@idp.example",
    "picture": "https://idp.example/profile/456",
    "approved_clients": ["abc", "def", "ghi"],
    "login_hints": ["demo2", "demo2@idp.example"],
    "domain_hints": ["corp.example"]
  }]
}

إذا لم يسجّل المستخدم الدخول، يمكنك الرد باستخدام HTTP 401 (غير مصرح به).

يشغّل المتصفّح قائمة الحسابات التي تم إرجاعها ولن تكون متاحة للجهة المحظورة.

نقطة نهاية البيانات الوصفية للعميل

تعرض نقطة نهاية البيانات الوصفية للعميل الخاصة بموفِّر الهوية البيانات الوصفية الخاصة بالطرف المعتمد، مثل سياسة الخصوصية وبنود الخدمة لدى الجهة المحظورة. على الجهات المحظورة تقديم روابط تؤدي إلى سياسة الخصوصية وبنود الخدمة إلى موفِّر الهوية مسبقًا. يتم عرض هذه الروابط في مربّع حوار تسجيل الدخول عندما لا يسجّل المستخدم في الجهة المحظورة لدى موفِّر الهوية حتى الآن.

ويرسل المتصفّح طلب GET باستخدام client_id navigator.credentials.get بدون ملفات تعريف الارتباط. مثال:

GET /client_metadata.php?client_id=1234 HTTP/1.1
Host: accounts.idp.example
Origin: https://rp.example/
Accept: application/json
Sec-Fetch-Dest: webidentity

وعند استلام الطلب، يجب على الخادم:

  1. تحديد الجهة المحظورة لـ client_id.
  2. استخدِم البيانات الوصفية للعميل للردّ.

تتضمن خصائص نقطة نهاية البيانات الوصفية للعميل ما يلي:

الموقع الوصف
privacy_policy_url (اختياري) عنوان URL لسياسة خصوصية الجهة المحظورة.
terms_of_service_url (اختياري) عنوان URL لبنود خدمة الجهة المحظورة.

يتوقع المتصفِّح استجابة JSON من نقطة النهاية:

{
  "privacy_policy_url": "https://rp.example/privacy_policy.html",
  "terms_of_service_url": "https://rp.example/terms_of_service.html",
}

يستنِد المتصفّح إلى البيانات الوصفية الخاصة بالعميل التي يتم عرضها، ولن تكون هذه البيانات متوفّرة للجهة المحظورة.

نقطة نهاية تأكيد رقم التعريف

تعرض نقطة نهاية تأكيد رقم التعريف لموفِّر الهوية تأكيدًا للمستخدم الذي سجّل الدخول. عندما يسجّل المستخدم الدخول إلى موقع الجهة المحظورة باستخدام طلب navigator.credentials.get()، يرسل المتصفّح طلب POST يتضمن ملفات تعريف الارتباط مع SameSite=None ونوع محتوى application/x-www-form-urlencoded إلى نقطة النهاية هذه مع المعلومات التالية:

الموقع الوصف
client_id (مطلوب) هو معرِّف العميل الخاص بالجهة المحظورة.
account_id (مطلوب) المعرّف الفريد للمستخدم الذي يسجّل الدخول.
nonce (اختياري) تشير هذه السمة إلى الطلب الخاص بالطلب الذي توفّره الجهة المحظورة.
disclosure_text_shown النتائج في سلسلة من "true" أو "false" (بدلاً من القيمة المنطقية) والنتيجة هي "false" في حال عدم عرض نص الإفصاح. يحدث ذلك عندما يتم تضمين معرِّف عميل الجهة المحظورة في قائمة المواقع الإلكترونية approved_clients للاستجابة من نقطة نهاية الحسابات أو إذا لاحظ المتصفِّح لحظة اشتراك في الماضي بدون approved_clients.
is_auto_selected إذا تم إجراء إعادة المصادقة التلقائية على الجهة المحظورة، تشير السمة is_auto_selected إلى "true". ويمكنك بدلاً من ذلك "false". ويساعد ذلك في دعم المزيد من الميزات المتعلّقة بالأمان. على سبيل المثال، قد يفضل بعض المستخدمين مستوى أمان أعلى يتطلب مصادقة المستخدم الصريحة في المصادقة. وفي حال تلقّى موفّر الهوية طلب رمز مميّز بدون مثل هذا التوسّط، يمكنه التعامل مع الطلب بطريقة مختلفة. على سبيل المثال، يمكنك عرض رمز خطأ يتيح لـ RP استدعاء واجهة برمجة تطبيقات FedCM مرة أخرى باستخدام mediation: required.

مثال على عنوان HTTP:

POST /assertion.php HTTP/1.1
Host: accounts.idp.example
Origin: https://rp.example/
Content-Type: application/x-www-form-urlencoded
Cookie: 0x23223
Sec-Fetch-Dest: webidentity

account_id=123&client_id=client1234&nonce=Ct60bD&disclosure_text_shown=true&is_auto_selected=true

وعند استلام الطلب، يجب على الخادم:

  1. يمكنك الردّ على الطلب باستخدام مشاركة الموارد المتعدّدة المصادر (CORS).
  2. تحقَّق من أنّ الطلب يحتوي على عنوان HTTP يتضمّن العنصر Sec-Fetch-Dest: webidentity.
  3. عليك مطابقة عنوان Origin مع أصل الجهة المحظورة التي يتم تحديدها من خلال client_id. الرفض في حال عدم التطابق
  4. عليك مطابقة account_id مع رقم تعريف الحساب الذي سبق أن سجّلت الدخول إليه. الرفض إذا لم يتطابقا.
  5. يمكنك الردّ باستخدام رمز مميّز. إذا تم رفض الطلب، يمكنك الرد باستخدام استجابة خطأ.

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

يتوقع المتصفِّح استجابة JSON التي تتضمّن السمة التالية:

الموقع الوصف
token (مطلوب) الرمز المميز هو سلسلة تحتوي على مطالبات بشأن المصادقة. 
{
  "token": "***********"
}

يتم تمرير الرمز المميز الذي تم إرجاعه إلى الجهة المحظورة من خلال المتصفح، حتى يتمكن الجهة المحظورة من التحقق من المصادقة.

عرض استجابة خطأ

يمكن أن تعرض id_assertion_endpoint أيضًا استجابة "خطأ"، التي تحتوي على حقلين اختياريين:

  • code: يمكن لموفِّر الهوية اختيار أحد الأخطاء المعروفة من قائمة أخطاء OAuth 2.0 (invalid_request، وunauthorized_client، وaccess_denied، وserver_error temporarily_unavailable) أو استخدام أي سلسلة عشوائية. إذا كان الأخير، يعرض Chrome واجهة المستخدم للخطأ مع رسالة خطأ عامة ويمرر الرمز إلى الجهة المحظورة.
  • url: تحدّد صفحة ويب يمكن للمستخدمين قراءتها وتحتوي على معلومات عن الخطأ، وذلك لتقديم معلومات إضافية عن الخطأ للمستخدمين. هذا الحقل مفيد للمستخدمين لأن المتصفحات لا يمكنها تقديم رسائل خطأ منسقة في واجهة مستخدم أصلية. على سبيل المثال، روابط للخطوات التالية ومعلومات الاتصال بخدمة العملاء وما إلى ذلك. إذا أراد أحد المستخدمين معرفة المزيد حول تفاصيل الخطأ وكيفية إصلاحه، يمكنه الانتقال إلى الصفحة المقدَّمة من واجهة مستخدم المتصفّح للاطّلاع على مزيد من التفاصيل. يجب أن يكون عنوان URL للموقع الإلكتروني نفسه لموفِّر الهوية configURL.
// id_assertion_endpoint response
{
  "error" : {
     "code": "access_denied",
     "url" : "https://idp.example/error?type=access_denied"
  }
}

إلغاء ربط نقطة النهاية

من خلال استدعاء IdentityCredential.disconnect()، يرسل المتصفّح طلب POST متعدد المصادر يحتوي على ملفات تعريف الارتباط مع SameSite=None ونوع محتوى application/x-www-form-urlencoded إلى نقطة نهاية إلغاء الربط هذه مع المعلومات التالية:

الموقع الوصف
account_hint تلميح لحساب موفِّر الهوية (IdP)..
client_id هو معرِّف العميل الخاص بالجهة المحظورة. 
POST /disconnect.php HTTP/1.1
Host: idp.example
Origin: rp.example
Content-Type: application/x-www-form-urlencoded
Cookie: 0x123
Sec-Fetch-Dest: webidentity

account_hint=account456&client_id=rp123

وعند استلام الطلب، يجب على الخادم:

  1. يمكنك الردّ على الطلب باستخدام مشاركة الموارد المتعدّدة المصادر (CORS).
  2. تحقَّق من أنّ الطلب يحتوي على عنوان HTTP يتضمّن العنصر Sec-Fetch-Dest: webidentity.
  3. عليك مطابقة عنوان Origin مع أصل الجهة المحظورة التي يتم تحديدها من خلال client_id. الرفض في حال عدم التطابق
  4. يمكنك مطابقة account_hint مع أرقام تعريف الحسابات التي سبق تسجيل الدخول إليها.
  5. ألغِ ربط حساب المستخدم بالجهة المحظورة.
  6. استجب للمتصفّح بمعلومات حساب المستخدم التي تم تحديدها بتنسيق JSON.

في ما يلي مثال لحمولة JSON للاستجابة:

{
  "account_id": "account456"
}

بدلاً من ذلك، إذا أراد موفِّر الهوية من المتصفّح إلغاء ربط جميع الحسابات المرتبطة بالجهة المحظورة، اختَر سلسلة لا تتطابق مع أي رقم تعريف حساب، على سبيل المثال "*".

عنوان URL لتسجيل الدخول

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

يعرض مربع حوار FedCM رسالة تقترح تسجيل الدخول، كما هو موضح في الصورة التالية.

جيم
مربع حوار في FedCM يقترح تسجيل الدخول إلى موفِّر الهوية
.

عندما ينقر المستخدم على الزر متابعة، يفتح المتصفِّح نافذة منبثقة لصفحة تسجيل دخول موفِّر الهوية.

إنّ
مثال على مربّع حوار يظهر بعد النقر على زرّ تسجيل الدخول إلى زرّ موفِّر الهوية.

مربع الحوار هو نافذة متصفح عادية تتضمن ملفات تعريف الارتباط للطرف الأول. يعود أي شيء يحدث في مربّع الحوار إلى موفِّر الهوية، ولا تتوفّر أي معرِّفات نوافذ لتقديم طلب اتصال من مصادر متعددة إلى صفحة الجهة المحظورة. بعد تسجيل دخول المستخدم، على موفِّر الهوية إجراء ما يلي:

  • أرسِل عنوان Set-Login: logged-in أو استدعِ واجهة برمجة التطبيقات navigator.login.setStatus("logged-in") لإعلام المتصفّح بأنّ المستخدم قد سجّل الدخول.
  • يمكنك الاتصال بـ IdentityProvider.close() لإغلاق مربّع الحوار.
جيم
يسجِّل مستخدم الدخول إلى جهة محظورة بعد تسجيل الدخول إلى موفِّر الهوية باستخدام ميزة "المراسلة عبر السحابة الإلكترونية من Firebase".

إبلاغ المتصفّح بحالة تسجيل دخول المستخدم على موفِّر الهوية

واجهة برمجة التطبيقات لحالة تسجيل الدخول هي آلية يعمل من خلالها الموقع الإلكتروني، خاصةً موفِّر الهوية، على إبلاغ المتصفِّح بحالة تسجيل دخول المستخدم على موفِّر الهوية (IdP). باستخدام واجهة برمجة التطبيقات هذه، يمكن للمتصفِّح تقليل الطلبات غير الضرورية إلى موفِّر الهوية والحدّ من هجمات التوقيت المحتملة.

ويمكن لموفِّري الهوية (IdP) إرسال إشارة إلى المتصفِّح عن حالة تسجيل دخول المستخدم من خلال إرسال عنوان HTTP أو من خلال استدعاء واجهة برمجة تطبيقات JavaScript عند تسجيل المستخدم الدخول في موفِّر الهوية أو عند تسجيل المستخدم لخروجه من جميع حسابات موفِّر الهوية. بالنسبة إلى كل موفِّر الهوية (IdP) (الذي يتم تحديده من خلال عنوان URL للإعدادات)، يحتفظ المتصفّح بمتغيّر ثلاثي الحالة يمثل حالة تسجيل الدخول مع القيم المحتملة logged-in وlogged-out وunknown. الحالة التلقائية هي unknown.

للإشارة إلى أنّ المستخدم سجّل الدخول، أرسِل عنوان HTTP يتضمّن السمة Set-Login: logged-in في عملية التنقّل على المستوى الأعلى أو طلب مورد فرعي للموقع الإلكتروني نفسه في مصدر موفِّر الهوية:

Set-Login: logged-in

يمكنك بدلاً من ذلك استدعاء واجهة برمجة تطبيقات JavaScript navigator.login.setStatus("logged-in") من مصدر موفِّر الهوية في شريط التنقّل على المستوى الأعلى:

navigator.login.setStatus("logged-in")

تسجّل هذه المكالمات حالة تسجيل دخول المستخدم على أنّها logged-in. عند ضبط حالة تسجيل دخول المستخدم على logged-in، ترسل الجهة المحظورة التي تطلب خدمة FedCM طلبات إلى نقطة نهاية حسابات موفِّر الهوية وتعرض الحسابات المتاحة للمستخدم في مربّع حوار FedCM.

للإشارة إلى تسجيل خروج المستخدم من جميع حساباته، أرسِل عنوان HTTP يتضمّن العنصر Set-Login: logged-out في عملية التنقّل على المستوى الأعلى أو طلب مورد فرعي للموقع الإلكتروني نفسه في مصدر موفِّر الهوية:

Set-Login: logged-out

يمكنك بدلاً من ذلك استدعاء واجهة برمجة تطبيقات JavaScript navigator.login.setStatus("logged-out") من مصدر موفِّر الهوية في شريط التنقّل على المستوى الأعلى:

navigator.login.setStatus("logged-out")

تسجّل هذه المكالمات حالة تسجيل دخول المستخدم على أنّها logged-out. عندما تكون حالة تسجيل دخول المستخدم هي logged-out، يتعذّر الاتصال بـ FedCM بدون إرسال أي طلب إلى نقطة نهاية حسابات موفِّر الهوية.

يتم ضبط حالة unknown قبل أن يرسل موفِّر الهوية إشارة باستخدام واجهة برمجة التطبيقات الخاصة بحالة تسجيل الدخول. تم تقديم Unknown لإجراء عملية نقل أفضل، لأنّه يُحتمل أن يكون المستخدم قد سجّل الدخول إلى موفِّر الهوية (IdP) سابقًا عند شحن واجهة برمجة التطبيقات هذه. قد لا تُتاح الفرصة لموفِّر الهوية (IdP) لإرسال إشارة إلى ذلك المتصفِّح عند استدعاء "المراسلة عبر السحابة الإلكترونية من Firebase" لأول مرة. في هذه الحالة، يرسل Chrome طلبًا إلى نقطة نهاية حسابات موفِّر الهوية ويعدِّل الحالة استنادًا إلى الاستجابة من نقطة نهاية الحسابات:

  • إذا عرضت نقطة النهاية قائمة بالحسابات النشطة، عدِّل الحالة إلى logged-in وافتح مربّع حوار FedCM لعرض هذه الحسابات.
  • إذا لم تعرض نقطة النهاية أي حسابات، عليك تعديل الحالة إلى logged-out بدون تعذُّر طلب FedCM.

السماح للمستخدم بتسجيل الدخول من خلال تدفق تسجيل دخول ديناميكي

وعلى الرغم من أنّ موفِّر الهوية (IdP) يُعلم المستخدم باستمرار بحالة تسجيل دخول المستخدم، قد يكون غير متزامن، مثلاً عند انتهاء صلاحية الجلسة. يحاول المتصفّح إرسال طلب معتمَد إلى نقطة نهاية الحسابات عندما تكون حالة تسجيل الدخول logged-in، ولكن لا يعرض الخادم أي حسابات لأنّ الجلسة لم تعُد متوفّرة. في هذا السيناريو، يمكن للمتصفّح السماح للمستخدم بتسجيل الدخول إلى موفِّر الهوية ديناميكيًا من خلال نافذة منبثقة.

سجِّل الدخول إلى المجموعة الموثوق بها باستخدام موفِّر الهوية.

بعد توفُّر إعدادات الإعداد ونقاط النهاية لموفِّر الهوية، يمكن لجهات الاتصال المحظورة طلب الرقم navigator.credentials.get() لطلب السماح للمستخدمين بتسجيل الدخول إلى الجهة المحظورة من خلال موفِّر الهوية.

قبل طلب بيانات من واجهة برمجة التطبيقات، عليك التأكّد من أنّ [FedCM متاح على متصفّح المستخدم]. للتحقق من توفر FedCM، عليك ربط هذا الرمز حول تنفيذ FedCM:

if ('IdentityCredential' in window) {
  // If the feature is available, take action
}

لطلب السماح للمستخدمين بتسجيل الدخول إلى موفِّر الهوية من الجهة المحظورة، اتّبِع الخطوات التالية، مثلاً:

const credential = await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: 'https://accounts.idp.example/config.json',
      clientId: '********',
      nonce: '******'
    }]
  }
});
const { token } = credential;

تستخدم السمة providers مصفوفة من IdentityProvider عناصر تتضمّن السمات التالية:

الموقع الوصف
configURL (مطلوب) مسار كامل لملف إعداد موفِّر الهوية.
clientId (مطلوب) معرِّف عميل الجهة المحظورة، الذي يصدره موفِّر الهوية.
nonce (اختياري) سلسلة عشوائية لضمان إصدار استجابة لهذا الطلب المحدّد. لمنع هجمات إعادة التشغيل.
loginHint (اختياري) من خلال تحديد إحدى قيم login_hints المقدَّمة من خلال نقاط نهاية الحسابات، يعرض مربّع حوار "المراسلة عبر السحابة الإلكترونية من Firebase" الحساب المحدّد بشكل انتقائي.
domainHint (اختياري) من خلال تحديد إحدى قيم domain_hints التي تقدّمها نقاط نهاية الحسابات، يعرض مربّع حوار "المراسلة عبر السحابة الإلكترونية من Firebase" الحساب المحدّد بشكل انتقائي.

يتعامل المتصفّح مع حالات استخدام الاشتراك وتسجيل الدخول بشكل مختلف بناءً على توفّر approved_clients في الرد الوارد من نقطة نهاية قائمة الحسابات. لن يعرض المتصفّح نص الإفصاح "للمتابعة باستخدام ...." إذا كان المستخدم قد اشترك في خدمة الجهة المحظورة.

يتم تحديد حالة الاشتراك بناءً على ما إذا كان قد تم استيفاء الشروط التالية أم لا:

  • إذا كان approved_clients يتضمّن clientId الخاصة بالجهة المحظورة.
  • في حال تذكّر المتصفِّح أنّ المستخدم قد اشترك من قبل في الجهة المحظورة.
تسجيل دخول مستخدم إلى جهة محظورة باستخدام ميزة "المراسلة عبر السحابة الإلكترونية من Firebase"

عندما يطلب الجهة المحظورة navigator.credentials.get()، يتم تنفيذ الأنشطة التالية:

  1. يرسل المتصفّح الطلبات ويجلب عدة مستندات:
    1. الملف المعروف وملف إعداد موفِّر الهوية (IdP) الذي يوضِّح نقاط النهاية.
    2. قائمة الحسابات:
    3. اختياري: عناوين URL لسياسة الخصوصية وبنود الخدمة لدى الجهة المحظورة، تم استردادها من نقطة نهاية البيانات الوصفية للعميل.
  2. يعرض المتصفح قائمة بالحسابات التي يمكن للمستخدم استخدامها لتسجيل الدخول، بالإضافة إلى بنود الخدمة وسياسة الخصوصية، في حال توفّرها.
  3. بعد أن يختار المستخدم حسابًا لتسجيل الدخول باستخدامه، يتم إرسال طلب إلى نقطة نهاية تأكيد رقم التعريف إلى موفِّر الهوية لاسترداد الرمز المميّز.
  4. يمكن للجهة المحظورة التحقّق من الرمز المميّز لمصادقة المستخدم.
طلب بيانات من واجهة برمجة التطبيقات لتسجيل الدخول
طلب بيانات من واجهة برمجة التطبيقات لتسجيل الدخول

من المتوقّع أن تتوافق الجهات المحظورة مع المتصفّحات التي لا تتوافق مع FedCM، وبالتالي يجب أن يتمكّن المستخدمون من استخدام عملية تسجيل دخول حالية لا تعتمد على خدمة FedCM. وإلى أن يتم الاستغناء تدريجيًا عن ملفات تعريف الارتباط التابعة لجهات خارجية، لن يؤدي ذلك إلى حلّ المشكلة.

بمجرد التحقق من صحة الرمز المميز من خلال خادم الجهة المحظورة، قد يسجل الجهة المحظورة المستخدم أو تسمح له بتسجيل الدخول وبدء جلسة جديدة.

واجهة برمجة تطبيقات تعديل تسجيل الدخول

بعد أن يسجِّل المستخدم الدخول، قد يطلب الطرف المعتمد (RP) من المستخدم أحيانًا إعادة المصادقة. إلا أن المستخدم قد لا يكون متأكدًا من الحساب الذي كان يستخدمه. إذا كان بإمكان الجهة المحظورة تحديد الحساب الذي سيتم تسجيل الدخول باستخدامه، سيكون من الأسهل على المستخدم اختيار حساب.

يمكن أن تعرض الجهات المحظورة حسابًا معيّنًا بشكل انتقائي من خلال استدعاء navigator.credentials.get() مع السمة loginHint مع استرجاع إحدى قيم login_hints التي يتم استرجاعها من نقطة نهاية قائمة الحسابات، كما هو موضّح في نموذج الرموز التالية:

return await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: "https://idp.example/manifest.json",
      clientId: "123",
      nonce: nonce,
      loginHint : "demo1@example.com"
    }]
  }
});

في حال عدم تطابق أي حسابات مع loginHint، يعرض مربع حوار FedCM طلبًا لتسجيل الدخول، الذي يسمح للمستخدم بتسجيل الدخول إلى حساب موفِّر الهوية يتطابق مع التلميح الذي طلبه الجهة المحظورة. عندما ينقر المستخدم على الإشعار، يتم فتح نافذة منبثقة تتضمّن عنوان URL لتسجيل الدخول المحدّد في ملف الإعداد. بعد ذلك، يتم إلحاق الرابط بتلميح تسجيل الدخول ومَعلمات طلب البحث لتلميح النطاق.

واجهة برمجة تطبيقات Domain Hint

هناك حالات يعرف فيها الجهة المحظورة مسبقًا أنّه يُسمح فقط للحسابات المرتبطة بنطاق معيّن بتسجيل الدخول إلى الموقع الإلكتروني. هذا أمر شائع على وجه الخصوص في سيناريوهات المؤسسات، حيث يقتصر الوصول إلى الموقع الإلكتروني على نطاق الشركة. لتوفير تجربة أفضل للمستخدم، تسمح واجهة برمجة التطبيقات FedCM API لـ RP بعرض الحسابات التي يمكن استخدامها فقط لتسجيل الدخول إلى الجهة المحظورة. يمنع ذلك السيناريوهات التي يحاول فيها المستخدم تسجيل الدخول إلى الجهة المحظورة باستخدام حساب خارج نطاق الشركة، ويتم عرض رسالة خطأ فقط لاحقًا (أو كتم صوتها في الحالات التي لا ينجح فيها تسجيل الدخول) لأنّه لم يتم استخدام النوع الصحيح من الحساب.

يمكن أن تعرض الجهات المحظورة بشكل انتقائي الحسابات المطابقة فقط من خلال استدعاء navigator.credentials.get() مع السمة domainHint مع إحدى قيم domain_hints التي يتم استرجاعها من نقطة نهاية قائمة الحسابات، على النحو الموضّح في نموذج الرمز البرمجي التالي:

return await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: "https://idp.example/manifest.json",
      clientId: "abc",
      nonce: nonce,
      domainHint : "corp.example"
    }]
  }
});

في حال عدم تطابق أي حسابات مع domainHint، يعرض مربع حوار FedCM طلبًا لتسجيل الدخول، الذي يسمح للمستخدم بتسجيل الدخول إلى حساب موفِّر الهوية يتطابق مع التلميح الذي طلبه الجهة المحظورة. عندما ينقر المستخدم على الإشعار، يتم فتح نافذة منبثقة تتضمّن عنوان URL لتسجيل الدخول المحدّد في ملف الإعداد. بعد ذلك، يتم إلحاق الرابط بتلميح تسجيل الدخول ومَعلمات طلب البحث لتلميح النطاق.

مثال على طلب تسجيل الدخول عندما لا تتطابق أي حسابات مع domainHint.
مثال على طلب تسجيل الدخول عندما لا تتطابق أي حسابات مع domainHint.

عرض رسالة خطأ

في بعض الأحيان، قد لا يتمكن موفِّر الهوية من إصدار رمز مميَّز لأسباب مشروعة، مثلاً عندما يكون العميل غير مُصرَّح به، يكون الخادم غير متاح مؤقتًا. وإذا عرض موفِّر الهوية استجابة "خطأ"، يمكن للجهة المحظورة رصدها، كما يُبلغ Chrome المستخدم من خلال عرض واجهة مستخدم للمتصفح بمعلومات الخطأ التي يوفرها موفِّر الهوية.

جيم
مربع حوار في FedCM يعرض رسالة الخطأ بعد تعذُّر محاولة تسجيل دخول المستخدم. ترتبط السلسلة بنوع الخطأ.
try {
  const cred = await navigator.credentials.get({
    identity: {
      providers: [
        {
          configURL: "https://idp.example/manifest.json",
          clientId: "1234",
        },
      ],
    }
  });
} catch (e) {
  const code = e.code;
  const url = e.url;
}

إعادة المصادقة التلقائية على المستخدمين بعد الموافقة الأولية

إعادة المصادقة التلقائية على FedCM (باختصار "إعادة المصادقة التلقائية" في FedCM) يمكن أن تسمح للمستخدمين بإعادة المصادقة تلقائيًا عندما يعودون مجددًا بعد المصادقة الأولية باستخدام FedCM. تعني "المصادقة الأولية" هنا أن المستخدم ينشئ حسابًا أو يسجّل الدخول إلى موقع الجهة المحظورة على الويب من خلال النقر على زر "متابعة باسم..." في مربع حوار تسجيل الدخول في FedCM لأول مرة على مثيل المتصفح نفسه.

على الرغم من أنّ تجربة المستخدم الواضحة منطقية قبل أن ينشئ المستخدم الحساب الموحّد لمنع التتبُّع (وهو أحد الأهداف الرئيسية لـ FedCM)، فإنها مرهقة بدون داعٍ بعد أن يمر بها المستخدم ذات مرة: بعد أن يمنح المستخدم الإذن للسماح بالتواصل بين الجهة المحظورة وموفِّر الهوية، لا توجد ميزة خصوصية أو أمان لفرض خصوصية أو ميزة من أجل فرض تأكيد صريح آخر للمستخدم على شيء سبق له إقراره.

باستخدام ميزة "إعادة المصادقة التلقائية"، يغيِّر المتصفّح سلوكه استنادًا إلى الخيار الذي حدّدته في mediation عند طلب navigator.credentials.get().

const cred = await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: "https://idp.example/fedcm.json",
      clientId: "1234",
    }],
  },
  mediation: 'optional', // this is the default
});

// `isAutoSelected` is `true` if auto-reauthn was performed.
const isAutoSelected = cred.isAutoSelected;

mediation هي سمة في واجهة برمجة تطبيقات إدارة بيانات الاعتماد، وهي تعمل بنفس الطريقة التي تعمل بها مع PasswordCredential و FederatedCredential وهو متوافق بشكل جزئي مع PublicKeyCredential أيضًا. تقبل السمة القيم الأربع التالية:

  • 'optional'(الخيار التلقائي): تتم إعادة المصادقة التلقائية إن أمكن، وتتطلب التوسّط في حال عدم حدوث ذلك. ننصحك بتحديد هذا الخيار في صفحة تسجيل الدخول.
  • 'required': يتطلب الأمر توسطًا دائمًا للمتابعة، مثل النقر على الزر "متابعة" في واجهة المستخدم. حدِّد هذا الخيار إذا كان من المتوقَّع أن يمنح المستخدمون الإذن صراحةً في كل مرة يحتاجون فيها إلى المصادقة.
  • 'silent': تتم إعادة المصادقة التلقائية إن أمكن، مع تعذُّر إتمام العملية بدون طلب معالجة إذا لم يكن الأمر كذلك. نقترح عليك تحديد هذا الخيار على الصفحات غير الصفحة المخصّصة لتسجيل الدخول، ولكن في الصفحات التي تريد إبقاء المستخدمين مسجّلين الدخول فيها، مثل صفحة عنصر على موقع إلكتروني للشحن أو صفحة مقالة على موقع إلكتروني إخباري.
  • 'conditional': يُستخدم في WebAuthn وغير متاح لبرنامج FedCM في الوقت الحالي.

من خلال هذه المكالمة، تتم إعادة المصادقة التلقائية في حال استيفاء الشروط التالية:

  • تتوفر خدمة FedCM للاستخدام. على سبيل المثال، لم يقم المستخدم بإيقاف FedCM على مستوى العالم أو لدى الجهة المحظورة في الإعدادات.
  • استخدم المستخدم حسابًا واحدًا فقط مع FedCM API لتسجيل الدخول إلى الموقع الإلكتروني على هذا المتصفح.
  • سجَّل المستخدم الدخول إلى موفِّر الهوية باستخدام هذا الحساب.
  • لم تحدث إعادة المصادقة التلقائية خلال آخر 10 دقائق.
  • لم يستدعي الجهة المحظورة navigator.credentials.preventSilentAccess() بعد تسجيل الدخول السابق.

عند استيفاء هذه الشروط، تبدأ محاولة إعادة مصادقة المستخدم تلقائيًا فور استدعاء navigator.credentials.get() في FedCM.

عند استخدام mediation: optional، قد تصبح ميزة إعادة المصادقة التلقائية غير متاحة لأسباب لا يعرفها إلا المتصفّح. ويمكن للجهة المحظورة التحقّق مما إذا كانت ميزة إعادة المصادقة التلقائية قد تم إجراؤها من خلال فحص السمة isAutoSelected.

ويساعد ذلك في تقييم أداء واجهة برمجة التطبيقات وتحسين تجربة المستخدم وفقًا لذلك. وأيضًا، عندما لا تكون هذه الميزة متاحة، قد يُطلب من المستخدم تسجيل الدخول من خلال توسّط مستخدم صريح، وهو مسار باستخدام mediation: required.

إعادة المصادقة التلقائية لمستخدم من خلال برنامج FedCM

فرض التوسّط باستخدام preventSilentAccess()

لن تؤدي إعادة المصادقة التلقائية للمستخدمين مباشرةً بعد تسجيل الخروج إلى تقديم تجربة جيدة للمستخدم. لهذا السبب، لدى FedCM فترة انتظار مدتها 10 دقائق بعد إعادة المصادقة التلقائية لمنع هذا السلوك. وهذا يعني أنّ إعادة المصادقة التلقائية تتم مرة واحدة على الأكثر كل 10 دقائق ما لم يسجّل المستخدم الدخول مرة أخرى خلال 10 دقائق. على الجهة المحظورة أن تطلب من الجهة المحظورة navigator.credentials.preventSilentAccess() صراحةً أن تطلب من المتصفّح إيقاف ميزة إعادة المصادقة التلقائية عندما يسجّل المستخدم الخروج من الجهة المحظورة بشكل صريح، مثلاً من خلال النقر على زر تسجيل الخروج.

function signout() {
  navigator.credentials.preventSilentAccess();
  location.href = '/signout';
}

يمكن للمستخدمين إيقاف ميزة إعادة المصادقة التلقائية في الإعدادات.

ويمكن للمستخدمين إيقاف ميزة إعادة المصادقة التلقائية من قائمة الإعدادات:

  • في متصفح Chrome على سطح المكتب، انتقل إلى chrome://password-manager/settings > تسجيل الدخول تلقائيًا.
  • في نظام التشغيل Android Chrome، افتح الإعدادات > مدير كلمات المرور > انقر على ترس في أعلى يسار الشاشة > تسجيل الدخول التلقائي.

ومن خلال إيقاف مفتاح التبديل، يمكن للمستخدم إيقاف إجراء إعادة المصادقة التلقائية معًا. ويتم تخزين هذا الإعداد ومزامنته على جميع الأجهزة، في حال تسجيل دخول المستخدم إلى حساب Google على النسخة الافتراضية من Chrome وتفعيل المزامنة.

إلغاء ربط موفِّر الهوية بالجهة المحظورة

إذا سجّل مستخدم في السابق الدخول إلى الجهة المحظورة باستخدام موفِّر الهوية من خلال FedCM، يتم حفظ العلاقة من خلال المتصفِّح محليًا باعتبارها قائمة الحسابات المرتبطة. قد يبدأ الجهة المحظورة عملية قطع الاتصال من خلال استدعاء الدالة IdentityCredential.disconnect(). يمكن استدعاء هذه الدالة من إطار RP ذي المستوى الأعلى. يحتاج الجهة المحظورة إلى تمرير configURL، وclientId التي يستخدمها ضمن موفِّر الهوية، وaccountHint لإلغاء ربط موفِّر الهوية. يمكن أن يكون تلميح الحساب سلسلة عشوائية طالما أنّ نقطة نهاية إلغاء الربط يمكنها تحديد الحساب، على سبيل المثال، عنوان البريد الإلكتروني أو رقم تعريف المستخدم الذي لا يتطابق بالضرورة مع رقم تعريف الحساب الذي وفّرته نقطة نهاية قائمة الحسابات:

// Disconnect an IdP account "account456" from the RP "https://idp.com/". This is invoked on the RP domain.
IdentityCredential.disconnect({
  configURL: "https://idp.com/config.json",
  clientId: "rp123",
  accountHint: "account456"
});

تعرض الدالة IdentityCredential.disconnect() القيمة Promise. قد ينتج عن هذا الوعد استثناء للأسباب التالية:

  • لم يسجِّل المستخدم الدخول إلى الجهة المحظورة باستخدام موفِّر الهوية من خلال برنامج FedCM.
  • يتم استدعاء واجهة برمجة التطبيقات من داخل إطار iframe بدون سياسة أذونات FedCM.
  • عنوان configURL غير صالح أو تنقصه نقطة نهاية إلغاء الربط.
  • تعذَّر التحقّق من سياسة أمان المحتوى (CSP).
  • هناك طلب إلغاء ربط في انتظار المراجعة.
  • أوقف المستخدم برنامج FedCM في إعدادات المتصفح.

عندما تعرض نقطة نهاية إلغاء ربط موفِّر الهوية استجابةً، يتم إلغاء ربط موفِّر الهوية (RP) وموفِّر الهوية (IdP) على المتصفِّح ويتم حلّ المشكلة. يتم تحديد رقم تعريف الحسابات غير المرتبطة في الاستجابة من نقطة نهاية إلغاء الربط.

الاتصال بـ FedCM من داخل إطار iframe متعدد المصادر

يمكن استدعاء برنامج FedCM من داخل إطار iframe متعدد المصادر باستخدام سياسة أذونات identity-credentials-get، إذا كان الإطار الرئيسي يسمح بذلك. ولإجراء ذلك، أضِف السمة allow="identity-credentials-get" إلى علامة iframe على النحو التالي:

<iframe src="https://fedcm-cross-origin-iframe.glitch.me" allow="identity-credentials-get"></iframe>

يمكنك الاطّلاع على هذه البيانات وهي قيد التنفيذ في مثال.

اختياريًا، إذا أراد الإطار الرئيسي تقييد المصادر التي يمكنها استدعاء FedCM، أرسِل عنوان Permissions-Policy مع قائمة بالمصادر المسموح بها.

Permissions-Policy: identity-credentials-get=(self "https://fedcm-cross-origin-iframe.glitch.me")

يمكنك الاطّلاع على المزيد من المعلومات حول آلية عمل "سياسة الأذونات" على الرابط التحكّم في ميزات المتصفّح باستخدام سياسة الأذونات.