تخصيص مسار عملية تأكيد رقم الهاتف في Firebase على Android

توضّح صفحة البدء في استخدام Firebase Phone Number Verification كيفية الدمج مع Firebase PNV باستخدام طريقة getVerifiedPhoneNumber() التي تعالج عملية Firebase PNV بأكملها، بدءًا من الحصول على موافقة المستخدم إلى إجراء طلبات الشبكة اللازمة إلى الخلفية في Firebase PNV.

ننصح معظم المطوّرين باستخدام واجهة برمجة التطبيقات ذات الطريقة الواحدة (getVerifiedPhoneNumber()). ومع ذلك، إذا كنت بحاجة إلى تحكّم أكثر دقة في التفاعل مع Android Credential Manager، مثلاً لطلب بيانات اعتماد أخرى إلى جانب رقم الهاتف، يوفّر صف Firebase PNV أيضًا الطريقتَين التاليتَين، ويتعامل كل منهما مع تفاعل مختلف مع الخلفية Firebase PNV:

  • يتلقّى getDigitalCredentialPayload() طلبًا موقّعًا من الخادم ستستخدمه لاستدعاء "مدير بيانات الاعتماد".
  • يتبادل exchangeCredentialResponseForPhoneNumber() الردّ من "مدير بيانات الاعتماد" مقابل رمز مميّز موقَّع يحتوي على رقم الهاتف الذي تم التحقّق منه.

بين استدعاء كل طريقة من هذه الطرق، تكون أنت المسؤول عن التعامل مع التفاعل مع واجهات برمجة التطبيقات الخاصة بأداة Credential Manager في Android. تقدّم هذه الصفحة نظرة عامة حول كيفية تنفيذ هذا التسلسل المكوّن من ثلاثة أجزاء.

قبل البدء

أعِدّ مشروعك على Firebase واستورِد تبعيات Firebase PNV كما هو موضّح في صفحة البدء.

1. الحصول على حمولة طلب المستند الرقمي

استدعِ طريقة getDigitalCredentialPayload() لإنشاء طلب للحصول على رقم الهاتف الخاص بالجهاز. في الخطوة التالية، سيكون هذا الطلب هو حمولة البيانات الخاصة بتفاعلك مع واجهة برمجة التطبيقات Credential Manager API.

// This instance does not require an Activity context.
val fpnv = FirebasePhoneNumberVerification.getInstance()

// Your request should include a nonce, which will propagate through the flow
// and be present in the final response from FPNV. See the section "Verifying
// the Firebase PNV token" for details on generating and verifying this.
val nonce = fetchNonceFromYourServer()

fpnv.getDigitalCredentialPayload(nonce, "https://example.com/privacy-policy")
  .addOnSuccessListener { fpnvDigitalCredentialPayload ->
    // Use the payload in the next step.
    // ...
  }
  .addOnFailureListener { e -> /* Handle payload fetch failure */ }

2. تقديم طلب للحصول على بيانات اعتماد رقمية باستخدام "إدارة بيانات الاعتماد"

بعد ذلك، مرِّر الطلب إلى "مدير بيانات الاعتماد".

لإجراء ذلك، عليك تضمين حمولة الطلب في طلب DigitalCredential API. يجب أن يتضمّن هذا الطلب قيمة nonce نفسها التي مرّرتها إلى getDigitalCredentialPayload().

// This example uses string interpolation for clarity, but you should use some kind of type-safe
// serialization method.
fun buildDigitalCredentialRequestJson(nonce: String, fpnvDigitalCredentialPayload: String) = """
    {
      "requests": [
        {
          "protocol": "openid4vp-v1-unsigned",
          "data": {
            "response_type": "vp_token",
            "response_mode": "dc_api",
            "nonce": "$nonce",
            "dcql_query": { "credentials": [$fpnvDigitalCredentialPayload] }
          }
        }
      ]
    }
""".trimIndent()

بعد ذلك، يمكنك تقديم الطلب باستخدام واجهة Credential Manager API:

suspend fun makeFpnvRequest(
  context: Activity, nonce: String, fpnvDigitalCredentialPayload: String): GetCredentialResponse {
  // Helper function to build the digital credential request (defined above).
  // Pass the same nonce you passed to getDigitalCredentialPayload().
  val digitalCredentialRequestJson =
    buildDigitalCredentialRequestJson(nonce, fpnvDigitalCredentialPayload)

  // CredentialManager requires an Activity context.
  val credentialManager = CredentialManager.create(context)

  // Build a Credential Manager request that includes the Firebase PNV option. Note that
  // you can't combine the digital credential option with other options.
  val request = GetCredentialRequest.Builder()
    .addCredentialOption(GetDigitalCredentialOption(digitalCredentialRequestJson))
    .build()

  // getCredential is a suspend function, so it must run in a coroutine scope,
  val cmResponse: GetCredentialResponse = try {
    credentialManager.getCredential(context, request)
  } catch (e: GetCredentialException) {
    // If the user cancels the operation, the feature isn't available, or the
    // SIM doesn't support the feature, a GetCredentialCancellationException
    // will be returned. Otherwise, a GetCredentialUnsupportedException will
    // be returned with details in the exception message.
    throw e
  }
  return cmResponse
}

في حال نجاح طلب Credential Manager، ستحتوي الاستجابة على مستند تعريف رقمي يمكنك استخراجه باستخدام رمز برمجي مثل المثال التالي:

val dcApiResponse = extractApiResponse(cmResponse)
fun extractApiResponse(response: GetCredentialResponse): String {
  val credential = response.credential
  when (credential) {
    is DigitalCredential -> {
      val json = JSONObject(credential.credentialJson)
      val firebaseJwtArray =
          json.getJSONObject("data").getJSONObject("vp_token").getJSONArray("firebase")
      return firebaseJwtArray.getString(0)

    }
    else -> {
      // Handle any unrecognized credential type here.
      Log.e(TAG, "Unexpected type of credential ${credential.type}")
    }
  }
}

3- استبدال ردّ بيانات الاعتماد الرقمية برمز مميّز Firebase PNV

أخيرًا، استدعِ طريقة exchangeCredentialResponseForPhoneNumber() لتبادل الردّ على بيانات الاعتماد الرقمية مقابل رقم الهاتف الذي تم تأكيده ورمز مميّز Firebase PNV:

fpnv.exchangeCredentialResponseForPhoneNumber(dcApiResponse)
  .addOnSuccessListener { result ->
    val phoneNumber = result.getPhoneNumber()
    // Verification successful
  }
  .addOnFailureListener { e -> /* Handle exchange failure */ }

4. جارٍ التحقّق من الرمز المميّز Firebase PNV

في حال نجاح عملية التحقّق، ستعرض الطريقة getVerifiedPhoneNumber() رقم الهاتف الذي تم التحقّق منه ورمزًا مميزًا موقّعًا يتضمّن رقم الهاتف. يمكنك استخدام هذه البيانات في تطبيقك على النحو الموضّح في سياسة الخصوصية.

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

  • نقطة نهاية لإنشاء أرقام عشوائية غير متكررة
  • نقطة نهاية للتحقّق من الرمز المميّز

يعود إليك أمر تنفيذ نقاط النهاية هذه، وتوضّح الأمثلة التالية كيفية تنفيذها باستخدام Node.js وExpress.

إنشاء أرقام عشوائية

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

app.get('/fpnvNonce', async (req, res) => {
    const nonce = crypto.randomUUID();

    // TODO: Save the nonce to a database, key store, etc.
    // You should also assign the nonce an expiration time and periodically
    // clear expired nonces from your database.
    await persistNonce({
        nonce,
        expiresAt: Date.now() + 180000, // Give it a short duration.
    });

    // Return the nonce to the caller.
    res.send({ nonce });
});

هذه هي نقطة النهاية التي ستستدعيها الدالة النائبة fetchNonceFromYourServer() في الخطوة 1. سيتم نشر الرقم العشوائي من خلال مختلف طلبات الشبكة التي ينفّذها العميل، وسيتم في النهاية إرساله مرة أخرى إلى الخادم في الرمز المميز Firebase PNV. في الخطوة التالية، عليك التأكّد من أنّ الرمز المميز يتضمّن رقمًا عشوائيًا لمرة واحدة أنشأته.

التحقّق من الرموز المميّزة

يتلقّى نقطة النهاية هذه رموزًا مميّزة من النوع Firebase PNV من تطبيق العميل ويتحقّق من صحتها. لإثبات صحة الرمز المميّز، عليك التحقّق مما يلي:

  • يتم توقيع الرمز المميّز باستخدام أحد المفاتيح المنشورة في نقطة النهاية Firebase PNV JWKS:

    https://fpnv.googleapis.com/v1beta/jwks
    
  • تحتوي مطالبات الجمهور والجهة المصدرة على رقم مشروعك على Firebase، وتكون بالتنسيق التالي:

    https://fpnv.googleapis.com/projects/FIREBASE_PROJECT_NUMBER
    

    يمكنك العثور على رقم مشروعك على Firebase في صفحة إعدادات المشروع في "وحدة تحكّم Firebase".

  • لم تنتهِ صلاحية الرمز المميز.

  • يحتوي الرمز المميّز على قيمة عشوائية صالحة. يكون الرقم العشوائي صالحًا في الحالات التالية:

    • أنّك أنشأته (أي يمكن العثور عليه في أي آلية ثبات تستخدمها)
    • لم يتم استخدامه من قبل
    • لم تنتهِ صلاحيتها

على سبيل المثال، قد يبدو تنفيذ Express على النحو التالي:

import { JwtVerifier } from "aws-jwt-verify";

// Find your Firebase project number in the Firebase console.
const FIREBASE_PROJECT_NUMBER = "123456789";

// The issuer and audience claims of the FPNV token are specific to your
// project.
const issuer = `https://fpnv.googleapis.com/projects/${FIREBASE_PROJECT_NUMBER}`;
const audience = `https://fpnv.googleapis.com/projects/${FIREBASE_PROJECT_NUMBER}`;

// The JWKS URL contains the current public signing keys for FPNV tokens.
const jwksUri = "https://fpnv.googleapis.com/v1beta/jwks";

// Configure a JWT verifier to check the following:
// - The token is signed by Google
// - The issuer and audience claims match your project
// - The token has not yet expired (default begavior)
const fpnvVerifier = JwtVerifier.create({ issuer, audience, jwksUri });

app.post('/verifiedPhoneNumber', async (req, res) => {
    if (!req.body) return res.sendStatus(400);
    // Get the token from the body of the request.
    const fpnvToken = req.body;
    try {
        // Attempt to verify the token using the verifier configured above.
        const verifiedPayload = await fpnvVerifier.verify(fpnvToken);

        // Now that you've verified the signature and claims, verify the nonce.
        // TODO: Try to look up the nonce in your database and remove it if it's
        // found; if it's not found or it's expired, throw an error.
        await testAndRemoveNonce(verifiedPayload.nonce);

        // Only after verifying the JWT signature, claims, and nonce, get the
        // verified phone number from the subject claim.
        // You can use this value however it's needed by your app.
        const verifiedPhoneNumber = verifiedPayload.sub;
        // (Do something with it...)

        return res.sendStatus(200);
    } catch {
        // If verification fails, reject the token.
        return res.sendStatus(400);
    }
});