Credential Manager - Holder API

تتيح واجهة برمجة التطبيقات Credential Manager - Holder لتطبيقات Android إدارة بيانات الاعتماد الرقمية وتقديمها إلى جهات التحقّق.

البدء

لاستخدام واجهة برمجة التطبيقات Credential Manager - Holder API، أضِف التبعيات التالية إلى نص برمجة الإصدار الخاص بوحدة تطبيقك:

// In your app module's build.gradle:
dependencies {
    implementation(libs.androidx.registry.provider)
    implementation(libs.androidx.registry.provider.play.services)
}

// In libs.versions.toml:
registryDigitalCredentials = "1.0.0-alpha01"

androidx-registry-provider = { module = "androidx.credentials.registry:registry-provider", version.ref = "registryDigitalCredentials" }
androidx-registry-provider-play-services = { module = "androidx.credentials.registry:registry-provider-play-services", version.ref = "registryDigitalCredentials" }

تسجيل بيانات الاعتماد باستخدام Credential Manager

يجب أن تسجّل المحفظة بيانات وصفية لبيانات الاعتماد حتى يتمكّن "مدير بيانات الاعتماد" من فلترتها وعرضها في أداة اختيار بيانات الاعتماد عند تلقّي طلب.

الشكل 1. واجهة مستخدم بيانات الاعتماد الرقمية

واجهة مستخدم أداة اختيار Credential Manager

يتم تمرير تنسيق هذه البيانات الوصفية إلى RegisterCredentialsRequest. أنشئ [RegistryManager][1] وسجِّل بيانات الاعتماد:

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

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

اختياري: إنشاء أداة مطابقة

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

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

التعامل مع بيانات اعتماد محدّدة

بعد ذلك، يجب أن يتعامل التطبيق مع الحالات التي يختار فيها المستخدم مستند تعريف. يمكنك تحديد نشاط يستمع إلى فلتر الأهداف androidx.credentials.registry.provider.action.GET_CREDENTIAL. يوضّح نموذج المحفظة هذا الإجراء.

سيتضمّن Intent الذي يبدأ النشاط طلب Verifier ومصدر الاتصال، ويمكن استخراجهما باستخدام الدالة PendingIntentHandler.retrieveProviderGetCredentialRequest. تعرض واجهة برمجة التطبيقات ProviderGetCredentialRequest يتضمّن جميع المعلومات المرتبطة بطلب أداة التحقّق المحدّدة. هناك ثلاثة مكوّنات رئيسية:

• التطبيق الذي قدّم الطلب. يمكنك استردادها من خلال getCallingAppInfo.
• بيانات الاعتماد المحدّدة يمكنك الحصول على معلومات حول المرشّح الذي اختاره المستخدم من خلال طريقة الإضافة selectedEntryId، وسيتطابق ذلك مع معرّف بيانات الاعتماد الذي سجّلته.
• أي طلبات محدّدة قدّمها المدقّق يمكنك الحصول على هذا المعرّف من خلال الطريقة getCredentialOptions. في هذه الحالة، من المفترض أن تجد GetDigitalCredentialOption في هذه القائمة، يتضمّن طلب "بيانات الاعتماد الرقمية".

في معظم الحالات، سيقدّم المدقّق طلب عرض بيانات اعتماد رقمية، ويمكنك معالجة هذا الطلب باستخدام نموذج الرمز التالي:

request.credentialOptions.forEach { option ->
    if (option is GetDigitalCredentialOption) {
        Log.i(TAG, "Got DC request: ${option.requestJson}")
        processRequest(option.requestJson)
    }
}

يمكنك الاطّلاع على مثال على ذلك في محفظتنا النموذجية.

عرض واجهة مستخدم المحفظة

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

إرجاع ردّ بيانات الاعتماد

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

PendingIntentHandler.setGetCredentialResponse(
    resultData,
    GetCredentialResponse(DigitalCredential(response.responseJson))
)
setResult(RESULT_OK, resultData)
finish()

في حال وجود استثناء، يمكنك إرسال استثناء بيانات الاعتماد بالطريقة نفسها:

PendingIntentHandler.setGetCredentialException(
    resultData,
    GetCredentialUnknownException() // Configure the proper exception
)
setResult(RESULT_OK, resultData)
finish()

راجِع تطبيق العيّنة للاطّلاع على مثال حول كيفية عرض ردّ بيانات الاعتماد في السياق.