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

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

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

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

بيئة تطوير FedCM

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

يوفِّر ملف إعداد موفِّر الهوية قائمة بنقاط النهاية المطلوبة للمتصفِّح. IdPs يستضيف ملف الإعداد هذا ونقاط النهاية وعناوين 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 كاملاً لموقع ملف إعدادات موفِّر الهوية (idP) على أنّه configURL. فعندما يتم استدعاء navigator.credentials.get() على الجهة المحظورة، وهو المتصفِّح جلب ملف الإعداد باستخدام طلب GET بدون العنوان Origin عنوان Referer لا يحتوي الطلب على ملفات تعريف ارتباط ولا يتّبع عمليات إعادة التوجيه. ويمنع ذلك موفِّر الهوية بشكل فعّال من معرفة هوية الشخص الذي قدَّم الطلب يحاول الجهة المحظورة الاتصال. على سبيل المثال:

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

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

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

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

{
  "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
    }]
  }
}

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

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

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

يرسل المتصفّح طلب 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. باستخدام مصفوفة من معلومات الحساب مع المواقع التالية:

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

{
  "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. الرد باستخدام البيانات الوصفية للعميل

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

ويتوقّع المتصفّح استجابة 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 إلى نقطة النهاية هذه بالمعلومات التالية:

مثال على عنوان 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. قم بالرد باستخدام رمز مميز. في حال رفض الطلب، عرض خطأ الرد.

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

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

{
  "token": "***********"
}

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

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

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

• code: يمكن لموفِّر الهوية اختيار أحد الأخطاء المعروفة من OAuth 2.0. الخطأ المحدد قائمة (invalid_request وunauthorized_client وaccess_denied وserver_error temporarily_unavailable) أو استخدام أي سلسلة عشوائية. إذا لم يكُن الأمر كذلك، عرض واجهة المستخدم التي تعرض الخطأ مع رسالة خطأ عامة وتمرير الرمز إلى الجهة المحظورة.
• 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 لنقطة نهاية قطع الاتصال هذه المعلومات التالية:

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"
}

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

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

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

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

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

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

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

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

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

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

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

Set-Login: logged-in

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

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

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

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

Set-Login: logged-out

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

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

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

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

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

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

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

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

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

قبل طلب واجهة برمجة التطبيقات، يجب التأكد من أن [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. الكائنات التي لها السمات التالية:

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

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

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

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

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

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

واجهة برمجة تطبيقات تلميح النطاق

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

يمكن للجهات المحظورة عرض الحسابات المطابقة فقط بشكل انتقائي من خلال استدعاء 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) المُطابق للتلميح الذي طلبه الجهة المحظورة. عندما ينقر المستخدم على الطلب، يتم فتح نافذة منبثقة تحتوي على عنوان URL لتسجيل الدخول المحدّد في ملف الإعداد. ثم يكون الرابط مرفقة بتلميح تسجيل الدخول ومعلمات طلب البحث لتلميح النطاق.

إظهار رسالة خطأ

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

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) يصبح الأمر مرهقًا بشكل غير ضروري بعد أن يمر بها المستخدم مرة واحدة: بعد أن يمنح المستخدم إذنًا للسماح بالاتصال بين الجهة المحظورة وموفِّر الهوية ما مِن فائدة تتعلّق بالخصوصية أو الأمان في حال فرض مستخدم آخر فاضح. تأكيدًا لشيء ما اعترفوا به مسبقًا.

من خلال إعادة المصادقة التلقائية، يغيّر المتصفّح سلوكه استنادًا إلى الخيار الذي حدد قيمة 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.

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

فرض التوسّط مع 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، يتم حفظ العلاقة من خلال المتصفح محليًا كقائمة الشبكات الحسابات. يمكن أن يبدأ الجهة المحظورة قطع الاتصال من خلال استدعاء IdentityCredential.disconnect(). ويمكن استدعاء هذه الدالة من إطار الجهة المحظورة من المستوى الأعلى على الجهة المحظورة أن تجتاز configURL، وهي clientId التي يستخدمها. ضمن موفِّر الهوية، ورقم accountHint لإلغاء ربط موفِّر الهوية (idP). حساب يمكن أن يكون التلميح سلسلة عشوائية طالما أن نقطة نهاية الفصل يمكن أن تحدد الحساب، مثل عنوان بريد إلكتروني أو رقم تعريف مستخدم ليس بالضرورة تتطابق مع رقم تعريف الحساب الذي توفّره نقطة نهاية قائمة الحسابات:

// 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. قد يؤدي هذا الوعد إلى استثناء للأسباب التالية:

• لم يسجِّل المستخدم الدخول إلى الجهة المحظورة باستخدام موفِّر الهوية من خلال برنامج "المراسلة عبر السحابة الإلكترونية من Firebase".
• يتم استدعاء واجهة برمجة التطبيقات من داخل إطار 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")

يمكنك معرفة المزيد من المعلومات عن كيفية عمل سياسة الأذونات في صفحة التحكم في ميزات المتصفّح ذات الأذونات السياسة: