Guida tecnica all'onboarding dell'operatore FPNV

Data ultima modifica: 10 settembre 2025

Panoramica

Questo documento descrive tutti i passaggi obbligatori per l'onboarding di un operatore nella verifica del numero di telefono Firebase (FPNV) tramite le verifiche del numero di telefono TS.43.

Terminologia

Parti coinvolte

• CSP: fornitore di servizi di comunicazione
  • Ad es. operatori di telefonia mobile
• Aggregatori
  • Aggregatori rivolti alle app: aggregatore che consente alle app di eseguire una verifica senza che l'app interagisca direttamente con l'operatore
  • ad es. Verifica del numero di telefono Firebase
  • Meta-aggregatore: aggregatore che supporta l'operatore nell'onboarding a un aggregatore rivolto alle app
    • Un meta-aggregatore potrebbe essere responsabile della configurazione dei server di gestione dei diritti per gli operatori e/o della configurazione dei dettagli dei server di gestione dei diritti con gli aggregatori rivolti alle app
• FPNV: Firebase Phone Number Verification
• TAM Google: Technical Account Manager di Google, che aiuta a integrare l'operatore in FPNV
• Android Telephony: offre API per numeri di telefono su Android, inclusa una piattaforma per operatori e aggregatori per fornire verifiche TS.43
• GSMA: associazione di operatori di rete mobile che definiscono le specifiche, tra cui TS.43
• CAMARA: progetto open source Linux che definisce le API degli operatori in collaborazione con la GSMA

Termini di verifica

• PNV: verifica del numero di telefono
• TS.43: definisce il protocollo per la comunicazione tra client mobile e server con l'operatore utilizzando HTTP
• EAP-AKA: metodo di autenticazione definito in https://www.rfc-editor.org/rfc/rfc4187, che non richiede l'interazione con l'utente
• ECS: Entitlement Configuration Server
  • Punto di ingresso per l'aggregatore per comunicare con l'operatore
• ODSA: On-Device Service Activation
  • Si riferisce a diverse operazioni fornite da ECS per attivare i servizi sul dispositivo
  • ad es. AcquireTemporaryToken; GetPhoneNumber

Server di assegnazione dei diritti dell'operatore e endpoint PNV

Creazione degli endpoint necessari

AZIONE1: l'operatore implementa i seguenti endpoint, tutti accessibili tramite internet. Per maggiori dettagli sull'implementazione, consulta l'allegato A.

Requisiti tecnici

Rendimento generale: il tempo di attività di tutti gli endpoint deve essere almeno del 99,99%.

Sicurezza: per motivi di sicurezza, gli endpoint dell'operatore devono soddisfare i seguenti requisiti:

• Token di autenticazione EAP-AKA: deve scadere entro 1 ora
• Token temporaneo: monouso con scadenza di 5 minuti
• Opzione 1: Vanilla TS.43
  • Token OAuth: deve scadere entro 1 ora
• Opzione 2: CAMARA
  • Token di accesso CAMARA: monouso con scadenza di 5 minuti

API Data Quality: 100% dei contenuti delle risposte riuscite (ovvero l'MSISDN deve essere accurato).

FPNV supporta due versioni di TS.43. La principale differenza è il modo in cui il server FPNV scambia il TempToken con l'operatore.

• Vanilla TS.43: si riferisce all'implementazione prescritta dalla specifica TS.43
• CAMARA: si riferisce all'implementazione prescritta dal flusso JWT bearer di CAMARA

Opzione 1: implementazione TS.43 standard

Richieste dal dispositivo Android

1. Endpoint EAP-AKA: restituisce un token di autenticazione
2. Endpoint AcquireTemporaryToken: dato il token di autenticazione, restituisce un TempToken

Richieste dal server FPNV

1. Endpoint OAuth 2.0 - Flusso ID/secret client OAuth: dato l'ID/secret client OAuth, restituisce un token di accesso OAuth
2. Endpoint GetPhoneNumber: dato il token di accesso OAuth e il TempToken, restituisce il numero di telefono corrispondente

Opzione 2: implementazione CAMARA

L'implementazione di CAMARA è simile all'implementazione TS.43 standard, ad eccezione degli endpoint per gestire le richieste dal server FPNV.

Richieste dal dispositivo Android

1. Endpoint EAP-AKA: restituisce un token di autenticazione
2. Endpoint AcquireTemporaryToken: dato un token di autenticazione, restituisce un TempToken

Richieste dal server FPNV

1. Endpoint OAuth 2.0 - Flusso di connessione (bearer) JWT: dato un JWT contenente il TempToken, restituisci un token di accesso CAMARA
2. Endpoint CAMARA NumberVerification v2: dato il token di accesso CAMARA, restituisce il numero di telefono corrispondente

Onboarding su Android Telephony e FPNV

App di test dell'operatore

AZIONE 2: l'operatore contatta il Technical Account Manager (TAM) di Google che condividerà con l'operatore l'app di test dell'operatore FPNV. Questa app di test dell'operatore simula le richieste che verranno inviate da FPNV, senza coinvolgere il server FPNV. Questa app di test dell'operatore è utile per l'operatore per verificare che i suoi endpoint funzionino correttamente.

ACTION3: l'operatore verifica che gli endpoint precedenti funzionino end-to-end utilizzando l'app di test dell'operatore FPNV.

Configurazione delle configurazioni di produzione necessarie

Android Config - EAP-AKA / AcquireTempToken

ACTION4: l'operatore definisce la configurazione di produzione per le richieste EAP-AKA/AcquireTempToken da Android Telephony

• Configurazione:
  • L'ID operatore canonico Android di questo operatore
  • TS.43 use_cases values: use_case=GetPhoneNumber
  • URL del server di assegnazione di produzione per EAP-AKA/AcquireTempToken
  • SAN e impronta digitale del certificato x509 di produzione di Firebase
  • SAN: fpnv.googleapis.com
  • Impronta: aad068c93399a22fc2b11ab58468e8cb72b8f9fc53700991799a8b764c589c7e

Firebase Config - Exchange TempToken for Phone

ACTION5: credenziali Firebase per recuperare un token OAuth dall'operatore

• Vanilla TS.43
  • L'operatore crea l'ID client OAuth e il segreto per le richieste di FPNV. L'operatore configura quindi il proprio endpoint OAuth per restituire un token di accesso per queste credenziali.
• CAMARA
  • Il TAM di Google fornisce la chiave pubblica di Google, in modo che l'endpoint OAuth dell'operatore possa verificare che il JWT sia stato firmato da Google

ACTION6: l'operatore definisce una configurazione di produzione per il server FPNV per scambiare il TempToken con un telefono

• ID operatore canonico Android di questo operatore di rete mobile
• Vanilla TS.43
  • OAuth - Client ID/Secret Flow
  • URL endpoint OAuth
  • ID/secret client OAuth
  • Ambito OAuth (se presente)
  • GetPhoneNumber
  • URL endpoint GetPhoneNumber
• CAMARA
  • OAuth - Flusso di concessione JWT
  • URL endpoint OAuth
  • API NumberVerification v2
  • URL endpoint NumberVerification

Condivisione di credenziali/configurazioni

Verifica del numero di telefono Firebase

AZIONE7: l'operatore condivide la configurazione di produzione di AZIONE4 e AZIONE6 con il Technical Account Manager di Google.

• [IMPORTANTE] Il segreto OAuth deve essere condiviso con Google utilizzando un meccanismo sicuro out-of-band (nessuna email, nessun documento e così via). Questo meccanismo out-of-band verrà concordato dall'operatore e dal TAM di Google.

AZIONE 8: il TAM di Google verifica che la configurazione funzioni end-to-end utilizzando l'app di test dell'operatore. Successivamente, il TAM di Google memorizzerà le credenziali OAuth in un archivio sicuro di Google e aggiornerà le configurazioni di FPNV per scambiare il TempToken con un telefono (ovvero le configurazioni dell'AZIONE 6).

Telefonia Android

AZIONE9: l'operatore segue il documento "Google Open Gateway CSP Onboarding" (che il TAM di Google condividerà con l'operatore). L'operatore o il suo TAM Google presenta un ticket Buganizer per l'onboarding nella configurazione di Android Telephony: https://issuetracker.google.com/issues/new?component=1861595&template=2168610. Questo bug verrà inserito nella configurazione di produzione da ACTION4.

Se un meta-aggregatore configura l'integrazione FPNV per conto dell'operatore, una dichiarazione di consenso (email, PDF, lettera e così via) della leadership dell'operatore (livello Direttore e superiore) deve confermare il rapporto commerciale con l'operatore in questione. Successivamente, il meta-aggregatore può fornire la configurazione dell'operatore per conto dell'operatore a Android Telephony.

Allegato A. Implementazione dettagliata

Sensibilità alle maiuscole

• Le intestazioni HTTP non sono sensibili alle maiuscole
• Tuttavia, i formati XML e JSON sono sensibili alle maiuscole. Pertanto, per i campi di richiesta/risposta, assicurati che corrispondano esattamente a questa documentazione.

Passaggio 1: EAP-AKA / AcquireTempToken

Endpoint: EAP-AKA e AcquireTempToken devono utilizzare lo stesso endpoint ECS.

EAP-AKA Challenge

Riferimenti: TS.43 v12.0 - Sezione 2.8.1 - "Embedded EAP-AKA Authentication by Entitlement Configuration Server".

EAP-AKA Step 1 - Authentication Challenge

EAP-AKA #1 - GET Request to ECS

Il modulo di telefonia Android invia una richiesta EAP-AKA TS.43 al server di autorizzazione dell'operatore.

Intestazioni delle richieste di Android

• Accept: application/vnd.gsma.eap-relay.v1.0+json
  • Si tratta di un formato JSON specifico per la GSMA, non solo application/json

Campi della richiesta di Android

• eap_id: vedi RCC.14 Allegato C
  • ovvero 0<IMSI>@<realm>.mnc<MNC>.mcc<MCC>.3gppnetwork.org
• GID1: specificato solo se la versione del diritto è 12.0
• app_name: AppName codificato avrà un valore hash MD5 del caso d'uso che esegue la verifica del telefono:
  • Tutte le richieste di aggregazione rivolte alle app avranno il nome dell'app Google-OGI
• app: l'ID app ap2014 rappresenta le informazioni sul numero di telefono
• terminal_vendor/model/sw_version: impostato su un valore arbitrario; Android non garantisce che questi campi contengano le informazioni effettive del dispositivo
• vers: versione della configurazione, ad es. 0 o 1
• entitlement_version: Google configurerà la versione dei diritti inviata agli operatori in base a quanto richiesto
  • In genere, il valore di entitlement_version è 10.0 o 12.0

EAP-AKA #1 - Response from ECS

Intestazioni della risposta ECS

• Content-Type: Android prevede che il tipo di risposta corrisponda all'intestazione Accept della richiesta
  • ovvero application/vnd.gsma.eap-relay.v1.0+json

Campi di risposta ECS

• eap-relay-packet: contiene il pacchetto EAP in conformità con RCC.14 - Section C.2

EAP-AKA Step 2 - Get Auth Token

EAP-AKA #2 - POST Request to ECS

Il modulo di telefonia Android invierà quindi l'eap-relay-packet ricevuto allo stesso endpoint.

Intestazioni delle richieste di Android

• Accept: Android imposterà due intestazioni Accept:
  • application/vnd.gsma.eap-relay.v1.0+json: si riferisce all'operatore che restituisce nuovamente JSON se il dispositivo deve inviare di nuovo un'altra richiesta EAP-AKA
  • text/vnd.wap.connectivity-xml: si riferisce al formato effettivo in cui Android si aspetta che l'operatore restituisca il token di autenticazione EAP-AKA
• Content-Type: application/vnd.gsma.eap-relay.v1.0+json

Campi della richiesta di Android

• eap-relay-packet: contiene eap-relay-packet della precedente risposta EAP-AKA, ma nel formato EAP-Response/AKA-Challenge in conformità con la RFC 4817 - Sezione 9.2.

EAP-AKA #2 - Response from ECS

Dopo un'autenticazione EAP-AKA riuscita, l'operatore restituisce un token di autenticazione.

Intestazioni della risposta ECS

• Content-Type: Android prevede che la risposta corrisponda all'intestazione Accept della richiesta
  • ovvero Android prevede che la risposta con il token di autenticazione abbia il tipo text/vnd.wap.connectivity-xml
  • L'altra intestazione Accept, application/vnd.gsma.eap-relay.v1.0+json, viene utilizzata se l'operatore vuole che Android esegua un'altra richiesta EAP-AKA

Campi di risposta ECS

• TOKEN.token: contiene il token di autenticazione
• TOKEN.validity: numero di secondi per cui la risposta è valida dopo che il dispositivo la riceve
  • Google verificherà che il token di autenticazione soddisfi i requisiti tecnici

AcquireTemporary Token

AcquireTempToken - GET Request to ECS

Utilizzando il token di autenticazione ricevuto da EAP-AKA, il client Android recupera il token temporaneo chiamando l'endpoint AcquireTemporaryToken dell'operatore. La richiesta

• Esempio: TS.43 v12.0 - Section 6.4.6 - "AcquireTemporaryToken Request Example"
• AcquireTempToken ha parametri simili a EAP-AKA #1, tranne che:
  • AcquireTempToken specifica anche IMSI, operation e operation_targets
  • AcquireTempToken non specifica EAP_ID

Intestazioni delle richieste di Android

• Accept: Android imposterà text/vnd.wap.connectivity-xml

Campi della richiesta di Android

• terminal_vendor/model/sw_version: Android non garantisce che questi campi contengano le informazioni effettive del dispositivo
• operation_targets
  • FPNV: l'obiettivo dell'operazione è GetPhoneNumber

AcquireTempToken - Response from ECS

Esempio: TS.43 v12.0 - Sezione 6.6.6 - "AcquireTemporaryToken Response Example"

Intestazioni della risposta ECS

• Content-Type: Android prevede che il tipo di risposta corrisponda all'intestazione Accept della richiesta
  • ovvero text/vnd.wap.connectivity-xml

Campi di risposta ECS

• APPLICATION.TemporaryToken: TemporaryToken che il server FPNV può quindi scambiare con un numero di telefono
• APPLICATION.TemporaryTokenExpiry: ora di scadenza nel formato AAAA-MM-GGThh:mm:ssTZD
  • Google verificherà che la scadenza di TempToken soddisfi i requisiti tecnici
• APPLICATION.OperationResult: vedi TS.43 v12.0 - Sezione 6.5.1
  • Nello specifico, se le operazioni sono SUCCESS, restituisci 1

Passaggio 2: scambia TempToken con il numero di telefono

Opzione 1: Vanilla TS.43

Endpoint: gli endpoint OAuth e GetPhoneNumber possono essere server/endpoint diversi tra loro. Questi endpoint possono anche differire dall'endpoint EAP-AKA/AcquireTempToken.

OAuth

L'operatore deve seguire questa guida OAuth e fornire a Google le informazioni OAuth necessarie (ID client, client secret, URL del server OAuth).

OAuth - Richiesta POST al server di autenticazione dell'operatore

Intestazioni delle richieste FPNV

• Authorization: FPNV imposterà Basic $BASE64_ENCODED_CREDENTIALS
  • Le credenziali con codifica Base64 sono la codifica Base64 di OAuth $CLIENT_ID:$CLIENT_SECRET
• Content-Type: FPNV imposterà application/x-www-form-urlencoded
• Accept: FPNV imposterà application/json

Campi della richiesta 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 - Response from Carrier's Auth Server

Intestazioni della risposta dell'operatore

• Content-Type: FPNV prevede che il tipo di risposta corrisponda all'intestazione Accept della richiesta
  • ovvero application/json

Campi di risposta del corriere

• access_token: token di accesso OAuth
• token_type: bearer
• expires_in: scadenza del token di accesso OAuth in secondi
  • Google verificherà che la data di scadenza del token OAuth soddisfi i requisiti tecnici.

200 OK
Content-Type: application/json

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

GetPhoneNumber

GetPhoneNumber - POST Request to ECS

Il server di verifica di Google recupera il numero di telefono utilizzando l'operazione GetPhoneNumber.

• Esempio: TS.43 v12.0 - Sezione 6.4.7 - "GetPhoneNumber Request Example"

Intestazioni delle richieste di FPNV

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

Campi della richiesta di FPNV

• requestor_id: identifica il servizio che chiama l'operazione GetPhoneNumber TS.43
  • Firebase Phone Number Verification UUID: 191fd7cc-f7cd-4bb4-a5d2-455ae1fb9a19
• temporary_token: TemporaryToken da AcquireTempToken
• access_token: token OAuth per l'autenticazione di Google con l'operatore
• terminal_vendor/model/sw_version: FPNV compilerà questi campi con valori arbitrari
• entitlement_version: Google configurerà la versione dei diritti inviata agli operatori in base a quanto richiesto
  • In genere, il valore di entitlement_version è 10.0 o 12.0
• app: FPNV imposterà ap2014
• app_name: FPNV imposterà firebase per tutte le richieste FPNV
  • Nota: AcquireTempToken avrà un app_name di Google-OGI, indipendentemente dall'aggregatore utilizzato
• operation: FPNV imposterà GetPhoneNumber

GetPhoneNumber - Response from ECS

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

Intestazioni della risposta dell'operatore

• Content-Type: FPNV prevede che il tipo di risposta corrisponda all'intestazione Accept della richiesta
  • ovvero application/json

Campi di risposta del corriere

• ap2014.MSISDN: FPNV prevede che il numero di telefono venga restituito nel formato E164
  • JSON è sensibile alle maiuscole, quindi MSISDN deve essere scritto in maiuscolo

Codici di errore TemporaryToken

Riferimenti alla sezione 2.8.6 della TS.43 v12.0.

La tabella seguente descrive in dettaglio le risposte di errore che l'ECS dovrebbe restituire al server di verifica di Google per le richieste GetPhoneNumber:

Opzione 2 - CAMARA

Endpoint: il recupero del token di accesso CAMARA e del numero di telefono possono avvenire su server/endpoint diversi. Questi endpoint possono differire anche dall'endpoint EAP-AKA / AcquireTempToken.

OAuth - Retrieve CAMARA Access Token

Google supporterà solo il flusso di autenticazione JWT di CAMARA e non il flusso CIBA.

Token di accesso CAMARA - Richiesta POST all'operatore

Google creerà un JWT con i seguenti campi.

• iss: emittente del JWT (ovvero ID client)
  • ad es. firebase (integrazione FPNV effettiva) o fpnv-carrier-tester-app (app di test dell'operatore)
• sub: Subject del JWT
  • ovvero operatortoken:$TEMP_TOKEN
• aud: pubblico; destinatari a cui è destinato il JWT
  • URL dell'endpoint del token (ovvero l'URL del server di autorizzazione)
• exp: tempo di scadenza in secondi
  • Google invierà una durata di scadenza che corrisponde al periodo di validità del token di accesso CAMARA (vedi Requisiti tecnici).
• iat: emesso al momento in secondi
• jti: identificatore univoco per evitare attacchi di riproduzione
  • ad es. UUID generato in modo casuale
• scope: scopo della richiesta
  • ovvero 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 firmerà il JWT utilizzando la propria chiave privata e l'operatore può convalidare il JWT utilizzando la chiave pubblica corrispondente. FPNV fornirà la chiave pubblica utilizzando un endpoint JWKS. Gli operatori devono eseguire regolarmente il polling di questo endpoint JWKS per la chiave pubblica (ad es. una volta al giorno), perché FPNV ruoterà le chiavi pubbliche a intervalli regolari (ad es. una volta ogni 30 giorni).

Intestazioni delle richieste di FPNV

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

Campi della richiesta di FPNV

• grant_type: urn:ietf:params:oauth:grant-type:jwt-bearer
• assertion: il JWT creato sopra e firmato con la chiave privata di FPNV
  • In particolare, questo JWT contiene il 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

Token di accesso CAMARA - Risposta dell'operatore

Intestazioni della risposta dell'operatore

• Content-Type: FPNV prevede che il tipo di risposta corrisponda all'intestazione Accept della richiesta
  • ovvero application/json

Campi di risposta del corriere

• access_token: token di accesso CAMARA, che può essere scambiato in un secondo momento con un numero di telefono
• token_type: bearer
• expires_in: scadenza del token di accesso OAuth in secondi
  • Google verificherà che la data di scadenza del token OAuth soddisfi i requisiti tecnici.
• scope: scopo della richiesta
  • ovvero 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 scambierà quindi il token di accesso CAMARA inviando una richiesta GET all'endpoint /device-phone-number dell'operatore.

CAMARA NumberVerification - GET Request to Carrier

Intestazioni delle richieste di 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

Intestazioni della risposta dell'operatore

• Content-Type: FPNV prevede che il tipo di risposta corrisponda all'intestazione Accept della richiesta
  • ovvero application/json

Campi di risposta del corriere

• devicePhoneNumber: restituisce il numero di telefono nel formato E164

200 OK
Content-Type: application/json

{
 "devicePhoneNumber": $PHONE_NUMBER
}