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

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

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

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

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

قبل البدء

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

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

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

Kotlin

// 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. يجب أن يتضمّن هذا الطلب رقمًا عشوائيًا مطابقًا للرقم الذي مرّرته إلى getDigitalCredentialPayload().

Kotlin

// 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()

بعد إجراء ذلك، يمكنك تقديم الطلب باستخدام واجهة برمجة التطبيقات الخاصة بـ "مدير بيانات الاعتماد":

Kotlin

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
}

إذا نجح استدعاء "مدير بيانات الاعتماد"، سيحتوي الردّ على بيانات اعتماد رقمية يمكنك استخراجها باستخدام رمز مثل المثال التالي:

Kotlin

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

Kotlin

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

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

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

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

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

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

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

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

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

Node.js

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 من عميلك وتتحقّق من صحتها. للتحقّق من رمز مميّز، عليك التأكّد مما يلي:

  • تم ضبط عنوان typ على JWT.

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

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

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

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

  • عنصر التحقّق من المستلِم هو قائمة تحتوي على رقم مشروعك على Firebase ورقم تعريف المشروع ويكون بالتنسيق التالي:

    [
      https://fpnv.googleapis.com/projects/FIREBASE_PROJECT_NUMBER,
      https://fpnv.googleapis.com/projects/FIREBASE_PROJECT_ID,
    ]
    
  • لم تنتهِ صلاحية الرمز المميّز.

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

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

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

Node.js

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);
    }
});