دليل مطوّري واجهة برمجة التطبيقات Federated Credential Management API

تعرَّف على كيفية استخدام FedCM للحفاظ على الخصوصية في عملية دمج الهوية.

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

للاطّلاع على مزيد من المعلومات عن حالات استخدام FedCM ومسارات المستخدمين وخطة عمل واجهة برمجة التطبيقات، يمكنك الاطّلاع على introductio to FedCM API.

بيئة تطوير FedCM

يجب أن يكون لديك سياق آمن (HTTPS أو localhost) في كلّ من موفّر خدمة المصادقة وموفّر الخدمة في Chrome لاستخدام FedCM.

تصحيح أخطاء الرمز البرمجي على Chrome على Android

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

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

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

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

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

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

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

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

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

إنشاء ملف well-known

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

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

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

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

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

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

يتم تحديد عنوان URL لملف الضبط من خلال القيم المقدَّمة لاستدعاء navigator.credentials.get الذي يتم تنفيذه على جهاز RP.

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() على RP، يُجلب المتصفّح ملف الإعدادات باستخدام طلب GET بدون عنوان Origin أو عنوان Referer. لا يتضمّن الطلب ملفات تعريف الارتباط ولا يتّبع عمليات إعادة التوجيه. ويؤدي ذلك إلى منع موفِّر الهوية بشكل فعّال من معرفة الجهة التي قدّمت الطلب ومحاولة ربطه بأحد موفِّري خدمات الربط. على سبيل المثال:

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 لصفحة تسجيل الدخول للمستخدم لتسجيل الدخول إلى موفِّر الهوية
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.

يمكن لـ RP تعديل السلسلة في واجهة مستخدم مربّع حوار FedCM باستخدام قيمة 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
    }]
  }
}

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

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

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

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

يُرسِل المتصفّح طلبًا من النوع 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 (اختياري) صفيف من أرقام تعريف عملاء RP التي سجّل المستخدم نفسه بها
login_hints (اختياري) مصفوفة من جميع أنواع الفلاتر الممكنة التي يتيحها موفِّر الهوية لتحديد حساب يمكن لـ RP استدعاء navigator.credentials.get() باستخدام الموقع loginHint لإظهار الحساب المحدّد بشكل انتقائي.
domain_hints (اختياري) صفيف يضمّ جميع النطاقات المرتبطة بالحساب يمكن لـ RP الاتصال بـ 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 (غير مصرّح به).

يستخدم المتصفّح قائمة الحسابات التي تم عرضها ولن تكون متاحة لمسؤول المراجعة.

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

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

يُرسِل المتصفّح طلب 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. حدِّد نقطة الاتصال (RP) للعنصر 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",
}

يستخدم المتصفّح البيانات الوصفية للعميل المعروضة ولن تكون متاحة لجهاز RP.

نقطة نهاية بيان الهوية

تعرض نقطة نهاية بيان الهوية لموفِّر الهوية بيانًا للمستخدم الذي سجّل الدخول. عندما يسجّل المستخدم الدخول إلى موقع إلكتروني تابع لخدمة مقارنة الأسعار باستخدام 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". ويساعد ذلك في توفير المزيد من الميزات المتعلّقة بالأمان. على سبيل المثال، قد يفضّل بعض المستخدمين مستوى أمان أعلى يتطلّب توسّط المستخدم بشكل صريح في المصادقة. إذا تلقّى موفّر الهوية طلب رمز مميّز بدون هذا التوسّط، يمكنه معالجة الطلب بشكل مختلف. على سبيل المثال، يمكنك عرض رمز خطأ ليتمكّن موفِّر المحتوى من طلب بيانات من واجهة برمجة التطبيقات 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 بمصدر RP الذي يحدّده 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 بمصدر RP الذي يحدّده client_id. ارفض الطلب في حال عدم تطابقه.
  4. قارِن account_hint مع أرقام تعريف الحسابات التي سبق أن سجّلت الدخول إليها.
  5. افصل حساب المستخدم عن نقطة الربط.
  6. يجب الردّ على المتصفّح بمعلومات حساب المستخدم المحدّد بتنسيق JSON.

في ما يلي مثال على حِمل JSON للاستجابة:

{
  "account_id": "account456"
}

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

عنوان URL لصفحة تسجيل الدخول

باستخدام واجهة برمجة التطبيقات Login Status API، يجب أن يُعلم موفِّر الهوية المتصفح بحالة تسجيل دخول المستخدم. ومع ذلك، قد لا تكون الحالة متزامنة، مثل عند انتهاء صلاحية الجلسة. في مثل هذا السيناريو، يمكن للمتصفّح السماح للمستخدم بتسجيل الدخول إلى موفِّر الهوية ديناميكيًا من خلال عنوان URL لصفحة تسجيل الدخول الذي تم تحديده باستخدام login_url في ملف إعدادات موفِّر الهوية.

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

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

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

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

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

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

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

Login Status API هي آلية يُعلم من خلالها الموقع الإلكتروني، ولا سيما موفّر الهوية، المتصفّح بحالة تسجيل دخول المستخدم على موفّر الهوية. باستخدام واجهة برمجة التطبيقات هذه، يمكن للمتصفّح تقليل الطلبات غير الضرورية إلى مزوّد الهوية وخدمات المصادقة والحدّ من الهجمات المحتملة المتعلّقة بالتوقيت.

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

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

Set-Login: logged-in

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

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

تسجِّل هذه المكالمات حالة تسجيل دخول المستخدم على أنّها logged-in. عندما يتم ضبط حالة تسجيل دخول المستخدِم على logged-in، يُرسِل مقدّم الطلبات الذي يتصل بـ FedCM طلبات إلى نقطة نهاية حسابات موفِّر الهوية ويعرض للمستخدم الحسابات المتاحة في مربع diálogo 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 قبل أن يرسل موفّر الهوية إشارة باستخدام Login Status API. تمّ تقديم Unknown لعملية انتقال أفضل، لأنّه من الممكن أن يكون المستخدِم قد تسجيل دخوله إلى موفِّر الهوية (IdP) عندما تم طرح واجهة برمجة التطبيقات هذه. قد لا تتوفر لدى موفِّر الهوية فرصة للإشارة إلى ذلك للمتصفّح بحلول وقت استدعاء FedCM لأول مرة. في هذه الحالة، يُرسل Chrome طلبًا إلى نقطة نهاية حسابات موفِّر الهوية ويُعدِّل الحالة استنادًا إلى الاستجابة الواردة من نقطة نهاية الحسابات:

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

السماح للمستخدم بتسجيل الدخول من خلال عملية تسجيل دخول ديناميكية

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

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

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

قبل طلب البيانات من واجهة برمجة التطبيقات، عليك التأكّد من أنّ FedCM متاح في browser العميل. للتحقّق من توفّر 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 التي يوفّرها نقاط نهاية الحسابات، يعرِض مربّع حوار FedCM الحساب المحدّد بشكل انتقائي.
domainHint (اختياري) من خلال تحديد إحدى قيم domain_hints التي يوفّرها نقاط نهاية الحسابات، يعرِض مربّع حوار FedCM الحساب المحدّد بشكل انتقائي.

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

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

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

عندما يتصل موفِّر المحتوى بـ navigator.credentials.get()، تتم تنفيذ الأنشطة التالية:

  1. يرسل المتصفّح الطلبات ويُجلب عدة مستندات:
    1. ملف well-known وملف إعدادات موفِّر الهوية اللذان يحددان نقاط النهاية
    2. قائمة الحسابات
    3. اختياري: عناوين URL لسياسة خصوصية مقدّم الخدمة وأحكام الخدمة، يتم استرجاعها من نقطة نهاية البيانات الوصفية للعميل.
  2. يعرض المتصفّح قائمة الحسابات التي يمكن للمستخدم استخدامها لتسجيل الدخول، بالإضافة إلى بنود الخدمة وسياسة الخصوصية إذا كانت متاحة.
  3. بعد أن يختار المستخدم حسابًا لتسجيل الدخول باستخدامه، يتم إرسال طلب إلى نقطة نهاية تأكيد هوية العميل إلى موفِّر الهوية لاسترداد رمز متغيّر.
  4. يمكن لمسؤول المعالجة إثبات صحة الرمز المميّز لمصادقة المستخدم.
طلب بيانات من واجهة برمجة التطبيقات لتسجيل الدخول
طلب واجهة برمجة التطبيقات لتسجيل الدخول

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

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

Login Hint API

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

يمكن لتطبيقات 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 طلب تسجيل الدخول، الذي يسمح للمستخدم بتسجيل الدخول إلى حساب موفِّر الهوية (IdP) يتطابق مع التلميح الذي طلبه موفِّر الموارد (RP). عندما ينقر المستخدم على الطلب، يتم فتح نافذة منبثقة تتضمّن عنوان URL لتسجيل الدخول المحدّد في ملف الإعدادات. بعد ذلك، تتم إضافة مَعلمات طلب البحث عن تلميح تسجيل الدخول وتلميح النطاق إلى الرابط.

Domain Hint API

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

يمكن لتطبيقات 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 طلب تسجيل الدخول، الذي يسمح للمستخدم بتسجيل الدخول إلى حساب موفِّر الهوية (IdP) يتطابق مع التلميح الذي طلبه موفِّر الموارد (RP). عندما ينقر المستخدم على الطلب، يتم فتح نافذة منبثقة تتضمّن عنوان URL لتسجيل الدخول المحدّد في ملف الإعدادات. بعد ذلك، تتم إضافة مَعلمات طلب البحث عن تلميح تسجيل الدخول وتلميح النطاق إلى الرابط.

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

عرض رسالة خطأ

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

A
مربّع حوار 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 للمرة الأولى في مثيل المتصفّح نفسه.

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

من خلال إعادة المصادقة التلقائية، يغيّر المتصفّح سلوكه استنادًا إلى الخيار الذي تحديده لـ 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، قد تكون إعادة المصادقة التلقائية غير متاحة لأسباب يعرفها المتصفّح فقط. يمكن لمسؤول المعالجة التحقّق مما إذا تم إجراء إعادة المصادقة التلقائية من خلال examining the isAutoSelected property.

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

يعيد المستخدِم المصادقة تلقائيًا من خلال FedCM.

فرض التوسّط مع preventSilentAccess()

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

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

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

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

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

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

إلغاء ربط موفِّر الهوية بمسؤول المعالجة

إذا سجّل مستخدم الدخول إلى مقدّم الخدمة باستخدام موفِّر الهوية من خلال FedCM، يحفظ المتصفّح ملفًا شخصيًا على الجهاز كقائمة بالحسابات المرتبط بها. يمكن أن يبدأ RP عملية قطع الاتصال من خلال استدعاء الدالة 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 في إعدادات المتصفّح.

عندما تعرض نقطة نهاية إلغاء الربط في موفِّر الهوية رداً، يتم إلغاء ربط موفِّر الهوية ومسؤول المعالجة في المتصفّح ويتم حلّ الوعد. يتم تحديد معرّف الحسابات التي تم إلغاء ربطها في الاستجابة من نقطة نهاية إلغاء الربط.

استدعاء 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")

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