Na stronie Rozpocznij korzystanie z Firebase Phone Number Verification znajdziesz szczegółowe informacje o tym, jak zintegrować Firebase PNV za pomocą metody getVerifiedPhoneNumber(), która obsługuje cały proces Firebase PNV, od uzyskania zgody użytkownika po wykonanie niezbędnych wywołań sieciowych do backendu Firebase PNV.
Większości deweloperów zalecamy korzystanie z interfejsu API z jedną metodą (getVerifiedPhoneNumber()). Jeśli jednak potrzebujesz większej kontroli nad interakcją z Menedżerem danych logowania na Androidzie – na przykład aby poprosić o inne dane logowania wraz z numerem telefonu – biblioteka Firebase PNV udostępnia też te 2 metody, z których każda obsługuje inną interakcję z backendem Firebase PNV:
getDigitalCredentialPayload()otrzymuje żądanie podpisane przez serwer, którego użyjesz do wywołania Menedżera danych logowania.exchangeCredentialResponseForPhoneNumber()wymienia odpowiedź z Credential Managera na podpisany token zawierający zweryfikowany numer telefonu. Na tym etapie nastąpi naliczenie opłat.
Między wywołaniami poszczególnych metod odpowiadasz za obsługę interakcji z interfejsami Credential Manager API na Androidzie. Na tej stronie znajdziesz ogólne informacje o tym, jak wdrożyć ten 3-etapowy proces.
Zanim zaczniesz
Skonfiguruj projekt Firebase i zaimportuj zależności Firebase PNV zgodnie z opisem na stronie Wprowadzenie.
1. Pobieranie ładunku żądania danych logowania w formie cyfrowej
Wywołaj metodę getDigitalCredentialPayload(), aby wygenerować prośbę o numer telefonu urządzenia. W następnym kroku to żądanie będzie ładunkiem interakcji z interfejsem 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. Wysyłanie żądania dotyczącego cyfrowych dokumentów tożsamości za pomocą Menedżera dokumentów tożsamości
Następnie przekaż prośbę do Menedżera danych logowania.
Aby to zrobić, musisz opakować ładunek żądania w żądanie interfejsu DigitalCredential API. To żądanie musi zawierać ten sam ciąg znaków, który został przekazany do funkcji 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()
Gdy to zrobisz, możesz wysłać żądanie za pomocą interfejsu 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
}
Jeśli wywołanie Credential Manager zakończy się powodzeniem, odpowiedź będzie zawierać cyfrowe dane logowania, które możesz wyodrębnić za pomocą kodu podobnego do tego w poniższym przykładzie:
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. Wymień odpowiedź dotyczącą cyfrowych danych logowania na token Firebase PNV
Na koniec wywołaj metodę exchangeCredentialResponseForPhoneNumber(), aby wymienić odpowiedź dotyczącą cyfrowych danych logowania na zweryfikowany numer telefonu i token Firebase PNV:
fpnv.exchangeCredentialResponseForPhoneNumber(dcApiResponse)
.addOnSuccessListener { result ->
val phoneNumber = result.getPhoneNumber()
// Verification successful
}
.addOnFailureListener { e -> /* Handle exchange failure */ }
Ten krok spowoduje naliczenie opłaty po jego pomyślnym zakończeniu i zwróceniu do aplikacji zweryfikowanego numeru telefonu.
4. Weryfikowanie tokena Firebase PNV
Jeśli proces się powiedzie, metoda getVerifiedPhoneNumber() zwróci zweryfikowany numer telefonu i podpisany token, który go zawiera. Możesz używać tych danych w aplikacji zgodnie z dokumentacją w swojej polityce prywatności.
Jeśli używasz zweryfikowanego numeru telefonu poza klientem aplikacji, zamiast samego numeru telefonu przekazuj token, aby móc zweryfikować jego integralność podczas używania. Aby weryfikować tokeny, musisz zaimplementować 2 punkty końcowe:
- Punkt końcowy generowania nonce
- Punkt końcowy weryfikacji tokena
Implementacja tych punktów końcowych zależy od Ciebie. Poniższe przykłady pokazują, jak możesz je zaimplementować za pomocą Node.js i Express.
Generowanie wartości nonce
Ten punkt końcowy odpowiada za generowanie i tymczasowe przechowywanie jednorazowych wartości zwanych nonce, które służą do zapobiegania atakom metodą powtórzenia na Twoje punkty końcowe. Możesz na przykład zdefiniować trasę ekspresową w ten sposób:
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 });
});
Jest to punkt końcowy, który wywoła funkcja zastępcza fetchNonceFromYourServer() z kroku 1. Wartość nonce będzie propagowana w różnych wywołaniach sieciowych wykonywanych przez klienta i ostatecznie trafi z powrotem na Twój serwer w tokenie Firebase PNV. W następnym kroku sprawdzisz, czy token zawiera wygenerowany przez Ciebie nonce.
Weryfikowanie tokenów
Ten punkt końcowy otrzymuje tokeny Firebase PNV od klienta i weryfikuje ich autentyczność. Aby zweryfikować token, musisz sprawdzić:
Nagłówek
typma wartośćJWT.Token jest podpisany jednym z kluczy opublikowanych w punkcie końcowym Firebase PNV JWKS z algorytmem
ES256:https://fpnv.googleapis.com/v1beta/jwksOświadczenia wystawcy zawierają numer Twojego projektu Firebase i mają następujący format:
https://fpnv.googleapis.com/projects/FIREBASE_PROJECT_NUMBERNumer projektu Firebase znajdziesz na stronie Ustawienia projektu w konsoli Firebase.
Roszczenie dotyczące odbiorców to lista zawierająca numer projektu Firebase i identyfikator projektu. Ma ona następujący format:
[ https://fpnv.googleapis.com/projects/FIREBASE_PROJECT_NUMBER, https://fpnv.googleapis.com/projects/FIREBASE_PROJECT_ID, ]Token nie utracił ważności.
Token zawiera prawidłowy jednorazowy kod. Wartość nonce jest prawidłowa, jeśli:
- został wygenerowany przez Ciebie (czyli można go znaleźć w dowolnym mechanizmie utrwalania, którego używasz);
- nie został jeszcze wykorzystany,
- nie utracił ważności,
Implementacja Express może wyglądać na przykład tak:
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);
}
});