تنفيذ حلّ للتحقّق من الهوية باستخدام FedCM من جهة موفّر الهوية

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

يتضمّن تنفيذ FedCM عدة خطوات أساسية لكل من موفِّر الهوية (IdP) والجهة المعتمِدة (RP). راجِع المستندات لمعرفة كيفية تنفيذ FedCM من جهة موفّر الهوية.

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

على IdPs إكمال الخطوات التالية لتنفيذ FedCM:

1. أنشئ ملف well-known.
2. أنشئ ملف إعداد.
3. أنشِئ نقاط النهاية التالية:
   • نقطة نهاية الحساب
   • نقطة نهاية تأكيد الهوية
   • [اختيارية] إلغاء ربط نقطة النهاية
   • [اختيارية] نقطة نهاية البيانات الوصفية للعميل
   • نقطة نهاية تسجيل الدخول
4. إعلام المتصفّح بحالة تسجيل دخول المستخدم

إنشاء ملف well-known

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

يمكن أن يتضمّن الملف المعروف جيدًا الخصائص التالية:

الموقع	مطلوب	الوصف
accounts_endpoint	مطلوب إذا كان ملف الإعداد يتضمّن نقطة نهاية client_metadata.	عنوان URL لنقطة نهاية الحسابات يتيح ذلك إمكانية استخدام إعدادات متعددة، طالما أنّ كل ملف إعداد يستخدم عنوان URL نفسه login_url وaccounts_endpoint. ملاحظة: تتوفّر المَعلمة بدءًا من الإصدار 132 من Chrome.
login_url	مطلوب إذا كان ملف الإعداد يتضمّن نقطة نهاية client_metadata.	عنوان URL لصفحة تسجيل الدخول الذي يستخدمه المستخدم لتسجيل الدخول إلى موفِّر الهوية يتيح ذلك إمكانية استخدام إعدادات متعددة، طالما أنّ كل ملف إعداد يستخدم login_url وaccounts_endpoint نفسيهما. ملاحظة: تتوفّر المَعلمة بدءًا من الإصدار 132 من Chrome والإصدارات الأحدث.

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

  {
     // You must include accounts_endpoint and login_url if your
     // config file specifies a client_metadata_endpoint
    "accounts_endpoint": "https://accounts.idp.example/accounts",
    "login_url": "https://accounts.idp.example/login"
  }

يمكن لموفِّري الهوية استيعاب ملفات إعداد متعددة لموفِّر الهوية، وذلك من خلال تحديد accounts_endpoint وlogin_url في ملف well-known. يمكن أن تكون هذه الميزة مفيدة في الحالات التالية:

• يجب أن يتيح موفِّر الهوية إعدادات اختبار وإنتاج مختلفة ومتعددة.
• يجب أن يتيح موفِّر الهوية إعدادات مختلفة لكل منطقة (على سبيل المثال، eu-idp.example وus-idp.example).

لإتاحة إعدادات متعدّدة (على سبيل المثال، للتمييز بين بيئة الاختبار وبيئة الإنتاج)، يجب أن يحدّد موفِّر الهوية accounts_endpoint وlogin_url:

  {
    // This property is required, but will be ignored when IdP supports
    // multiple configs (when `accounts_endpoint` and `login_url` are
    // specified), as long as `accounts_endpoint` and `login_url` in
    // that config file match those in the well-known file.
    "provider_urls": [ "https://idp.example/fedcm.json" ],

    // Specify accounts_endpoint and login_url properties to support
    // multiple config files.
    // Note: The accounts_endpoint and login_url must be identical
    // across all config files. Otherwise,
    // the configurations won't be supported.
    "accounts_endpoint": "https://idp.example/accounts",
    "login_url": "https://idp.example/login"
  }

ملاحظة: عند استخدام FedCM، قد تكون نطاقات خادم RP التجريبية أو المرحلية هي النطاقات الفرعية لخادم موفّر الهوية (IdP) المخصّص للإنتاج. على سبيل المثال، يقع خادم موفِّر الهوية الخاص بالإنتاج على idp.example، ويقع كل من خادم RP الخاص بمرحلة الاختبار وخادم موفِّر الهوية الخاص بمرحلة الاختبار على staging.idp.example. ومع ذلك، بما أنّ ملف well-known يجب أن يكون في جذر eTLD+1 لخادم موفّر الهوية، يجب أن يكون في idp.example/.well-known/web-identity وهو خادم الإنتاج. بما أنّه ليس من الضروري أن يتمكّن المطوّرون من وضع الملفات في بيئة الإنتاج أثناء عملية التطوير، يمنعهم ذلك من اختبار FedCM. إذا كان نطاق RP هو نفسه نطاق IdP، يمكن لمتصفّح Chrome تخطّي التحقّق من الملف المعروف بدءًا من الإصدار 122 من Chrome. يمكنك أيضًا تجاوز عملية التحقّق configURL من خلال تفعيل العلامة chrome://flags#fedcm-without-well-known-enforcement. ويكون ذلك مفيدًا عندما تستخدم بيئة التطوير نظام أسماء نطاقات لا يمكن الوصول إليه بشكل علني.

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

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

يتم تحديد عنوان URL لملف الإعداد من خلال القيم المقدَّمة إلى استدعاء navigator.credentials.get() الذي يتم تنفيذه على RP. سيمرّر موفّر الهوية عنوان URL لملف الإعداد لكل موفّر هوية:

  // Executed on RP's side:
  try {
    const credential = await navigator.credentials.get({
      identity: {
        providers: [
          {
            // To allow users to sign in with the IdP1 using FedCM, RP specifies the IdP's config file URL:
            configUrl: 'https://idp1.example/foo.json', // first IdP
            clientId: '123',
          },
          // To allow users to sign in with the IdP2 using FedCM, RP specifies the IdP's config file URL.
          // Note that multiple IdPs in a single get() are supported from Chrome 136.
          {
            configUrl: 'https://idp2.example/bar.json', // second IdP
            clientId: '456',
          },
        ],
      },
    });

    const token = credential.token;
    // Get the current IdP's configURL to identify which provider the user is signed in with
    const currentIdpConfigUrl = credential.configURL;
    if (currentIdpConfigUrl === 'https://idp1.example/foo.json') {
      // handle the case where the user signed in with idp1
    } else if (currentIdpConfigUrl === 'https://idp2.example/bar.json') {
      // handle the case where the user signed in with idp2
    }
  } catch (error) {
    // handle error
  }

سيجلب المتصفّح ملف الإعدادات باستخدام طلب GET بدون العنوان Origin أو العنوان Referer. لا يتضمّن الطلب ملفات تعريف الارتباط ولا يتّبع عمليات إعادة التوجيه. يمنع ذلك بشكل فعّال موفّر الهوية من معرفة هوية المستخدم الذي أرسل الطلب وموفّر الخدمة الذي يحاول الربط. على سبيل المثال:

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

تنبيه: تتضمّن جميع الطلبات المُرسَلة من المتصفّح باستخدام FedCM عنوان Sec-Fetch-Dest: webidentity لمنع هجمات تزوير الطلبات عبر المواقع. يجب أن تؤكّد نقاط نهاية موفِّر الهوية التالية تضمين هذا العنوان:

• نقطة نهاية الحسابات
• نقطة نهاية تأكيد الهوية
• إلغاء ربط نقطة النهاية

يجب أن تنفّذ جهة توفير الهوية نقطة نهاية إعداد تستجيب باستخدام JSON. يتضمّن ملف JSON السمات التالية:

الموقع	الوصف
accounts_endpoint (مطلوب)	عنوان URL لنقطة نهاية الحسابات
account_label (اختياري)	سلسلة تصنيف الحساب المخصّص، التي تحدّد الحسابات التي يجب عرضها عند استخدام ملف الإعداد هذا، على سبيل المثال: "account_label": "developer". يمكن لموفّر الهوية تنفيذ تصنيف مخصّص للحساب على النحو التالي: أنشئ ملف إعداد مرتبطًا بتصنيفات معيّنة (باستخدام المَعلمة account_label). حدِّد التصنيفات في نقطة نهاية الحسابات. على سبيل المثال، ينفّذ موفِّر الهوية "https://idp.example/developer-config.json" ملف إعداد مع تحديد "account_label": "developer". تضع خدمة IdP أيضًا التصنيف "developer" على بعض الحسابات باستخدام المَعلمة label_hints في نقطة نهاية الحسابات. عندما يطلب RP navigator.credentials.get() مع تحديد ملف الإعداد "https://idp.example/developer-config.json"، سيتم عرض الحسابات التي تحمل التصنيف "developer" فقط. ملاحظة: تتوفّر تصنيفات الحسابات المخصّصة بدءًا من الإصدار 132 من Chrome.
supports_use_other_account (اختياري)	قيمة منطقية تحدّد ما إذا كان بإمكان المستخدم تسجيل الدخول باستخدام حساب مختلف عن الحساب الذي سجّل الدخول به (إذا كان موفّر خدمة تحديد الهوية يتيح استخدام حسابات متعددة). ينطبق ذلك على وضع النشاط فقط.
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 بكسل في الوضع السلبي وأكبر من أو يساوي 40 بكسل في الوضع النشط.

في ما يلي مثال على نص الرد من موفّر خدمة تحديد الهوية:

  {
    "accounts_endpoint": "/accounts.example",
    "client_metadata_endpoint": "/client_metadata.example",
    "id_assertion_endpoint": "/assertion.example",
    "disconnect_endpoint": "/disconnect.example",
    "login_url": "/login",
    // When RPs use this config file, only those accounts will be
    //returned that include `developer` label in the accounts endpoint.
    "account_label": "developer",
    "supports_use_other_account": true,
    "branding": {
      "background_color": "green",
      "color": "#FFEEAA",
      "icons": [{
        "url": "https://idp.example/icon.ico",
        "size": 25
      }]
    }
  }

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

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

استخدام حساب آخر

يمكن للمستخدمين التبديل إلى حساب يختلف عن الحساب الذي سجّلوا الدخول إليه، إذا كانت خدمة IdP تتيح استخدام حسابات متعددة أو استبدال الحساب الحالي.

لتمكين المستخدم من اختيار حسابات أخرى، يجب أن يحدّد موفِّر الهوية هذه الميزة في ملف الإعداد:

  {
    "accounts_endpoint" : "/accounts.example",
    "supports_use_other_account": true
  }

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

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

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

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

عند تلقّي الطلب، على الخادم إجراء ما يلي:

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

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

الموقع	الوصف
id (مطلوب)	المعرّف الفريد للمستخدم
name	الاسم الكامل للمستخدم وفقًا للغته وإعداداته المفضّلة ملاحظة: بدءًا من الإصدار 141 من Chrome، يجب توفير إحدى المَعلمات name أو email أو username أو tel على الأقل. في إصدارات Chrome السابقة، يجب توفُّر كل من name وemail.
username	اسم مستخدم يختاره المستخدم ملاحظة: بدءًا من الإصدار 141 من Chrome، يجب توفير إحدى المَعلمات name أو email أو username أو tel على الأقل.
email	عنوان البريد الإلكتروني للمستخدم. ملاحظة: بدءًا من الإصدار 141 من Chrome، يجب توفير إحدى المَعلمات name أو email أو username أو tel على الأقل. في إصدارات Chrome السابقة، يجب توفُّر كل من name وemail.
tel	رقم هاتف المستخدِم ملاحظة: بدءًا من الإصدار 141 من Chrome، يجب توفير إحدى المَعلمات name أو email أو username أو tel على الأقل.
picture (اختياري)	عنوان URL لصورة الأفاتار للمستخدم
given_name (اختياري)	الاسم الأول للمستخدم
approved_clients (اختياري)	مصفوفة من أرقام تعريف عملاء "الطرف المعتمد" التي سجّل المستخدم بها
login_hints (اختياري)	مصفوفة تتضمّن جميع أنواع الفلاتر الممكنة التي يتيحها موفّر خدمة تحديد الهوية لتحديد حساب. يمكن لمقدّم الخدمة الاعتماد على navigator.credentials.get() مع السمة loginHint لعرض الحساب المحدّد بشكل انتقائي.
domain_hints (اختياري)	مصفوفة تتضمّن جميع النطاقات المرتبطة بالحساب. يمكن لموفّر الهوية (RP) استدعاء navigator.credentials.get() باستخدام السمة domainHint لفلترة الحسابات.
label_hints (اختياري)	مصفوفة من تصنيفات الحساب المخصّصة التي يرتبط بها الحساب. يمكن لموفّر الهوية تنفيذ تصنيف الحسابات المخصّص على النحو التالي: حدِّد تصنيفات الحسابات في نقطة نهاية الحسابات (باستخدام المَعلمة label_hints). أنشِئ ملف إعداد لكل تصنيف محدّد. على سبيل المثال، ينفّذ موفِّر الهوية https://idp.example/developer-config.json ملف إعداد مع تحديد "account_label": "developer". تضع خدمة IdP أيضًا التصنيف "developer" على بعض الحسابات باستخدام المَعلمة label_hints في نقطة نهاية الحسابات. عندما يطلب RP navigator.credentials.get() مع تحديد ملف إعداد https://idp.example/developer-config.json، سيتم عرض الحسابات التي تحمل التصنيف "developer" فقط. تختلف تصنيفات الحساب المخصّصة عن تلميح تسجيل الدخول وتلميح النطاق من حيث أنّ خادم موفِّر الهوية يحتفظ بها بالكامل، ولا يحدّد الطرف المعتمد إلا ملف الإعداد الذي سيتم استخدامه. ملاحظة: تتوفّر تصنيفات الحسابات المخصّصة بدءًا من الإصدار 132 من Chrome.

مثال على نص الرد:

  {
    "accounts": [{
      "id": "1234",
      "given_name": "John",
      "name": "John Doe",
      "email": "[e-mail]",
      "picture": "https://idp.example/profile/123",
      // Ids of those RPs where this account can be used
      "approved_clients": ["123", "456", "789"],
      // This account has 'login_hints`. When an RP calls `navigator.credentials.get()`
      // with a `loginHint` value specified, for example, `exampleHint`, only those
      // accounts will be shown to the user whose 'login_hints' array contains the `exampleHint`.
      "login_hints": ["demo1", "exampleHint"],
      // This account is labelled. IdP can implement a specific config file for a
      // label, for example, `https://idp.example/developer-config.json`. Like that
      // RPs can filter out accounts by calling `navigator.credentials.get()` with
      // `https://idp.example/developer-config.json` config file.
      "label_hints": ["enterprise", "developer"]
    }, {
      "id": "5678",
      "given_name": "Johnny",
      "name": "Johnny",
      "email": "[e-mail]",
      "picture": "https://idp.example/profile/456",
      "approved_clients": ["abc", "def", "ghi"],
      "login_hints": ["demo2"],
      "domain_hints": ["@domain.example"]
    }]
  }

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

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

نقطة نهاية تأكيد الهوية

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

الموقع	الوصف
client_id (مطلوب)	معرّف العميل الخاص بطرف الاعتماد.
account_id (مطلوب)	المعرّف الفريد للمستخدم الذي سجّل الدخول.
disclosure_text_shown	تؤدي إلى ظهور سلسلة من "true" أو "false" (بدلاً من قيمة منطقية). تكون النتيجة "false" في الحالات التالية: إذا لم يظهر نص الإفصاح لأنّ معرّف عميل الشريك الإعلاني كان مضمّنًا في قائمة السمة approved_clients ضمن الردّ من نقطة نهاية الحسابات إذا لم يظهر نص الإفصاح لأنّ المتصفّح رصد لحظة اشتراك في الماضي بدون approved_clients. إذا كانت المعلَمة fields لا تتضمّن جميع الحقول الثلاثة ("name" و"email" و "picture")، مثلاً fields=[ ] أو fields=['name', 'picture']. وهو مطلوب للتوافق مع عمليات التنفيذ القديمة. ملاحظة: اعتبارًا من الإصدار 141 من Chrome، قد يتم عرض نص الإفصاح حتى إذا كانت قيمة disclosure_text_shown هي "false". للتحقّق مما إذا كان نص الإفصاح قد تم عرضه، راجِع قيمة disclosure_shown_for بدلاً من ذلك.
disclosure_shown_for	تدرِج هذه السمة الحقول التي عرضها المتصفّح للمستخدم في نص الإفصاح لإعلامه بالبيانات التي يطلبها الطرف المعتمد من موفِّر الهوية.
is_auto_selected	في حال إجراء إعادة المصادقة تلقائيًا على RP، يشير is_auto_selected إلى "true". في الحالات الأخرى، قُل "false". ويساعد ذلك في توفير المزيد من الميزات المتعلّقة بالأمان. على سبيل المثال، قد يفضّل بعض المستخدمين مستوى أمان أعلى يتطلّب وسيطة صريحة من المستخدم في عملية المصادقة. إذا تلقّى موفّر خدمة تحديد الهوية طلب رمز مميّز بدون هذا التوسّط، يمكنه التعامل مع الطلب بشكل مختلف. على سبيل المثال، يمكنك عرض رمز خطأ يتيح لموفّر الهوية استدعاء FedCM API مرة أخرى باستخدام mediation: required.
fields (اختياري)	مصفوفة من السلاسل تحدّد معلومات المستخدم التي طلب من موفّر خدمة الهوية مشاركتها. يمكن تحديد الحقول التالية بشكل اختياري: "name" "username" "email" "tel" "picture" سيرسل المتصفّح fields وdisclosure_text_shown وdisclosure_shown_for مع تضمين الحقول المحدّدة في طلب POST، كما هو موضّح في المثال التالي. ملاحظة: تتوافق Fields API مع الإصدار 132 من Chrome والإصدارات الأحدث. يتوفّر الحقلان `"username"` و `"tel"` بدءًا من الإصدار 141 من Chrome.
params (اختياري)	أي عنصر JSON صالح يسمح بتحديد مَعلمات مفتاح/قيمة مخصّصة إضافية، على سبيل المثال: ‫scope: قيمة سلسلة تحتوي على أذونات إضافية يحتاج "موفّر الخدمة" إلى طلبها، مثل "drive.readonly calendar.readonly" ‫nonce: سلسلة عشوائية يقدّمها "الطرف المعتمد" لضمان إصدار الردّ لهذا الطلب المحدّد. يمنع هجمات إعادة الإرسال. مَعلمات أخرى مخصّصة للمفاتيح والقيم عندما يرسل المتصفّح طلب POST، سيتم تحويل القيمة params إلى تنسيق JSON ثم ترميزها باستخدام النسبة المئوية. ملاحظة: تتوافق واجهة برمجة التطبيقات Parameters API مع الإصدار 132 من Chrome والإصدارات الأحدث.

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

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

  // disclosure_text_shown is set to 'false', as the 'name' field value is missing in 'fields' array
  // params value is serialized to JSON and then percent-encoded.
  account_id=123&client_id=client1234&disclosure_text_shown=false&is_auto_selected=true&params=%22%7B%5C%22nonce%5C%22%3A%5C%22nonce-value%5C%22%7D%22.%0D%0A4&fields=email,picture&disclosure_shown_for=email,picture

عند تلقّي الطلب، على الخادم إجراء ما يلي:

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

تحذير: يجب أن يكون طلب CORS معتمدًا، ما يعني أنّ عنوان الاستجابة Access-Control-Allow-Origin يجب أن يشير إلى مصدر محدّد بدلاً من حرف بدل باستخدام "*".

HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://rp.example
Access-Control-Allow-Credentials: true
  

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

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

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

الموقع	الوصف
token	الرمز المميّز هو سلسلة أو عنصر من النوع any يحتوي على بيانات حول المصادقة. ملاحظة: يتوفّر نوع العنصر بدءًا من الإصدار 143 من Chrome.
continue_on	عنوان URL لإعادة التوجيه الذي يتيح عملية تسجيل دخول متعددة الخطوات

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

{
  // IdP can respond with a token object to authenticate the user
  "token": {
    "access_token": "a1b2c3d4e5f6...",
    "user_info": {
      "email": "[e-mail]",
      "given_name": "Jane",
      "family_name": "Doe"
    }
  }
}

ميزة "المتابعة على"

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

• إذن الوصول إلى موارد المستخدم من جهة الخادم
• إثبات أنّ معلومات الاتصال محدَّثة
• أدوات رقابة الأهل

يمكن أن تعرض نقطة نهاية تأكيد الهوية السمة continue_on التي تتضمّن مسارًا مطلقًا أو نسبيًا إلى نقطة نهاية تأكيد الهوية.

  {
    // In the id_assertion_endpoint, instead of returning a typical
    // "token" response, the IdP decides that it needs the user to
    // continue on a dialog window:
    "continue_on": "https://idp.example/continue_on_url"
  }

إذا كانت الاستجابة تتضمّن المَعلمة continue_on، سيتم فتح نافذة حوار جديدة ونقل المستخدم إلى المسار المحدّد. بعد تفاعل المستخدم مع الصفحة continue_on، على موفِّر الهوية استدعاء IdentityProvider.resolve() مع الرمز المميز الذي تم تمريره كمعلَمة، وذلك حتى يمكن حل الوعد من طلب navigator.credentials.get() الأصلي:

  document.getElementById('example-button').addEventListener('click', async () => {
    let accessToken = await fetch('/generate_access_token.cgi');
    // Closes the window and resolves the promise (that is still hanging
    // in the relying party's renderer) with the value that is passed.
    IdentityProvider.resolve(accessToken);
  });

سيغلق المتصفّح بعد ذلك مربّع الحوار تلقائيًا وسيعيد الرمز المميز إلى برنامج واجهة برمجة التطبيقات الذي طلب الرمز. تُعدّ IdentityProvider.resolve() المكالمة لمرة واحدة الطريقة الوحيدة التي يمكن من خلالها لنافذة الوالد (RP) ونافذة الحوار (IdP) التواصل.
إذا رفض المستخدم الطلب، يمكن لموفّر خدمة تحديد الهوية إغلاق النافذة من خلال استدعاء IdentityProvider.close().

  IdentityProvider.close();

تتطلّب واجهة برمجة التطبيقات Continuation API تفاعلاً صريحًا من المستخدم (نقرات) لتعمل. في ما يلي طريقة عمل واجهة برمجة التطبيقات Continuation API مع أوضاع التوسّط المختلفة:

• في وضع passive:
  • ‫mediation: 'optional' (الإعداد التلقائي): لن تعمل Continuation API إلا مع إيماءة من المستخدِم، مثل النقر على زر في الصفحة أو على واجهة مستخدم FedCM. عندما يتم تشغيل عملية إعادة المصادقة التلقائية بدون إيماءة من المستخدم، لن يتم فتح مربّع حوار، وسيتم رفض الوعد.
  • ‫mediation: 'required': يطلب من المستخدم دائمًا التفاعل، وبالتالي تعمل واجهة برمجة التطبيقات Continuation API دائمًا.
• في الوضع النشط:
  • يجب دائمًا تفعيل المستخدم. تكون واجهة برمجة التطبيقات Continuation API متوافقة دائمًا.

إذا غيّر المستخدم حسابه في مربّع الحوار لسبب ما (على سبيل المثال، إذا كان موفّر خدمة تحديد الهوية يوفّر وظيفة "استخدام حساب آخر"، أو في حالات التفويض)، يتلقّى طلب resolve وسيطًا ثانيًا اختياريًا يسمح بما يلي:

  IdentityProvider.resolve(token, {accountId: '1234');

إرجاع ردّ يفيد بحدوث خطأ

يمكن أن تعرض 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"
    }
  }

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

تصنيفات الحساب المخصّصة

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

يمكن إجراء فلترة مشابهة باستخدام ميزتَي تلميح النطاق وتلميح تسجيل الدخول، وذلك من خلال تحديدهما في طلب navigator.credentials.get(). ومع ذلك، يمكن أن تفلتر "تصنيفات الحسابات المخصّصة" المستخدمين من خلال تحديد ملف الإعداد، وهو أمر مفيد بشكل خاص عند استخدام عناوين URL متعددة للإعداد. تختلف تصنيفات الحسابات المخصّصة أيضًا في أنّها يتم توفيرها من خادم موفّر خدمة تحديد الهوية، وليس من الجهة المعتمدة، مثل تلميحات تسجيل الدخول أو النطاق.

لنفترض أنّ موفّر خدمة هوية يريد التمييز بين حسابات "developer" وحسابات "hr". لتحقيق ذلك، يجب أن يتيح موفِّر الهوية استخدام عنوانَي URL للإعداد لكل من "developer" و"hr" على التوالي:

• يحتوي ملف إعدادات المطوّر https://idp.example/developer/fedcm.json على التصنيف "developer"، بينما يحتوي ملف إعدادات المؤسسة https://idp.example/hr/fedcm.json على التصنيف "hr" على النحو التالي:

  // The developer config file at `https://idp.example/developer/fedcm.json`
  {
    "accounts_endpoint": "https://idp.example/accounts",
    "client_metadata_endpoint": "/client_metadata",
    "login_url": "https://idp.example/login",
    "id_assertion_endpoint": "/assertion",
    "account_label": "developer"
  }

  // The hr config file at `https://idp.example/hr/fedcm.json`
  {
    "accounts_endpoint": "https://idp.example/accounts",
    "client_metadata_endpoint": "/client_metadata",
    "login_url": "https://idp.example/login",
    "id_assertion_endpoint": "/assertion",
    "account_label": "hr"
  }

• في حال استخدام هذا الإعداد، يجب أن يتضمّن ملف well-known accounts_endpoint وlogin_url للسماح باستخدام عناوين URL متعددة خاصة بالإعدادات:

  {
    "provider_urls": [ "https://idp.example/fedcm.json" ],
    "accounts_endpoint": "https://idp.example/accounts",
    "login_url": "https://idp.example/login"
  }

• تعرض نقطة نهاية الحسابات الخاصة بموفّر الهوية الشائع (IdP) (في هذا المثال https://idp.example/accounts) قائمة بالحسابات تتضمّن السمة label_hints مع التصنيفات المعيّنة في مصفوفة لكل حساب:

  {
  "accounts": [{
    "id": "123",
    "given_name": "John",
    "name": "John Doe",
    "email": "[e-mail]",
    "picture": "https://idp.example/profile/123",
    "label_hints": ["developer"]
    }], [{
    "id": "4567",
    "given_name": "Jane",
    "name": "Jane Doe",
    "email": "[e-mail]",
    "picture": "https://idp.example/profile/4567",
    "label_hints": ["hr"]
    }]
  }

عندما يريد موفّر خدمة السماح لمستخدمي "hr" بتسجيل الدخول، يمكنه تحديد configURL https://idp.example/hr/fedcm.json في طلب navigator.credentials.get():

  let { token } = await navigator.credentials.get({
    identity: {
      providers: [{
        clientId: '1234',
        configURL: 'https://idp.example/hr/fedcm.json',
        params: {
            nonce: '234234'
        }
      },
    }
  });

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

اعتبارات إضافية:

• التصنيفات هي سلاسل. إذا كان الصفيف label_hints أو الحقل account_label يستخدم قيمة ليست سلسلة، يتم تجاهل القيمة.
• في حال عدم تحديد أي تصنيفات في configURL، سيتم عرض جميع الحسابات في أداة اختيار الحسابات في FedCM.
• إذا لم يتم تحديد أي تصنيفات لحساب ما، لن يظهر هذا الحساب في أداة اختيار الحساب إلا إذا لم يحدّد configURL تصنيفًا أيضًا.
• إذا لم يتطابق أي حساب مع التصنيف المطلوب في الوضع السلبي (على غرار ميزة "تلميح النطاق")، يعرض مربّع حوار FedCM طلب تسجيل دخول، ما يتيح للمستخدم تسجيل الدخول إلى حساب على موفّر الهوية. في الوضع النشط، يتم فتح نافذة مربّع حوار تسجيل الدخول مباشرةً.

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

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

الموقع	الوصف
account_hint	تلميح لحساب موفّر الهوية
client_id	معرّف العميل الخاص بطرف الاعتماد.

  POST /disconnect.example 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. تأكَّد من أنّ الطلب يتضمّن عنوان Sec-Fetch-Dest: webidentity HTTP.
3. طابِق الحقل Origin مع مصدر RP الذي تحدّده السمة client_id. رفض الطلب إذا لم تتطابق.
4. مطابقة account_hint مع أرقام تعريف الحسابات التي تم تسجيل الدخول إليها
5. افصل حساب المستخدم عن "الجهة المسؤولة".
6. الردّ على المتصفّح بمعلومات حساب المستخدم المحدَّد بتنسيق JSON

تحذير: يجب أن يكون طلب CORS معتمدًا، ما يعني أنّ عنوان الاستجابة Access-Control-Allow-Origin يجب أن يشير إلى مصدر محدّد بدلاً من حرف بدل باستخدام "*".

HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://rp.example
Access-Control-Allow-Credentials: true
  

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

  {
    "account_id": "account456"
  }

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

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

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

يرسل المتصفّح طلب GET باستخدام client_id navigator.credentials.get بدون ملفات تعريف الارتباط. إذا تم استدعاء واجهة FedCM API من مصدر على مواقع إلكترونية متعددة، يتم إرسال المَعلمة top_frame_origin أيضًا. على سبيل المثال:

  GET /client_metadata.example?client_id=1234&top_frame_origin=https%3A%2F%2Ftop-frame.example HTTP/1.1
  Host: accounts.idp.example
  Origin: https://rp.example/
  Accept: application/json
  Sec-Fetch-Dest: webidentity

عند تلقّي الطلب، على الخادم إجراء ما يلي:

1. حدِّد RP لـ client_id.
2. [اختياري] إذا تم تضمين top_frame_origin في الطلب، تحقَّق مما إذا كان RP والإطار العلوي تابعَين للجهة نفسها لتحديد ما إذا كان المتصفّح سيشير إلى نطاق iframe. على موفّري خدمات تحديد الهوية تحديد منطقهم المخصّص لتحديد ذلك.
3. الردّ باستخدام البيانات الوصفية للعميل

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

الموقع	الوصف
privacy_policy_url (اختياري)	عنوان URL لسياسة الخصوصية الخاصة بمنصة الشركاء
terms_of_service_url (اختياري)	عنوان URL لبنود خدمة "الشريك المرجعي"
icons (اختياري)	مصفوفة من الكائنات، مثل [{ "url": "https://rp.example/rp-icon.ico", "size": 40}]
client_is_third_party_to_top_frame_origin (اختياري)	قيمة منطقية تشير إلى ما إذا كان موفّر الخدمة مضمّنًا في إطار iframe تابع لجهة خارجية على موقع إلكتروني ذي مستوى أعلى. عند ضبط القيمة على "صحيح"، ستعرض واجهة مستخدم FedCM نطاق الإطار المتضمّن الذي يتم استدعاء واجهة برمجة التطبيقات منه، بالإضافة إلى نطاق الموقع الإلكتروني ذي المستوى الأعلى.

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

  {
    "privacy_policy_url": "https://rp.example/privacy_policy.html",
    "terms_of_service_url": "https://rp.example/terms_of_service.html",
    "icons": [{
          "url": "https://rp.example/rp-icon.ico",
          "size": 40
      }]
  }

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

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

تُستخدَم نقطة النهاية هذه للسماح للمستخدم بتسجيل الدخول إلى موفِّر الهوية.

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

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

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

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

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

ملاحظة: لا يمكن للموقع الإلكتروني التحكّم في حجم مربّع الحوار قبل فتحه. يتم ضبط الحجم تلقائيًا على 500 بكسل للعرض و600 بكسل للارتفاع.

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

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

ملاحظة: يمكنك الاطّلاع على إعلام المتصفّح بحالة تسجيل الدخول للمستخدم لمعرفة المزيد عن عنوان HTTP Set-Login والدالة IdentityProvider.close().

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

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

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

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

• logged-in
• logged-out
• unknown (تلقائي)

حالة تسجيل الدخول	الوصف
logged-in	عندما يتم ضبط حالة تسجيل دخول المستخدم على logged-in، يرسل الطرف الاعتمادي الذي يستدعي FedCM طلبات إلى نقطة نهاية الحسابات في موفّر الهوية ويعرض الحسابات المتاحة للمستخدم في مربّع حوار FedCM.
logged-out	عندما تكون حالة تسجيل الدخول للمستخدم هي logged-out، يتعذّر تنفيذ FedCM بدون إرسال طلب إلى نقطة نهاية الحسابات في موفّر الهوية.
unknown (تلقائي)	يتم ضبط الحالة unknown قبل أن يرسل موفّر الهوية إشارة باستخدام Login Status API. عندما تكون الحالة unknown، يرسل المتصفّح طلبًا إلى نقطة نهاية الحسابات في موفّر خدمة تحديد الهوية ويعدّل الحالة استنادًا إلى الردّ الوارد من نقطة نهاية الحسابات.

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

  Set-Login: logged-in

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

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

سيتم ضبط حالة تسجيل الدخول للمستخدم على logged-in.

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

  Set-Login: logged-out

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

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

سيتم ضبط حالة تسجيل الدخول للمستخدم على logged-out.

يتم ضبط الحالة unknown قبل أن يرسل موفّر الهوية إشارة باستخدام واجهة برمجة التطبيقات Login Status. يرسل المتصفّح طلبًا إلى نقطة نهاية الحسابات الخاصة بموفّر خدمة تحديد الهوية ويعدّل الحالة استنادًا إلى الردّ الوارد من نقطة نهاية الحسابات:

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

ملاحظة: يمكن إرسال عنوان حالة تسجيل الدخول من الموارد الفرعية same-site أيضًا، بدءًا من الإصدار 122 من Chrome. ويكون ذلك مفيدًا، مثلاً، عندما يتيح موقع إلكتروني للمستخدمين إدخال اسم المستخدم وكلمة المرور على idp.example، ولكن يتم نشر بيانات الاعتماد على login.idp.example باستخدام fetch(). لا يزال بإمكان استجابة الجلب من login.idp.example ضبط حالة تسجيل الدخول في idp.example من خلال إرسال عنوان HTTP Set-Login: logged-in.

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

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

تم تصميم تجربة تسجيل الدخول الديناميكية هذه للحالات التي تنتهي فيها صلاحية جلسة موفّر الهوية بدون تسجيل خروج صريح، ما يؤدي إلى تعارض حالة تسجيل الدخول في المتصفّح مع حالة المستخدم الفعلية. لا يتم تشغيل هذا الإجراء للمستخدمين الذين لم يسجّلوا الدخول إلى موفِّر الهوية بعد. تم تصميم هذا المسار لتغطية الحالات التي تكون فيها حالة تسجيل الدخول إلى موفِّر الهوية للمستخدم على المتصفح هي logged-in ولكن نقطة نهاية الحسابات الخاصة بموفِّر الهوية لا تعرض أي حسابات. بافتراض أنّه يتم استدعاء Login Status API على الفور، عند استدعاء FedCM، يمكن أن يحدث أي من السيناريوهات التالية:

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

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