Guide technique de prise en main pour les opérateurs FPNV

Date de la dernière modification : 10 septembre 2025

Présentation

Ce document décrit toutes les étapes obligatoires pour intégrer un opérateur à la validation du numéro de téléphone Firebase (FPNV) via les validations de numéro de téléphone TS.43.

Terminologie

Parties concernées

• FSC : fournisseur de services de communication
  • Exemple : Opérateurs mobiles
• Agrégateurs
  • Agrégateurs orientés application : agrégateur qui permet aux applications d'effectuer une validation sans que l'application interagisse directement avec l'opérateur.
  • (par exemple, la validation du numéro de téléphone Firebase)
  • Méta-agrégateur : agrégateur qui permet à l'opérateur d'intégrer un agrégateur destiné aux applications
    • Un méta-agrégateur peut être chargé de configurer les serveurs d'autorisation pour les opérateurs et/ou de configurer les détails des serveurs d'autorisation avec les agrégateurs orientés application.
• FPNV : Firebase Phone Number Verification (validation du numéro de téléphone Firebase)
• TAM Google : responsable de compte technique Google qui aide l'opérateur à intégrer FPNV
• Android Telephony : propose des API de numéros de téléphone sur Android, y compris une plate-forme permettant aux opérateurs et aux agrégateurs de fournir des validations TS.43.
• GSMA : association d'opérateurs de réseau mobile qui définit des spécifications, y compris TS.43
• CAMARA : projet Open Source Linux qui définit les API d'opérateur en collaboration avec la GSMA

Conditions de validation

• VNT : validation du numéro de téléphone
• TS.43 : définit le protocole permettant aux clients mobiles et aux serveurs de communiquer avec l'opérateur à l'aide du protocole HTTP.
• EAP-AKA : méthode d'authentification définie dans https://www.rfc-editor.org/rfc/rfc4187, qui ne nécessite pas d'interaction avec l'utilisateur.
• ECS : Entitlement Configuration Server (serveur de configuration des droits)
  • Point d'entrée permettant à l'agrégateur de communiquer avec l'opérateur
• ODSA : On-Device Service Activation (Activation du service sur l'appareil)
  • Fait référence aux différentes opérations fournies par l'ECS pour activer les services sur l'appareil.
  • (par exemple, AcquireTemporaryToken ou GetPhoneNumber).

Serveur de droits d'accès de l'opérateur et point de terminaison PNV

Créer les points de terminaison nécessaires

ACTION1 : le transporteur implémente les points de terminaison suivants, qui sont tous accessibles via Internet. Pour en savoir plus sur l'implémentation, consultez l'Annexe A.

Exigences techniques

Performances générales : le temps d'activité de tous les points de terminaison doit être d'au moins 99,99 %.

Sécurité : pour des raisons de sécurité, les points de terminaison de l'opérateur doivent répondre aux exigences suivantes :

• Jeton d'authentification EAP-AKA : doit expirer dans un délai d'une heure
• Jeton temporaire : à usage unique, il expire au bout de cinq minutes.
• Option 1 : Vanilla TS.43
  • Jeton OAuth : doit expirer dans un délai d'une heure
• Option 2 : CAMARA
  • Jeton d'accès CAMARA : à usage unique, expire au bout de cinq minutes

Qualité des données de l'API : 100 % du contenu des réponses réussies (c'est-à-dire que le MSISDN doit être exact).

FPNV est compatible avec deux variantes de TS.43. La principale différence réside dans la façon dont le serveur FPNV échangera le TempToken avec l'opérateur.

• Vanilla TS.43 : fait référence à l'implémentation telle que prescrite par la spécification TS.43.
• CAMARA : fait référence à l'implémentation prescrite par le flux de porteur JWT de CAMARA.

Option 1 : Implémentation Vanilla TS.43

Demandes depuis un appareil Android

1. Point de terminaison EAP-AKA : renvoie un jeton d'authentification.
2. Point de terminaison AcquireTemporaryToken : renvoie un TempToken à partir du jeton d'authentification.

Demandes du serveur FPNV

1. Point de terminaison OAuth 2.0 : flux d'ID/de code secret du client OAuth : renvoie un jeton d'accès OAuth à partir de l'ID/du code secret du client OAuth
2. Point de terminaison GetPhoneNumber : renvoie le numéro de téléphone correspondant à un jeton d'accès OAuth et à un jeton temporaire.

Option 2 : Implémentation CAMARA

L'implémentation CAMARA est semblable à l'implémentation TS.43 standard, à l'exception des points de terminaison permettant de gérer les requêtes du serveur FPNV.

Demandes depuis un appareil Android

1. Point de terminaison EAP-AKA : renvoie un jeton d'authentification.
2. Point de terminaison AcquireTemporaryToken : renvoie un TempToken à partir d'un jeton d'authentification

Demandes du serveur FPNV

1. Point de terminaison OAuth 2.0 – Flux de support JWT : renvoie un jeton d'accès CAMARA à partir d'un JWT contenant le jeton temporaire.
2. Point de terminaison CAMARA NumberVerification v2 : renvoie le numéro de téléphone correspondant à un jeton d'accès CAMARA donné.

Intégration à la téléphonie Android et à FPNV

Application de test de l'opérateur

ACTION2 : L'opérateur contacte le responsable de compte technique (TAM) Google, qui lui fournit l'application de test FPNV. Cette application de test de l'opérateur imite les requêtes qui seront envoyées par FPNV, sans impliquer le serveur FPNV. Cette application de test des opérateurs permet à l'opérateur de valider le bon fonctionnement de ses points de terminaison.

ACTION3 : L'opérateur vérifie que les points de terminaison ci-dessus fonctionnent de bout en bout à l'aide de l'application de test FPNV.

Configurer les configurations de production nécessaires

Configuration Android : EAP-AKA / AcquireTempToken

ACTION4 : l'opérateur définit sa configuration de production pour ses requêtes EAP-AKA/AcquireTempToken depuis Android Telephony.

• Config :
  • ID d'opérateur canonique Android de cet opérateur
  • Valeurs TS.43 use_cases : use_case=GetPhoneNumber
  • URL du serveur de droits de production pour EAP-AKA/AcquireTempToken
  • SAN et empreinte du certificat x509 de production de Firebase
  • SAN : fpnv.googleapis.com
  • Empreinte : aad068c93399a22fc2b11ab58468e8cb72b8f9fc53700991799a8b764c589c7e

Configuration Firebase : échanger un jeton temporaire contre un numéro de téléphone

ACTION5 : identifiants Firebase permettant de récupérer un jeton OAuth auprès du transporteur

• Vanilla TS.43
  • L'opérateur crée l'ID client et le code secret OAuth pour les requêtes de FPNV. Le transporteur configure ensuite son point de terminaison OAuth pour renvoyer un jeton d'accès pour ces identifiants.
• CAMARA
  • L'équipe TAM de Google fournit la clé publique de Google afin que le point de terminaison OAuth de l'opérateur puisse vérifier que le jeton JWT a été signé par Google.

ACTION6 : L'opérateur définit une configuration de production pour le serveur FPNV afin d'échanger le TempToken contre un téléphone.

• L'ID d'opérateur canonique Android de cet opérateur mobile
• Vanilla TS.43
  • OAuth : flux d'ID/de code secret du client
  • URL du point de terminaison OAuth
  • ID/code secret du client OAuth
  • Habilitation OAuth (le cas échéant)
  • GetPhoneNumber
  • URL du point de terminaison GetPhoneNumber
• CAMARA
  • Schéma de principe du jeton de support JWT OAuth
  • URL du point de terminaison OAuth
  • API NumberVerification v2
  • URL du point de terminaison NumberVerification

Partager des identifiants/configurations

Validation du numéro de téléphone Firebase

ACTION7 : L'opérateur partage sa configuration de production à partir de ACTION4 et ACTION6 avec le responsable technique de compte Google.

• [IMPORTANT] Le code secret OAuth doit être partagé avec Google à l'aide d'un mécanisme sécurisé hors bande (pas d'e-mails, pas de documents, etc.). Ce mécanisme hors bande sera convenu entre l'opérateur et le responsable de compte technique Google.

ACTION8 : Le TAM Google valide le bon fonctionnement de la configuration de bout en bout à l'aide de l'application de test de l'opérateur. Ensuite, il stocke les identifiants OAuth dans un espace de stockage sécurisé Google et met à jour les configurations de FPNV pour échanger le jeton temporaire contre un téléphone (c'est-à-dire les configurations de l'ACTION6).

Téléphonie Android

ACTION9 : L'opérateur suit le document "Google Open Gateway CSP Onboarding" (que le TAM Google partagera avec l'opérateur). L'opérateur ou son TAM Google ouvre un ticket Buganizer pour l'intégration à la configuration de la téléphonie Android : https://issuetracker.google.com/issues/new?component=1861595&template=2168610. Ce bug prendra en compte la configuration de production de ACTION4.

Si un méta-agrégateur configure l'intégration FPNV au nom du transporteur, une déclaration de consentement (e-mail, PDF, lettre, etc.) de la direction du transporteur (niveau Directeur ou supérieur) doit confirmer sa relation commerciale avec ledit opérateur. Le méta-agrégateur peut ensuite fournir la configuration de l'opérateur à Android Telephony au nom de l'opérateur.

Annexe A. Implémentation détaillée

Sensibilité à la casse

• Les en-têtes HTTP ne sont pas sensibles à la casse.
• Toutefois, les formats XML et JSON sont sensibles à la casse. Par conséquent, pour les champs de requête/réponse, assurez-vous qu'ils correspondent exactement à cette documentation.

Étape 1 : EAP-AKA / AcquireTempToken

Points de terminaison : EAP-AKA et AcquireTempToken doivent utiliser le même point de terminaison ECS.

Défi EAP-AKA

Références : TS.43 v12.0 – Section 2.8.1 : "Embedded EAP-AKA Authentication by Entitlement Configuration Server".

Étape 1 d'EAP-AKA : Défi d'authentification

EAP-AKA #1 - GET Request to ECS

Le module de téléphonie Android envoie une requête TS.43 EAP-AKA au serveur d'habilitation de l'opérateur.

En-têtes de requête d'Android

• Accept : application/vnd.gsma.eap-relay.v1.0+json
  • Il s'agit d'un format JSON spécifique à la GSMA, et non à application/json.

Champs de requête Android

• eap_id : consultez l'annexe C de RCC.14.
  • (par exemple, 0<IMSI>@<realm>.mnc<MNC>.mcc<MCC>.3gppnetwork.org)
• GID1 : à spécifier uniquement si la version du droit d'accès est 12.0
• app_name : le nom de l'application encodé aura une valeur hachée MD5 du cas d'utilisation qui effectue la validation du numéro de téléphone :
  • Toutes les requêtes d'agrégateur destinées aux applications auront un nom d'application Google-OGI.
• app : l'ID d'application ap2014 représente les informations sur le numéro de téléphone.
• terminal_vendor/model/sw_version : défini sur une valeur arbitraire. Android ne garantit pas que ces champs contiennent les informations réelles de l'appareil.
• vers : version de la configuration (par exemple, 0 ou 1)
• entitlement_version : Google configure la version des droits d'accès envoyée aux opérateurs en fonction de ce qu'ils demandent.
  • En général, la entitlement_version est de 10.0 ou 12.0.

EAP-AKA #1 - Response from ECS

En-têtes de réponse ECS

• Content-Type : Android s'attend à ce que le type de réponse corresponde à l'en-tête Accept de la requête.
  • (par exemple, application/vnd.gsma.eap-relay.v1.0+json)

Champs de réponse ECS

• eap-relay-packet : contient le package EAP conformément à la section C.2 de RCC.14.

Étape 2 d'EAP-AKA : Obtenir le jeton d'authentification

EAP-AKA #2 - POST Request to ECS

Le module de téléphonie Android renverra ensuite le eap-relay-packet reçu au même point de terminaison.

En-têtes de requête d'Android

• Accept : Android définit deux en-têtes Accept :
  • application/vnd.gsma.eap-relay.v1.0+json : fait référence à l'opérateur qui renvoie à nouveau le JSON si l'appareil doit envoyer une autre requête EAP-AKA.
  • text/vnd.wap.connectivity-xml : fait référence au format réel qu'Android attend du jeton d'authentification EAP-AKA renvoyé par l'opérateur.
• Content-Type : application/vnd.gsma.eap-relay.v1.0+json

Champs de requête Android

• eap-relay-packet : contient le eap-relay-packet de la réponse EAP-AKA précédente, mais au format EAP-Response/AKA-Challenge, conformément à la section 9.2 de la norme RFC 4817.

EAP-AKA #2 - Response from ECS

Une fois l'authentification EAP-AKA réussie, l'opérateur renvoie un jeton d'authentification.

En-têtes de réponse ECS

• Content-Type : Android s'attend à ce que la réponse corresponde à l'en-tête Accept de la requête.
  • Autrement dit, Android s'attend à ce que la réponse avec le jeton d'authentification soit de type text/vnd.wap.connectivity-xml.
  • L'autre en-tête Accept, application/vnd.gsma.eap-relay.v1.0+json, est utilisé si l'opérateur souhaite qu'Android effectue une autre requête EAP-AKA.

Champs de réponse ECS

• TOKEN.token : contient le jeton d'authentification.
• TOKEN.validity : nombre de secondes pendant lesquelles la réponse est valide après que l'appareil l'a reçue.
  • Google vérifiera que le jeton d'authentification répond aux exigences techniques.

AcquireTemporary Token

AcquireTempToken : requête GET envoyée à ECS

À l'aide du jeton d'authentification reçu d'EAP-AKA, le client Android récupère le jeton temporaire en appelant le point de terminaison AcquireTemporaryToken de l'opérateur. La demande

• Exemple : TS.43 v12.0 – Section 6.4.6 – "Exemple de requête AcquireTemporaryToken"
• AcquireTempToken comporte des paramètres semblables à EAP-AKA #1, sauf pour les points suivants :
  • AcquireTempToken spécifie également IMSI, operation et operation_targets.
  • AcquireTempToken ne spécifie pas EAP_ID.

En-têtes de requête d'Android

• Accept : Android définira text/vnd.wap.connectivity-xml

Champs de requête Android

• terminal_vendor/model/sw_version : Android ne garantit pas que ces champs contiennent les informations réelles de l'appareil.
• operation_targets
  • FPNV : l'opération cible est GetPhoneNumber

AcquireTempToken : réponse de l'ECS

Exemple : TS.43 v12.0 – Section 6.6.6 – "Exemple de réponse AcquireTemporaryToken"

En-têtes de réponse ECS

• Content-Type : Android s'attend à ce que le type de réponse corresponde à l'en-tête Accept de la requête.
  • (par exemple, text/vnd.wap.connectivity-xml)

Champs de réponse ECS

• APPLICATION.TemporaryToken : TemporaryToken que le serveur FPNV peut ensuite échanger contre un numéro de téléphone.
• APPLICATION.TemporaryTokenExpiry : heure d'expiration au format AAAA-MM-JJThh:mm:ssTZD
  • Google vérifiera que la date d'expiration de TempToken respecte les exigences techniques.
• APPLICATION.OperationResult : consultez la section 6.5.1 de TS.43 v12.0.
  • Plus précisément, si les opérations sont de type SUCCESS, renvoyez 1.

Étape 2 : Échangez le TempToken contre un numéro de téléphone

Option 1 : Vanilla TS.43

Points de terminaison : les points de terminaison OAuth et GetPhoneNumber peuvent être des serveurs/points de terminaison différents. Ces points de terminaison peuvent également différer du point de terminaison EAP-AKA/AcquireTempToken.

OAuth

Le transporteur doit suivre ce guide OAuth et fournir à Google les informations OAuth nécessaires (ID client, code secret du client, URL du serveur OAuth).

OAuth : requête POST envoyée au serveur d'authentification de l'opérateur

En-têtes de requête FPNV

• Authorization : FPNV définira Basic $BASE64_ENCODED_CREDENTIALS
  • Les identifiants encodés en base64 sont l'encodage en base64 de l'$CLIENT_ID:$CLIENT_SECRET OAuth.
• Content-Type : FPNV définira application/x-www-form-urlencoded
• Accept : FPNV définira application/json

Champs de la demande FPNV

• grant_type : client_credentials

POST HTTP/1.1
Host: $OAUTH_ENDPOINT
Authorization: Basic $BASE64_ENCODED_CREDENTIALS
Content-Type: application/x-www-form-urlencoded
Accept: application/json

grant_type=client_credentials

OAuth : réponse du serveur d'authentification de l'opérateur

En-têtes de réponse de l'opérateur

• Content-Type : FPNV s'attend à ce que le type de réponse corresponde à l'en-tête Accept de la requête.
  • (par exemple, application/json)

Champs de réponse de l'opérateur

• access_token : jeton d'accès OAuth
• token_type : bearer
• expires_in : expiration du jeton d'accès OAuth en secondes.
  • Google validera que le délai d'expiration du jeton OAuth respecte les exigences techniques.

200 OK
Content-Type: application/json

{
  "access_token": $ACCESS_TOKEN,
  "token_type": "bearer",
  "expires_in": $EXPIRATION_IN_SECS,
}

GetPhoneNumber

GetPhoneNumber : requête POST envoyée à ECS

Le serveur de validation Google récupère le numéro de téléphone à l'aide de l'opération GetPhoneNumber.

• Exemple : TS.43 v12.0 – Section 6.4.7 – "GetPhoneNumber Request Example"

En-têtes de requête de FPNV

• Accept : application/json
• Content-Type : application/json

Champs de demande FPNV

• requestor_id : identifie le service appelant l'opération GetPhoneNumber TS.43
  • UUID de validation du numéro de téléphone Firebase : 191fd7cc-f7cd-4bb4-a5d2-455ae1fb9a19
• temporary_token : TemporaryToken de AcquireTempToken
• access_token : jeton OAuth permettant à Google de s'authentifier auprès de l'opérateur
• terminal_vendor/model/sw_version : FPNV remplira ces champs avec des valeurs arbitraires.
• entitlement_version : Google configure la version des droits d'accès envoyée aux opérateurs en fonction de ce qu'ils demandent.
  • En général, la entitlement_version est de 10.0 ou 12.0.
• app : FPNV définira ap2014
• app_name : FPNV définira firebase pour toutes les requêtes FPNV
  • Remarque : AcquireTempToken aura un app_name de Google-OGI, quel que soit l'agrégateur utilisé.
• operation : FPNV définira GetPhoneNumber

GetPhoneNumber : réponse de l'ECS

Exemple : TS.43 v12.0 - Section 6.6.7 - "GetPhoneNumber Response Example"

En-têtes de réponse de l'opérateur

• Content-Type : FPNV s'attend à ce que le type de réponse corresponde à l'en-tête Accept de la requête.
  • (par exemple, application/json)

Champs de réponse de l'opérateur

• ap2014.MSISDN : FPNV s'attend à ce que le numéro de téléphone soit renvoyé au format E164.
  • JSON est sensible à la casse. MSISDN doit donc être en majuscules.

Codes d'erreur TemporaryToken

Références de la section 2.8.6 de la norme TS.43 v12.0.

Le tableau suivant détaille les réponses d'échec que l'ECS est censé renvoyer au serveur de validation Google pour les requêtes GetPhoneNumber :

Option 2 : CAMARA

Points de terminaison : la récupération du jeton d'accès CAMARA et du numéro de téléphone peut s'effectuer sur des serveurs/points de terminaison différents. Ces points de terminaison peuvent également différer du point de terminaison EAP-AKA / AcquireTempToken.

OAuth – Récupérer le jeton d'accès CAMARA

Google n'acceptera que le flux de porteur JWT de CAMARA et non le flux CIBA.

Jeton d'accès CAMARA : requête POST à l'opérateur

Google créera un JWT avec les champs suivants.

• iss : émetteur du JWT (alias ID client)
  • Par exemple, firebase (intégration réelle de FPNV) ou fpnv-carrier-tester-app (application de test de l'opérateur)
• sub : sujet du jeton JWT
  • (par exemple, operatortoken:$TEMP_TOKEN)
• aud : audience, destinataires auxquels le jeton JWT est destiné
  • URL du point de terminaison du jeton (c'est-à-dire l'URL du serveur d'autorisation)
• exp : délai d'expiration en secondes
  • Google enverra une durée d'expiration correspondant à la durée de validité du jeton d'accès CAMARA (voir Exigences techniques).
• iat : heure d'émission en secondes
• jti : identifiant unique permettant d'éviter les attaques par relecture
  • (par exemple, un UUID généré de manière aléatoire)
• scope : objet de la demande
  • (par exemple, dpv:FraudPreventionAndDetection number-verification:device-phone-number:read)

{
  "iss": "firebase",
  "sub": "operatortoken:ey...",
  "aud": $OAUTH_ENDPOINT,
  "exp": $EXPIRATION_TIME_IN_SECS,
  "iat": $ISSUED_AT_TIME_IN_SECS,
  "jti": $RANDOMLY_GENERATED_UUID,
  "scope": "dpv:FraudPreventionAndDetection number-verification:device-phone-number:read"
}

FPNV signera le jeton JWT à l'aide de sa propre clé privée, et le transporteur pourra valider le jeton JWT à l'aide de la clé publique correspondante. FPNV fournira la clé publique à l'aide d'un point de terminaison JWKS. Les opérateurs doivent interroger régulièrement ce point de terminaison JWKS pour obtenir la clé publique (par exemple, une fois par jour), car FPNV alternera les clés publiques à une cadence régulière (par exemple, une fois tous les 30 jours).

En-têtes de requête de FPNV

• Content-Type : application/x-www-form-urlencoded
• Accept : application/json

Champs de demande FPNV

• grant_type : urn:ietf:params:oauth:grant-type:jwt-bearer
• assertion : jeton JWT créé ci-dessus et signé avec la clé privée de FPNV
  • Ce jeton JWT contient notamment le TempToken.

POST /token.oauth2 HTTP/1.1
Host: as.example.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
&assertion=$JWT

Jeton d'accès CAMARA – Réponse de l'opérateur

En-têtes de réponse de l'opérateur

• Content-Type : FPNV s'attend à ce que le type de réponse corresponde à l'en-tête Accept de la requête.
  • (par exemple, application/json)

Champs de réponse de l'opérateur

• access_token : jeton d'accès CAMARA, qui peut ensuite être échangé contre un numéro de téléphone
• token_type : bearer
• expires_in : expiration du jeton d'accès OAuth en secondes.
  • Google validera que le délai d'expiration du jeton OAuth respecte les exigences techniques.
• scope : objet de la demande
  • (par exemple, dpv:FraudPreventionAndDetection number-verification:device-phone-number:read)

200 OK
Content-Type: application/json

{
  "access_token": $CAMARA_ACCESS_TOKEN,
  "token_type": "bearer",
  "expires_in": $EXPIRATION_IN_SECS,
  "scope": "dpv:FraudPreventionAndDetection number-verification:device-phone-number:read"
}

API CAMARA NumberVerification v2

Google échangera ensuite ce jeton d'accès CAMARA en envoyant une requête GET au point de terminaison /device-phone-number de l'opérateur.

CAMARA NumberVerification - GET Request to Carrier

En-têtes de requête de FPNV

• Authorization : Bearer $CAMARA_ACCESS_TOKEN
• Accept : application/json

GET /device-phone-number
Authorization: Bearer $CAMARA_ACCESS_TOKEN
Accept: application/json
Content-Type: application/json

CAMARA NumberVerification - Response from Carrier

En-têtes de réponse de l'opérateur

• Content-Type : FPNV s'attend à ce que le type de réponse corresponde à l'en-tête Accept de la requête.
  • (par exemple, application/json)

Champs de réponse de l'opérateur

• devicePhoneNumber : renvoie le numéro de téléphone au format E164.

200 OK
Content-Type: application/json

{
 "devicePhoneNumber": $PHONE_NUMBER
}