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

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

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

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

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

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

الطلبات التابعة

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

Kotlin

dependencies {
    implementation("androidx.credentials:credentials:1.7.0-alpha01")
    implementation("androidx.credentials:credentials-play-services-auth:1.7.0-alpha01")
}

Groovy

dependencies {
    implementation "androidx.credentials:credentials:1.7.0-alpha01"
    implementation "androidx.credentials:credentials-play-services-auth:1.7.0-alpha01"
}

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

نظرة عامة

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

// createRestoreRequest contains the details sent by the server 
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 options required to get the restore key
val authenticationJson = fetchAuthenticationJson()

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

val response = credentialManager.getCredential(context, getRequest)

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

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

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

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

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

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

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

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

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

// When the user logs out, delete the restore key
val response = credentialManager.clearCredentialState(clearRequest)