На странице Начало работы с Firebase Phone Number Verification рассказывается, как интегрировать Firebase PNV с помощью метода getVerifiedPhoneNumber(), который обрабатывает весь процесс Firebase PNV – от получения согласия пользователя до выполнения необходимых сетевых вызовов к серверной части Firebase PNV.
Большинству разработчиков рекомендуется использовать API с одним методом (getVerifiedPhoneNumber()). Однако если вам нужен более точный контроль над взаимодействием с Менеджером учетных данных Android, например чтобы запрашивать другие учетные данные вместе с номером телефона, библиотека Firebase PNV также предоставляет два метода, каждый из которых обрабатывает отдельное взаимодействие с серверной частью Firebase PNV:
getDigitalCredentialPayload()получает подписанный сервером запрос, который вы будете использовать для вызова Менеджера учетных данных.exchangeCredentialResponseForPhoneNumber()обменивает ответ от Менеджера учетных данных на подписанный токен, содержащий подтвержденный номер телефона. На этом этапе будет выставлен счет.
Между вызовами этих методов вы должны обрабатывать взаимодействие с API Менеджера учетных данных Android. На этой странице рассказывается, как реализовать этот процесс, состоящий из трех частей.
Подготовка
Настройте проект Firebase и импортируйте зависимости Firebase PNV, как описано на странице Начало работы.
1. Получение полезной нагрузки запроса цифрового удостоверения личности
Вызовите метод getDigitalCredentialPayload(), чтобы сгенерировать запрос номера телефона устройства. На следующем шаге этот запрос будет полезной нагрузкой вашего взаимодействия с Credential Manager API.
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 API. Этот запрос должен содержать тот же одноразовый код, который вы передали в 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()
После этого вы можете сделать запрос с помощью Credential Manager API:
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, ]Срок действия токена не истек.
Токен содержит действительный nonce. Одноразовый код считается действительным, если:
- Вы сгенерировали его (то есть его можно найти в любом механизме сохранения, который вы используете).
- Он не использовался ранее.
- Срок действия не истек.
Например, реализация 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);
}
});