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-alpha02"

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

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

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

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

يحتوي Intent الذي يبدأ النشاط على طلب أداة التحقّق ومصدر الاستدعاء، ويمكنك استخراجه باستخدام الدالة 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()

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