الحفاظ على اتساق بيانات الاعتماد مع موفّري بيانات الاعتماد

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

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

يمكن أن تؤدي حالات عدم التطابق المحتملة بين البيانات المحفوظة على خادم الجهة المعتمِدة ومقدّم بيانات الاعتماد إلى تجارب سيئة للمستخدم. قد تنشأ مشاكل في الحالات التالية:

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

تتيح Signal API في Credential Manager للجهات المعتمِدة التواصل مع مقدّمي بيانات الاعتماد لحذف بيانات الاعتماد وتعديل البيانات الوصفية للمستخدمين، مثل اسم المستخدم والاسم المعروض. هناك ثلاثة أنواع من الطلبات المتاحة لسيناريوهات مختلفة:

• SignalUnknownCredentialRequest

  • يشير إلى أنّ بيانات اعتماد معيّنة لم تعُد صالحة ويجب إخفاؤها أو إزالتها من مقدّم بيانات الاعتماد.

• SignalAllAcceptedCredentialIdsRequest

  • توفّر هذه السمة قائمة بمعرّفات بيانات الاعتماد المقبولة لموفّر بيانات الاعتماد.

• SignalCurrentUserDetailsRequest

  • تعدّل هذه الطريقة تفاصيل البيانات الوصفية للمستخدم.

التوافق مع الإصدارات

تتوفّر واجهة برمجة التطبيقات Signal API على الأجهزة التي تعمل بالإصدار 15 من نظام التشغيل Android أو الإصدارات الأحدث، وتتوفّر بدءًا من الإصدار 1.6.0-beta03 من مكتبة androidx.credentials.

التنفيذ

لاستخدام Signal API، اتّبِع الخطوات التالية:

1. أضِف تبعية Credential Manager إلى مشروعك.

   ملاحظة: تتوفّر Signal API بدءًا من الإصدار credentials 1.6.0-beta03، ولكن ننصحك باستخدام أحدث إصدار من المكتبة كلما أمكن ذلك.

   Kotlin

   dependencies {
       implementation("androidx.credentials:credentials:1.6.0-rc01")
   }

   Groovy

   dependencies {
       implementation "androidx.credentials:credentials:1.6.0-rc01"
   }

2. استدعاء Signal API

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

   • بيانات اعتماد غير معروفة (SignalUnknownCredentialRequest)

     استخدِم SignalUnknownCredentialRequest للإشارة إلى أنّ بيانات الاعتماد مرفوضة وغير معروفة. عندما يتلقّى موفّر بيانات الاعتماد هذه الإشارة، يخفي بيانات الاعتماد أو يحذفها.

     الاستخدام

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

     مَعلمات JSON المطلوبة لهذا الطلب هي rpId وcredentialId. لمزيد من المعلومات حول بنية JSON، يُرجى الاطّلاع على خيارات signalUnknownCredential.

     credentialManager.signalCredentialState(
         SignalUnknownCredentialRequest(
             requestJson = JSONObject().apply {
                 put("rpId", rpId /* [String] RP ID of the relying party */)
                 put("credentialId", credentialId /* [String] Credential ID of the credential to be hidden or deleted */)
             }.toString()
         )
     )
     

   • جميع بيانات الاعتماد المقبولة (SignalAllAcceptedCredentialIdsRequest)

     استخدِم SignalAllAcceptedCredentialIdsRequest لإشعار موفّري بيانات الاعتماد بمجموعة جميع بيانات الاعتماد المقبولة. بعد أن يتلقّى موفّر بيانات الاعتماد الإشارة، سيخفي أو يحذف أي بيانات اعتماد غير مضمّنة في هذه القائمة، أو سيزيل إخفاء أي بيانات اعتماد تم إخفاؤها سابقًا وأصبحت مضمّنة في القائمة.

     ملاحظة: عند مصادقة المستخدم، يُفضّل استخدام هذه الإشارة على SignalUnknownCredentialRequest.

     الاستخدام

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

     مَعلمات JSON المطلوبة لهذا الطلب هي rpId وuserId وallAcceptedCredentialIds. لمزيد من المعلومات حول بنية JSON، يُرجى الاطّلاع على خيارات signalAllAcceptedCredential.

     credentialManager.signalCredentialState(
         SignalAllAcceptedCredentialIdsRequest(
             requestJson = JSONObject().apply {
                 put("rpId", rpId /* [String] RP ID of the relying party */)
                 put("userId", userId /* [String] User ID of the current user */)
                 put(
                     "allAcceptedCredentialIds",
                     JSONArray(credentialIdsList /* [List<String>] List of accepted Credential IDs */)
                 )
             }.toString()
         )
     )
     

   • تفاصيل المستخدم الحالي (SignalCurrentUserDetailsRequest)

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

     الاستخدام

     استخدِم هذه الإشارة عندما يعدّل المستخدم أو الطرف المعتمِد بيانات وصفية خاصة بمفتاح المرور مرتبطة بحساب المستخدم.

     معلَمات JSON المطلوبة لهذا الطلب هي rpId وuserId وname وdisplayName. لمزيد من المعلومات حول بنية JSON، يُرجى الاطّلاع على خيارات signalCurrentUserDetails.

     credentialManager.signalCredentialState(
         SignalCurrentUserDetailsRequest(
             requestJson = JSONObject().apply {
                 put("rpId", rpId /* [String] RP ID of the relying party */)
                 put("userId", userId /* [String] User ID of the current user */)
                 put("name", name /* [String] New Name to be updated for the current user */)
                 put("displayName", displayName /* [String] New display name to be updated for the current user */)
             }.toString()
         )
     )
     

   ملاحظة: تتيح واجهة برمجة التطبيقات Credential Manager Signal API التنفيذ في الخلفية، ولكن على الجهات المعتمِدة الحدّ من عدد مرات طلب البيانات إلى 10 طلبات كحد أقصى خلال أي فترة زمنية مدتها 120 ثانية، وذلك للبقاء ضمن حدود معدّل الاستخدام المحدّدة. قد يؤدي الإفراط في إرسال الإشارات إلى تقييد الخدمة أو رفض الطلب.

اختبار عملية التنفيذ

لاختبار عملية تنفيذ Signal API، أكمِل الخطوات التالية:

1. ثبِّت نموذج مزوّد بيانات الاعتماد باسم MyVault.

   ملاحظة: تطبيق MyVault مخصّص لأغراض الاختبار فقط.

2. فعِّل MyVault كمزوّد بيانات اعتماد في الإعدادات > كلمات المرور ومفاتيح المرور والحسابات > الخدمة المفضّلة.

   

3. فعِّل جميع الإشعارات لتطبيق MyVault من خلال الإعدادات > التطبيقات > MyVault > الإشعارات.

   

4. تأكَّد من تفعيل خيار العرض على الشاشة للإشعارات في الإعدادات > التطبيقات > MyVault > الإشعارات > الفئات > قناة إشعارات Signal API.

   

5. في تطبيقك، شغِّل العمليات التي ترسل طلبات الإشارات إلى مقدّم بيانات الاعتماد. من المفترض أن تظهر لك إشعارات من MyVault على الشاشة. يؤكّد ذلك أنّ مزوّد بيانات الاعتماد تلقّى الطلبات.