Firebase Phone Number Verification is in private preview. If you're a developer interested in trying out this product during the preview phase, fill out this interest form to join the waitlist.

Cette page a été traduite par l'API Cloud Translation.

Personnaliser le flux de validation du numéro de téléphone Firebase sur Android

La page Premiers pas avec Firebase Phone Number Verification explique comment intégrer Firebase PNV à l'aide de la méthode getVerifiedPhoneNumber(), qui gère l'ensemble du flux Firebase PNV, de l'obtention du consentement de l'utilisateur à l'exécution des appels réseau nécessaires au backend Firebase PNV.

L'API à méthode unique (getVerifiedPhoneNumber()) est recommandée pour la plupart des développeurs. Toutefois, si vous avez besoin d'un contrôle plus précis de l'interaction avec le Gestionnaire d'identifiants Android (par exemple, pour demander d'autres identifiants en plus du numéro de téléphone), la bibliothèque Firebase PNV fournit également les deux méthodes suivantes, qui gèrent chacune une interaction différente avec le backend Firebase PNV :

getDigitalCredentialPayload() reçoit une requête signée par le serveur que vous utiliserez pour appeler Credential Manager.
exchangeCredentialResponseForPhoneNumber() échange la réponse du Gestionnaire d'identifiants contre un jeton signé contenant le numéro de téléphone validé.

Entre l'appel de chacune de ces méthodes, vous êtes responsable de la gestion de l'interaction avec les API Credential Manager d'Android. Cette page vous explique comment implémenter ce flux en trois parties.

Avant de commencer

Configurez votre projet Firebase et importez les dépendances Firebase PNV comme décrit sur la page Premiers pas.

1. Obtenir la charge utile de la demande de certification numérique

Appelez la méthode getDigitalCredentialPayload() pour générer une requête pour le numéro de téléphone de l'appareil. À l'étape suivante, cette requête constituera la charge utile de votre interaction avec l'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. Envoyer une demande d'identifiant numérique à l'aide du Gestionnaire d'identifiants

Transmettez ensuite la requête au Gestionnaire d'identifiants.

Pour ce faire, vous devez encapsuler la charge utile de la requête dans une requête de l'API DigitalCredential. Cette requête doit inclure le même nonce que celui que vous avez transmis à 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()

Une fois cela fait, vous pouvez envoyer la requête à l'aide de l'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
}

Si l'appel Credential Manager réussit, sa réponse contient un identifiant numérique que vous pouvez extraire à l'aide d'un code semblable à l'exemple suivant :

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. Échanger la réponse d'identifiant numérique contre un jeton Firebase PNV

Enfin, appelez la méthode exchangeCredentialResponseForPhoneNumber() pour échanger la réponse des identifiants numériques contre le numéro de téléphone validé et un jeton Firebase PNV :

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

4. Vérifier le jeton Firebase PNV

Si le flux réussit, la méthode getVerifiedPhoneNumber() renvoie le numéro de téléphone validé et un jeton signé le contenant. Vous pouvez utiliser ces données dans votre application, comme indiqué dans vos règles de confidentialité.

Si vous utilisez le numéro de téléphone validé en dehors du client de l'application, vous devez transmettre le jeton au lieu du numéro de téléphone lui-même afin de pouvoir vérifier son intégrité lorsque vous l'utilisez. Pour valider les jetons, vous devez implémenter deux points de terminaison :

Point de terminaison de génération de nonce
Point de terminaison de validation des jetons

L'implémentation de ces points de terminaison vous incombe. Les exemples suivants montrent comment les implémenter à l'aide de Node.js et d'Express.

Générer des nonces

Ce point de terminaison est chargé de générer et de stocker temporairement des valeurs à usage unique appelées nonces, qui permettent d'éviter les attaques par rejeu contre vos points de terminaison. Par exemple, vous pouvez définir une route Express comme suit :

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

Il s'agit du point de terminaison que la fonction d'espace réservé, fetchNonceFromYourServer(), appellerait à l'étape 1. Le nonce se propagera à travers les différents appels réseau effectués par le client et finira par revenir à votre serveur dans le jeton Firebase PNV. Dans l'étape suivante, vous allez vérifier que le jeton contient un nonce que vous avez généré.

Valider les jetons

Ce point de terminaison reçoit les jetons Firebase PNV de votre client et vérifie leur authenticité. Pour valider un jeton, vous devez vérifier les éléments suivants :

Le jeton est signé à l'aide de l'une des clés publiées au point de terminaison JWKS Firebase PNV :
```
https://fpnv.googleapis.com/v1beta/jwks
```
Les revendications d'audience et d'émetteur contiennent le numéro de votre projet Firebase et sont au format suivant :
```
https://fpnv.googleapis.com/projects/FIREBASE_PROJECT_NUMBER
```
Vous trouverez le numéro de votre projet Firebase sur la page Paramètres du projet de la console Firebase.
Le jeton n'a pas expiré.
Le jeton contient un nonce valide. Un nonce est valide si :
- Vous l'avez généré (c'est-à-dire qu'il se trouve dans le mécanisme de persistance que vous utilisez).
- Il n'a pas déjà été utilisé.
- Il n'a pas expiré

Par exemple, l'implémentation Express peut se présenter comme suit :

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

Personnaliser le flux de validation du numéro de téléphone Firebase sur Android Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.