دليل المطوِّر حول استخدام 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

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

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

استخدام FedCM API

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

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

إنشاء ملف well-known

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

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

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

يقدّم ملف إعدادات مزوّد الهوية قائمة بنقاط النهاية المطلوبة للمتصفح. ستستضيف منصّات إدارة الهوية ملف الإعدادات هذا ونقاط النهاية وعناوين URL المطلوبة. ويجب عرض كلّ application/json 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".

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

{
  "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:

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

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

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

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

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

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

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

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

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

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

تعرض نقطة نهاية بيان الهوية لموفِّر الهوية بيانًا للمستخدم الذي سجّل الدخول. عندما يسجّل المستخدم الدخول إلى موقع إلكتروني لجهة محظورة باستخدام navigator.credentials.get() call، يرسِل المتصفّح طلب 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. قم بالرد باستخدام رمز مميز. في حال رفض الطلب، يمكنك الردّ بإرسال استجابة بالخطأ.

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

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

{
  "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 إلى نقطة نهاية قطع الاتصال هذه باستخدام المعلومات التالية:

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 لتسجيل الدخول

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

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

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

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

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

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

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 في شريط تنقّل المستوى الأعلى أو طلب مورد فرعي للموقع الإلكتروني نفسه في مصدر موفِّر الهوية (idP):

Set-Login: logged-out

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

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

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

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

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

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

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

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

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

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

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

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 إما بشكل عام أو لوحدة RP في الإعدادات.
• استخدم المستخدم حسابًا واحدًا فقط مع واجهة برمجة تطبيقات FedCM لتسجيل الدخول إلى الموقع الإلكتروني على هذا المتصفح.
• سجَّل المستخدم الدخول إلى موفِّر الهوية باستخدام هذا الحساب.
• لم تتم إعادة المصادقة التلقائية خلال آخر 10 دقائق.
• لم يستدعي الجهة المحظورة navigator.credentials.preventSilentAccess() بعد تسجيل الدخول السابق.

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

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

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

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

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