Настройте процесс проверки номера телефона Firebase на Android

На странице Начало работы с Firebase Phone Number Verification подробно описано, как интегрироваться с Firebase PNV с помощью метода getVerifiedPhoneNumber() , который обрабатывает весь поток Firebase PNV — от получения согласия пользователя до выполнения необходимых сетевых вызовов к бэкэнду Firebase PNV .

API с одним методом ( getVerifiedPhoneNumber() ) рекомендуется большинству разработчиков. Однако, если вам требуется более детальный контроль над взаимодействием с Android Credential Manager, например, для запроса других учётных данных вместе с номером телефона, библиотека Firebase PNV также предоставляет следующие два метода, каждый из которых обрабатывает различные взаимодействия с бэкендом Firebase PNV :

  • getDigitalCredentialPayload() получает подписанный сервером запрос, который вы будете использовать для вызова диспетчера учетных данных.
  • exchangeCredentialResponseForPhoneNumber() обменивает ответ от Credential Manager на подписанный токен, содержащий проверенный номер телефона.

Между вызовами каждого из этих методов вы отвечаете за взаимодействие с API-интерфейсами диспетчера учётных данных Android. На этой странице представлен обзор реализации этого трёхэтапного процесса.

Прежде чем начать

Настройте свой проект Firebase и импортируйте зависимости Firebase PNV как описано на странице «Начало работы» .

1. Получите полезную нагрузку запроса цифровых учетных данных.

Вызовите метод getDigitalCredentialPayload() , чтобы сгенерировать запрос на номер телефона устройства. На следующем этапе этот запрос станет полезной нагрузкой вашего взаимодействия с API Credential Manager.

// 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. Сделайте запрос на цифровые учетные данные с помощью диспетчера учетных данных.

Затем передайте запрос менеджеру по учетным данным.

Для этого необходимо обернуть полезную нагрузку запроса в API-запрос DigitalCredential. Этот запрос должен включать тот же одноразовый код, который вы передали в 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()

После этого вы можете сделать запрос, используя API Credential Manager:

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
}

Если вызов диспетчера учетных данных выполнен успешно, его ответ будет содержать цифровые учетные данные, которые можно извлечь с помощью кода, подобного следующему примеру:

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.

Генерация одноразовых чисел

Эта конечная точка отвечает за генерацию и временное хранение одноразовых значений, называемых одноразовыми значениями (nonce), которые используются для предотвращения атак с повторным воспроизведением на ваши конечные точки. Например, ваш маршрут 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. Значение nonce будет передаваться через различные сетевые вызовы, выполняемые клиентом, и в конечном итоге вернется на ваш сервер в токене Firebase PNV . На следующем шаге вы проверяете, содержит ли токен сгенерированный вами nonce.

Проверка токенов

Эта конечная точка получает токены 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);
    }
});