يتم قبول مستندات التعريف من "محفظة Google"

على الإنترنت

يمكن قبول بطاقات التعريف الرقمية في كلّ من عمليات التسجيل داخل التطبيق والويب. لقبول بيانات الاعتماد من "محفظة Google"، عليك إجراء ما يلي:

  1. الدمج باستخدام التطبيق أو الويب باتّباع التعليمات المقدَّمة
  2. يُرجى ملء هذا النموذج لطلب قبول بيانات الاعتماد من "محفظة Google" والموافقة على بنود الخدمة.

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

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

  • رابط بنود الخدمة
  • Logo
  • الموقع الإلكتروني
  • رقم تعريف حزمة "متجر Play" (لعمليات دمج تطبيقات Android)
  • رقم تعريف Gmail الذي تم استخدامه للانضمام إلى الإصدار التجريبي العلني

تنسيقات بيانات الاعتماد المتوافقة

هناك العديد من المعايير المقترَحة التي تحدّد تنسيق البيانات في مستندات هوية الرقمية، وقد اكتسب معياران منها رواجًا كبيرًا في المجال:

  1. مستندات mdocs: تحدّدها المنظمة الدولية للمواصفات (ISO).
  2. بيانات الاعتماد القابلة للتحقّق من W3C: هي بيانات تحدّدها W3C.

على الرغم من أنّ "مدير بيانات الاعتماد" في Android يتوافق مع التنسيقَين، لا تتيح "محفظة Google" حاليًا سوى استخدام بطاقات التعريف الرقمية المستندة إلى mdoc.

تجربة المستخدم

عندما يطلب تطبيق سمات الهوية، تحدث العملية التالية:

  1. اكتشاف بيانات الاعتماد: يبحث التطبيق في محافظ الدفع المتاحة لتحديد بيانات الاعتماد التي يمكنها تلبية الطلب. يقدّم Android بعد ذلك أداة اختيار لواجهة مستخدِم النظام، وتعرض المعلومات التي ستتم مشاركتها. يتيح ذلك للمستخدم اتخاذ قرار مدروس بشأن بيانات الاعتماد التي سيتم استخدامها.

  2. اختيار المستخدم وتفاعل المحفظة: يختار المستخدم بيانات اعتماد، ويستدعي Android تطبيق المحفظة المناسب لإكمال المعاملة. قد يعرض تطبيق "محفظة Google" شاشة طلب الموافقة الخاصة به أو قد يطلب تأكيد البيانات باستخدام المقاييس الحيوية.

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

في التطبيق

لطلب بيانات اعتماد الهوية من تطبيقات Android، اتّبع الخطوات التالية:

تعديل التبعيات

في ملف build.gradle الخاص بمشروعك، عدِّل التبعيات ل استخدام Credential Manager (الإصدار التجريبي):

dependencies {
    implementation("androidx.credentials:credentials:1.5.0-alpha05")
    // optional - needed for credentials support from play services, for devices running Android 13 and below.
    implementation("androidx.credentials:credentials-play-services-auth:1.5.0-alpha05")
}

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

لضبط عنصر CredentialManager وإعداده، أضِف منطقًا مشابهًا لما يلي:

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

سمات هوية الطلب

// Retrieves the user's digital identites from wallet apps for your app.
val getIdentityCredentialOption = GetDigitalCredentialOption(
    requestJson = requestJson, // this is what partners needs to set, example JSON specified below
)
val result = credentialManager.getCredential(request = GetCredentialRequest(credentialOptions, ...)

يقدّم المُرسِل للطلب جميع مَعلمات IdentityRequest كسلسلة JSON. في ما يلي تمثيلها على أنّها مَعلمة requestMatcher من CredentialOption. لا يهتم "مدير بيانات الاعتماد" بمحتوى ملف json هذا. سيتم تمرير طلب json هذا مباشرةً إلى محافظ العملات الرقمية، والتي تتحمّل بعد ذلك مسؤولية تحليله وتحديد بيانات الاعتماد التي يمكنها تلبية الطلب. يمكن العثور على التنفيذ الكامل في نموذج التطبيق.

نتوقع أن تعرّف W3C طلب JSON هذا على أنّه مكوّن من web API. سيتيح هذا التوحيد للمتصفّحات نقل الطلبات إلى Android مباشرةً.

لإعطائك فكرة عن الشكل الذي قد يبدو عليه هذا الطلب، إليك نموذج لطلب mdoc:

{
  "selector": {
    "format": [
      "mdoc"
    ],
    "doctype": "org.iso.18013.5.1.mDL",
    "fields": [
      {
        "namespace": "org.iso.18013.5.1",
        "name": "family_name",
        "intentToRetain": false
      },
      {
        "namespace": "org.iso.18013.5.1",
        "name": "given_name",
        "intentToRetain": false
      },
      {
        "namespace": "org.iso.18013.5.1",
        "name": "age_over_21",
        "intentToRetain": false
      }
    ]
  },
  "nonce": "3cydsUF9xNFyBDAAWOct09hEeSqrFX2WB2r0G6f8Ol0=",
  "readerPublicKey": "BApmGdElal2-1dtafsdHVRa1EpAWZfhlQj_iof2I8L3V8_dCK1gVR0_12E4ZSQ2LcqXRd4zxVeKEqU1wUSgGWUU="
}

تعرض الاستجابة identityToken (سلسلة JSON) التي يحدّدها W3C. تطبيق "محفظة Google" مسؤول عن صياغة هذا الرد.

مثال:

{
    "token": "<base64 encoded response>"
}

إرسال الرمز المميّز ومعالجته على الخادم

عند تلقّي identityToken، من المفترض أن يرسل تطبيقك هذا الرمز إلى خادم التطبيق للتحقّق منه. تتضمن الخطوة الأولى فك ترميز الرمز المميّز من تنسيق base64. تمثّل صفيف البايت الناتج بيانات CBOR ، والتي تلتزم بـ CDDL التالي.

CredentialDocument = {
  "version": tstr,       // Set to "ANDROID-HPKE-v1"
  "pkEm": bstr,          // Public key, in uncompressed form
  "cipherText": bstr     // The encrypted data
}

تتمثل الخطوة التالية في حساب SessionTranscript من ISO/IEC 18013-5:2021 باستخدام بنية تسليم خاصة بنظام Android:

SessionTranscript = [
  null,                // DeviceEngagementBytes not available
  null,                // EReaderKeyBytes not available
  AndroidHandover      // Defined below
]

AndroidHandover = [
  "AndroidHandoverv1", // Version number
  nonce,               // nonce that comes from request
  appId,               // RP package name
  pkRHash,             // The SHA256 hash of the recipient public key
]

يتم تشفير cipherText باستخدام تشفير HPKE. لفك تشفيره، استخدِم SessionTranscript كبيانات مُعتمَدة إضافية، بالإضافة إلى المفتاح الخاص لخوارزمية التشفير المتماثل (EC) الذي تم إنشاؤه سابقًا، والإعدادات التالية:

  • KEM: DHKEM(P-256, HKDF-SHA256)
  • KDF: HKDF-SHA256
  • AEAD: AES-128-GCM

النص الواضح الناتج هو وحدات بيانات CBOR لرسالة DeviceResponse كما هو محدّد في ISO/IEC 18013-5:2021. يجب التحقّق من صحة DeviceResponse وفقًا للمادة 9 من ‎ ISO/IEC 18013-5:2021. ويشمل ذلك عدة خطوات، مثل التحقّق من أنّ ملف mdoc مصدره جهة إصدار موثوق بها وأنّ الجهاز المقصود هو الذي وقّع على الاستجابة. يمكن استخدام فئة DeviceResponseParser من مشروع OpenWallet Foundation Identity Credential كجزء من عملية التحقّق هذه.

الويب

لطلب بيانات اعتماد الهوية باستخدام Digital Credentials API على Chrome، عليك الاشتراك في مرحلة التجربة والتقييم لواجهة برمجة التطبيقات Digital Credentials API.

عرض شخصي

يتطلب قبول مستندات التعريف من "محفظة Google" اتّباع الخطوات التالية:

  • إنشاء قارئ أو الحصول عليه لقبول مستندات التعريف كما هو محدّد في معيار ISO 18013-5
  • تحميل شهادات IACA في قارئ البطاقات لضمان أنّ مستندات التعريف المقبولة أصلية
  • اختبار الحلّ
  • تسجيل تطبيقك في "محفظة Google"

إنشاء قارئ أو الحصول عليه لقبول مستندات التعريف كما هو محدّد في معيار ISO 18013-5

يتم تنفيذ مستندات التعريف في "محفظة Google" وفقًا لمعيار ISO 18013-5 لرخص القيادة على الأجهزة الجوّالة. وتستخدم هذه الأجهزة تفاعلاً مستندًا إلى NFC أو رمز الاستجابة السريعة مع تقنية BLE كآلية لنقل البيانات، وبالتالي يمكن لأي جهاز يمكنه تنفيذ هذه الجوانب من المعيار أن يعمل كقارئ، حتى لو كان تطبيقًا جوّالاً. وبما أنّ المعيار مفتوح، تتوفّر في السوق عدة عمليات تنفيذ تابعة لجهات خارجية. بالإضافة إلى ذلك، يمكنك تنفيذ الوظيفة مباشرةً إذا لزم الأمر.

للحصول على إرشادات حول كيفية تنفيذ الوظيفة بنفسك، يمكنك مراجعة تطبيق Android المرجعي المفتوح المصدر الذي يستخدم معيار ISO ويمكنه قبول تراخيص mDL من "محفظة Google".

يمكنك البدء بإنشاء تطبيق قارئ المراجع وتشغيله عبر اتّباع الخطوات التالية:

  • استنساخ مستودع التطبيقات المرجعية
  • افتح المشروع في استوديو Android.
  • أنشئ هدف appverifier وشغِّله على جهاز Android أو المحاكي.

تحميل شهادات IACA في قارئ البطاقات لضمان أنّ مستندات التعريف المقبولة أصلية

يتطلب التحقّق من بيانات اعتماد حقيقية امتلاك مستند تعريف في المحفظة صادر عن جهة إصدار معتمَدة. إليك قائمة بجهات الإصدار المتوافقة مع "محفظة Google" أدناه مع روابط تؤدي إلى شهاداتهم لإجراء عملية التحقّق.

اختبار الحلّ

لاختبار الحل الذي تقدّمه، أنشئ تطبيق Android لحامل المراجع المفتوحة المصدر وشغِّله. في ما يلي خطوات إنشاء تطبيق حامل المرجع وتشغيله:

  • استنساخ مستودع التطبيقات المرجعية
  • افتح المشروع في استوديو Android.
  • أنشئ هدف appholder وشغِّله على جهاز Android أو المحاكي.

(اختياري) تسجيل تطبيقك في محفظة Google

يمكنك تسجيل طلبك في "محفظة Google" من خلال ملء هذا النموذج.