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

على الإنترنت

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

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

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

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

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

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

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

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

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

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

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

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

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

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

في التطبيق

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

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

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

dependencies {
    implementation("androidx.credentials:credentials:1.5.0-beta01")
    // 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-beta01")
}

ضبط "مدير بيانات الاعتماد"

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

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

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

بدلاً من تحديد مَعلمات فردية لطلبات الهوية، يقدّم التطبيق هذه المَعلمات معًا كسلسلة JSON ضمن CredentialOption. يُرسِل "مدير بيانات الاعتماد" سلسلة JSON هذه إلى المَحافظ الرقمية المتاحة بدون فحص محتواها. بعد ذلك، تكون كل محفظة مسؤولة عن ما يلي: - تحليل سلسلة JSON لفهم طلب تحديد الهوية - تحديد بيانات الاعتماد المخزّنة التي تستوفي الطلب، إن وجدت

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

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

في ما يلي نموذج لملف mdoc requestJson لبروتوكول المعاينة:

{
  identity: {
    providers: [{
      holder: {
        selector: {
          format: ['mdoc'],
          type: 'org.iso.18013.5.1.mDL',
          fields: [
            'org.iso.18013.5.1.family_name',
            'org.iso.18013.5.1.portrait',
          ]
        },
        params: {
          nonce: '1234',
          readerPublicKey: '<public_key>',
          extraParamAsNeededByWallets: true,
        },
      },
    }]
  }
}

// The request in the JSON format to conform with
// the JSON-ified Digital Credentials API request definition.
val requestJson = generateRequestFromServer()
val digitalCredentialOption =
    GetDigitalCredentialOption(requestJson = requestJson)

// Use the option from the previous step to build the `GetCredentialRequest`.
val getCredRequest = GetCredentialRequest(
    listOf(digitalCredentialOption)
)

coroutineScope.launch {
    try {
        val result = credentialManager.getCredential(
            context = activityContext,
            request = getCredRequest
        )
        verifyResult(result)
    } catch (e : GetCredentialException) {
        handleFailure(e)
    }
}

// Handle the successfully returned credential.
fun verifyResult(result: GetCredentialResponse) {
    val credential = result.credential
    when (credential) {
        is DigitalCredential -> {
            val responseJson = credential.credentialJson
            validateResponseOnServer(responseJson)
        }
        else -> {
            // Catch any unrecognized credential type here.
            Log.e(TAG, "Unexpected type of credential ${credential.type}")
        }
    }
}

// Handle failure.
fun handleFailure(e: GetCredentialException) {
  when (e) {
        is GetCredentialCancellationException -> {
            // The user intentionally canceled the operation and chose not
            // to share the credential.
        }
        is GetCredentialInterruptedException -> {
            // Retry-able error. Consider retrying the call.
        }
        is NoCredentialException -> {
            // No credential was available.
        }
        is CreateCredentialUnknownException -> {
            // An unknown, usually unexpected, error has occurred. Check the
            // message error for any additional debugging information.
        }
        is CreateCredentialCustomException -> {
            // You have encountered a custom error thrown by the wallet.
            // If you made the API call with a request object that's a
            // subclass of CreateCustomCredentialRequest using a 3rd-party SDK,
            // then you should check for any custom exception type constants
            // within that SDK to match with e.type. Otherwise, drop or log the
            // exception.
        }
        else -> Log.w(TAG, "Unexpected exception type ${e::class.java}")
    }
}

تعرض الاستجابة 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)
  • دالة إنشاء المفاتيح: 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 ويمكنه قبول رخص القيادة الرقمية من "محفظة Google".

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

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

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

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

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

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

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

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