تنفيذ ميزة "استعادة بيانات الاعتماد" باستخدام "مدير بيانات الاعتماد"

توضّح هذه الصفحة كيفية إنشاء مفتاح استعادة وتسجيل الدخول باستخدامه وحذفه.

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

تعمل ميزة "استعادة بيانات الاعتماد" في "مدير بيانات الاعتماد" على الأجهزة التي تعمل بالإصدار 9 من نظام التشغيل Android والإصدارات الأحدث، والإصدار الأساسي 24220000 أو الإصدارات الأحدث من "خدمات Google Play" (GMS)، والإصدار 1.5.0 أو الإصدارات الأحدث من مكتبة androidx.credentials.

المتطلّبات الأساسية

إعداد خادم معتمِد مشابه للخادم المستخدَم في مفاتيح المرور إذا كان لديك خادم تم إعداده للتعامل مع المصادقة باستخدام مفاتيح المرور، استخدِم عملية التنفيذ نفسها من جهة الخادم لاستعادة المفاتيح.

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

الاعتمادية

أضِف الاعتماديات التالية إلى ملف build.gradle الخاص بوحدة تطبيقك:

Kotlin

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

Groovy

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

تتوفّر ميزة "استعادة بيانات الاعتماد" في الإصدار 1.5.0 والإصدارات الأحدث من مكتبة androidx.credentials. ومع ذلك، يُنصح باستخدام أحدث الإصدارات الثابتة من التبعيات حيثما أمكن ذلك.

ملاحظة: تعمل ميزة "استعادة بيانات الاعتماد" بغض النظر عمّا إذا كان allowBackup مضبوطًا في manifest.

نظرة عامة

1. إنشاء مفتاح استعادة: لإنشاء مفتاح استعادة، أكمِل الخطوات التالية:
   1. إنشاء مثيل لـ Credential Manager: أنشئ عنصر CredentialManager
   2. الحصول على خيارات إنشاء بيانات الاعتماد من خادم التطبيق: أرسِل إلى تطبيق العميل التفاصيل المطلوبة لإنشاء مفتاح الاستعادة من خادم تطبيقك.
   3. إنشاء مفتاح استرداد: أنشئ مفتاح استرداد لحساب المستخدم إذا كان المستخدم مسجّلاً الدخول إلى تطبيقك.
   4. التعامل مع ردّ إنشاء بيانات الاعتماد: أرسِل بيانات الاعتماد من تطبيق العميل إلى خادم تطبيقك لمعالجتها، وتعامل مع أي استثناءات.
2. تسجيل الدخول باستخدام مفتاح استعادة: لتسجيل الدخول باستخدام مفتاح استعادة، أكمِل الخطوات التالية:
   1. الحصول على خيارات استرداد بيانات الاعتماد من خادم التطبيق: أرسِل إلى تطبيق العميل التفاصيل المطلوبة لاسترداد مفتاح الاستعادة من خادم تطبيقك.
   2. الحصول على مفتاح الاستعادة: اطلب مفتاح الاستعادة من "مدير الاعتماد" عندما يضبط المستخدم جهازًا جديدًا. ويتيح ذلك للمستخدم تسجيل الدخول بدون الحاجة إلى إدخال أي معلومات إضافية.
   3. التعامل مع استجابة استرداد بيانات الاعتماد: أرسِل مفتاح الاستعادة من تطبيق العميل إلى خادم التطبيق لتسجيل دخول المستخدم.
3. حذف مفتاح استعادة

إنشاء مفتاح استعادة

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

ملاحظة: يرتبط مفتاح الاستعادة باسم حزمة فريد للتطبيق. إذا كان للتطبيق الرئيسي والتطبيقات الفرعية لمؤسستك أسماء حِزم مختلفة، أنشِئ مفتاح استعادة منفصلاً لكل تطبيق.

إنشاء مثيل لـ Credential Manager

استخدِم سياق نشاط تطبيقك لإنشاء عنصر CredentialManager.

// Use your app or activity context to instantiate a client instance of
// CredentialManager.
private val credentialManager = CredentialManager.create(context)

الحصول على خيارات إنشاء بيانات الاعتماد من خادم تطبيقك

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

إنشاء مفتاح الاستعادة

بعد تحليل خيارات إنشاء المفتاح العام التي أرسلها الخادم، أنشئ مفتاح استعادة من خلال تضمين هذه الخيارات في عنصر CreateRestoreCredentialRequest واستدعاء الطريقة createCredential() باستخدام العنصر CredentialManager.

val credentialManager = CredentialManager.create(context)

// On a successful authentication create a Restore Key
// Pass in the context and CreateRestoreCredentialRequest object
val response = credentialManager.createCredential(context, createRestoreRequest)

النقاط الرئيسية حول الرمز

• يحتوي عنصر CreateRestoreCredentialRequest على الحقول التالية:

  • requestJson: خيارات إنشاء بيانات الاعتماد التي يرسلها خادم التطبيق بتنسيق Web Authentication API من أجل PublicKeyCredentialCreationOptionsJSON.

  • ‫isCloudBackupEnabled: حقل Boolean لتحديد ما إذا كان سيتم الاحتفاظ بنسخة احتياطية من مفتاح الاستعادة على السحابة الإلكترونية. تكون قيمة هذا الخيار تلقائيًا true. يتضمّن هذا الحقل القيم التالية:

    • true: (يُنصح به) تتيح هذه القيمة الاحتفاظ بنسخة احتياطية من مفاتيح الاستعادة على السحابة الإلكترونية إذا كان المستخدم قد فعّل خدمة "الاحتفاظ بنسخة احتياطية" من Google و"التشفير التام بين الأطراف"، مثل قفل الشاشة.
    • ‫false: تحفظ هذه القيمة المفتاح محليًا وليس على السحابة الإلكترونية. لن يتوفّر المفتاح على الجهاز الجديد إذا اختار المستخدم استعادة البيانات من السحابة الإلكترونية.
  تنبيه: ننصحك بضبط isCloudBackupEnabled على true. إذا كانت ميزة النسخ الاحتياطي على السحابة الإلكترونية غير مفعّلة واستعاد المستخدم البيانات من نسخة احتياطية على السحابة الإلكترونية، ستتعذّر عملية استرداد مفتاح الاستعادة. لا يتلقّى المستخدمون الذين يستعيدون تطبيقك من خلال نسخة احتياطية على السحابة الإلكترونية مفتاح الاستعادة، ولا يتم تسجيل دخولهم تلقائيًا.

التعامل مع استجابة إنشاء بيانات الاعتماد

تعرض واجهة برمجة التطبيقات Credential Manager API ردًا من النوع CreateRestoreCredentialResponse. تحتوي هذه الاستجابة على استجابة تسجيل بيانات الاعتماد الخاصة بالمفتاح العام بتنسيق JSON.

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

أثناء عملية إنشاء مفتاح الاستعادة، تعامَل مع الاستثناءات التالية:

• ‫CreateRestoreCredentialDomException: يحدث هذا الاستثناء إذا كانت قيمة requestJson غير صالحة ولا تتّبع تنسيق WebAuthn الخاص PublicKeyCredentialCreationOptionsJSON.
• E2eeUnavailableException: يحدث هذا الاستثناء إذا كانت قيمة isCloudBackupEnabled هي true، ولكن جهاز المستخدم لا يتضمّن ميزة الاحتفاظ بنسخة احتياطية من البيانات أو التشفير التام بين الأطراف، مثل قفل الشاشة.
• IllegalArgumentException: يحدث هذا الاستثناء إذا كان createRestoreRequest فارغًا أو بتنسيق JSON غير صالح، أو إذا لم يكن يتضمّن user.id صالحًا يتوافق مع مواصفات WebAuthn.

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

استخدِم ميزة "استعادة بيانات الاعتماد" لتسجيل دخول المستخدم بدون أي إجراء من جانبه أثناء عملية إعداد الجهاز.

الحصول على خيارات استرداد بيانات الاعتماد من خادم التطبيق

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

الحصول على مفتاح الاستعادة

للحصول على مفتاح الاستعادة على الجهاز الجديد، استدعِ طريقة getCredential() في عنصر CredentialManager.

يمكنك الحصول على مفتاح الاستعادة في الحالات التالية:

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

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

// Fetch the Authentication JSON from server
val authenticationJson = fetchAuthenticationJson()

// Create the GetRestoreCredentialRequest object
val options = GetRestoreCredentialOption(authenticationJson)
val getRequest = GetCredentialRequest(listOf(options))

// The restore key can be fetched in two scenarios to
// 1. On the first launch of app on the device, fetch the Restore Key
// 2. In the onRestore callback (if the app implements the Backup Agent)
val response = credentialManager.getCredential(context, getRequest)

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

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

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

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

حذف مفتاح الاستعادة

لا يحتفظ "مدير بيانات الاعتماد" بأي حالة ولا يدرك نشاط المستخدم، لذا لا يحذف مفاتيح الاستعادة تلقائيًا بعد استخدامها. لحذف مفتاح استعادة، استدعِ طريقة clearCredentialState(). لأسباب تتعلّق بالأمان، احذف المفتاح كلما سجّل المستخدم الخروج. يضمن ذلك أنّه في المرة التالية التي يفتح فيها المستخدم التطبيق على الجهاز نفسه، سيتم تسجيل خروجه وسيُطلب منه تسجيل الدخول مرة أخرى.

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

تتم إزالة مفاتيح الاستعادة في الحالات التالية فقط:

• الإجراءات على مستوى النظام: إلغاء المستخدمين تثبيت التطبيق أو محو بياناته
• عمليات استدعاء على مستوى التطبيق: يمكنك حذف المفتاح آليًا من خلال استدعاء clearCredentialState() عند معالجة تسجيل خروج المستخدم في رمز تطبيقك.

عندما يسجّل المستخدم خروجه من تطبيقك، استدعِ طريقة clearCredentialState() على عنصر CredentialManager.

// Create a ClearCredentialStateRequest object
val clearRequest = ClearCredentialStateRequest(TYPE_CLEAR_RESTORE_CREDENTIAL)

// On user log-out, clear the restore key
val response = credentialManager.clearCredentialState(clearRequest)