Guía técnica de integración de operadores de FPNV

Fecha de última modificación: 10 de septiembre de 2025

Descripción general

En este documento, se registran todos los pasos obligatorios para incorporar un operador a la verificación de números de teléfono de Firebase (FPNV) a través de las verificaciones de números de teléfono de TS.43.

Terminología

Partes involucradas

• CSP: Proveedor de servicios de comunicación
  • p.ej., operadores de telefonía celular
• Agregadores
  • Agregadores orientados a la app: Agregador que permite que las apps realicen una verificación sin que la app interactúe directamente con el operador
  • p.ej., Verificación del número de teléfono de Firebase
  • Meta-Aggregator: Agregador que ayuda al operador a incorporarse a un agregador orientado a la app
    • Un metaagregador podría encargarse de configurar los servidores de derechos para los operadores o de configurar los detalles de los servidores de derechos con los agregadores orientados a la app.
• FPNV: Verificación de número de teléfono de Firebase
• TAM de Google: Es el administrador técnico de cuentas de Google, que ayuda a incorporar la aerolínea a FPNV.
• Telefonía de Android: Ofrece APIs de números de teléfono en Android, incluida una plataforma para que los operadores y agregadores proporcionen verificaciones de TS.43
• GSMA: Asociación de operadores de redes móviles que definen especificaciones, incluido el TS.43
• CAMARA: Proyecto de código abierto de Linux que define las APIs de operadores en colaboración con la GSMA

Condiciones de Verificación

• PNV: Verificación del número de teléfono
• TS.43: Define el protocolo para que los clientes y servidores móviles se comuniquen con el operador a través de HTTP.
• EAP-AKA: Es el método de autenticación definido en https://www.rfc-editor.org/rfc/rfc4187, que no requiere interacción con el usuario.
• ECS: Servidor de configuración de derechos
  • Punto de entrada para que el agregador se comunique con el operador
• ODSA: Activación de servicio integrado en el dispositivo
  • Se refiere a las diferentes operaciones que proporciona el ECS para activar servicios en el dispositivo.
  • p.ej., AcquireTemporaryToken; GetPhoneNumber

Servidor de derechos del operador y extremo de PNV

Cómo crear los extremos necesarios

ACTION1: El operador implementa los siguientes extremos, a los que se puede acceder a través de Internet. Consulta el Anexo A para obtener más detalles sobre la implementación.

Requisitos técnicos

Rendimiento general: El tiempo de actividad de todos los extremos debe ser de al menos el 99.99%.

Seguridad: Por motivos de seguridad, los endpoints de la empresa de transporte deben satisfacer los siguientes requisitos:

• Token de autorización de EAP-AKA: Debe vencer en un plazo de 1 hora
• Token temporal: Se usa una sola vez y vence en 5 minutos.
• Opción 1: Vanilla TS.43
  • Token de OAuth: Debe vencer en un plazo de 1 hora
• Opción 2: CAMARA
  • Token de acceso de CAMARA: De un solo uso con un vencimiento de 5 minutos

Calidad de los datos de la API: El 100% del contenido de las respuestas exitosas (es decir, el MSISDN debe ser preciso).

La FPNV admite dos variantes de TS.43. La principal diferencia es la forma en que el servidor de FPNV intercambiará el TempToken con el operador.

• TS.43 estándar: Se refiere a la implementación según lo prescrito por la especificación TS.43.
• CAMARA: Se refiere a la implementación según lo prescrito por el flujo de token de portador JWT de CAMARA.

Opción 1: Implementación de TS.43 de Vanilla

Solicitudes desde dispositivos Android

1. Extremo de EAP-AKA: Devuelve un token de autorización
2. Extremo AcquireTemporaryToken: Dado el token de autorización, devuelve un TempToken

Solicitudes del servidor de FPNV

1. Extremo de OAuth 2.0: Flujo de ID/secreto del cliente de OAuth: Dado el ID/secreto del cliente de OAuth, devuelve un token de acceso de OAuth
2. Extremo GetPhoneNumber: Dado el token de acceso de OAuth y el TempToken, devuelve el número de teléfono correspondiente.

Opción 2: Implementación de CAMARA

La implementación de CAMARA es similar a la implementación estándar de TS.43, excepto por los extremos para controlar las solicitudes del servidor de FPNV.

Solicitudes desde dispositivos Android

1. Extremo de EAP-AKA: Devuelve un token de autorización
2. Extremo AcquireTemporaryToken: Dado un token de autorización, devuelve un TempToken

Solicitudes del servidor de FPNV

1. Extremo de OAuth 2.0: Flujo de portador de JWT: Dado un JWT que contiene el TempToken, devuelve un token de acceso de CAMARA.
2. Extremo de NumberVerification v2 de CAMARA: Dado el token de acceso de CAMARA, devuelve el número de teléfono correspondiente.

Incorporación a la telefonía de Android y a la FPNV

App de prueba del operador

ACTION2: El operador se comunica con el administrador técnico de cuentas (TAM) de Google, quien le compartirá la app de prueba del operador de FPNV. Esta app de prueba de operador simula las solicitudes que enviará FPNV, sin involucrar al servidor de FPNV. Esta app de prueba de la empresa de telefonía es útil para que la empresa valide que sus extremos funcionan correctamente.

ACTION3: El operador verifica que los extremos anteriores funcionen de extremo a extremo con la app de prueba del operador de FPNV.

Configura los parámetros de producción necesarios

Android Config: EAP-AKA / AcquireTempToken

ACTION4: El operador define su configuración de producción para sus solicitudes de EAP-AKA/AcquireTempToken desde Android Telephony

• Configuración:
  • ID canónico de empresa de transporte de Android de esta empresa de transporte
  • Valores de TS.43 use_cases: use_case=GetPhoneNumber
  • URL del servidor de derechos de producción para EAP-AKA/AcquireTempToken
  • SAN y huella digital del certificado x509 de producción de Firebase
  • SAN: fpnv.googleapis.com
  • Huella digital: aad068c93399a22fc2b11ab58468e8cb72b8f9fc53700991799a8b764c589c7e

Firebase Config - Exchange TempToken for Phone

ACTION5: Credenciales de Firebase para recuperar un token de OAuth del operador

• Vanilla TS.43
  • El operador crea el ID y el secreto del cliente de OAuth para las solicitudes de FPNV. Luego, la empresa de transporte configura su extremo de OAuth para que devuelva un token de acceso para estas credenciales.
• CAMARA
  • El TAM de Google proporciona la clave pública de Google para que el extremo de OAuth del operador pueda verificar que Google firmó el JWT.

ACTION6: El operador define una configuración de producción para que el servidor de FPNV intercambie el TempToken por un teléfono.

• ID canónico de operador de Android de este OMV
• Vanilla TS.43
  • OAuth: Flujo de ID y secreto del cliente
  • URL del extremo de OAuth
  • ID y secreto del cliente de OAuth
  • Permiso de OAuth (si corresponde)
  • GetPhoneNumber
  • URL del extremo de GetPhoneNumber
• CAMARA
  • OAuth: flujo de portador de JWT
  • URL del extremo de OAuth
  • API de NumberVerification v2
  • URL del extremo de NumberVerification

Compartir credenciales o configuraciones

Verificación del número de teléfono con Firebase

ACTION7: El operador comparte su configuración de producción de ACTION4 y ACTION6 con el administrador de cuentas técnicas de Google.

• [IMPORTANTE] El secreto de OAuth se debe compartir con Google a través de un mecanismo seguro fuera de banda (sin correos electrónicos, sin documentos, etc.). El operador y el TAM de Google acordarán este mecanismo fuera de banda.

ACTION8: El TAM de Google valida que la configuración funcione de extremo a extremo con la app de prueba del operador. Luego, el TAM de Google almacenará las credenciales de OAuth en un almacenamiento seguro de Google y actualizará la configuración de FPNV para intercambiar el TempToken por un teléfono (es decir, la configuración de ACTION6).

Telefonía de Android

ACTION9: El operador sigue el documento "Incorporación del CSP de Google Open Gateway" (que el TAM de Google compartirá con el operador). El operador o su TAM de Google registran un ticket de Buganizer para incorporar la configuración de telefonía de Android: https://issuetracker.google.com/issues/new?component=1861595&template=2168610. Este error tomará la configuración de producción de ACTION4.

Si un metaagregador configura la integración de FPNV en nombre del operador, el liderazgo del operador (nivel de director o superior) debe confirmar su relación comercial con dicho operador a través de una declaración de consentimiento (correo electrónico, PDF, carta, etc.). Luego, el metaagregador puede proporcionar la configuración del operador en nombre de este a la telefonía de Android.

Anexo A Implementación detallada

Distinción entre mayúsculas y minúsculas

• Los encabezados HTTP no distinguen mayúsculas de minúsculas.
• Sin embargo, los formatos XML y JSON distinguen mayúsculas de minúsculas. Por lo tanto, para los campos de solicitud y respuesta, asegúrate de que coincidan exactamente con esta documentación.

Paso 1: EAP-AKA / AcquireTempToken

Extremos: EAP-AKA y AcquireTempToken deben usar el mismo extremo de ECS.

Desafío de EAP-AKA

Referencias: TS.43 v12.0, sección 2.8.1, "Embedded EAP-AKA Authentication by Entitlement Configuration Server".

EAP-AKA, paso 1: Desafío de autenticación

EAP-AKA #1: Solicitud GET a ECS

El módulo de telefonía de Android envía una solicitud de EAP-AKA de TS.43 al servidor de derechos del operador.

Encabezados de solicitud de Android

• Accept: application/vnd.gsma.eap-relay.v1.0+json
  • Es un formato JSON específico de GSMA, no solo application/json

Campos de solicitud de Android

• eap_id: Consulta el Anexo C de RCC.14
  • es decir, 0<IMSI>@<realm>.mnc<MNC>.mcc<MCC>.3gppnetwork.org
• GID1: Solo se especifica si la versión del derecho es 12.0
• app_name: El AppName codificado tendrá un valor hash MD5 del caso de uso que realiza la verificación telefónica:
  • Todas las solicitudes de agregadores orientadas a la app tendrán el nombre de la app Google-OGI.
• app: El ID de la app ap2014 representa la información del número de teléfono.
• terminal_vendor/model/sw_version: Se establece en un valor arbitrario. Android no garantiza que estos campos contengan la información real del dispositivo.
• vers: Versión de la configuración, p.ej., 0 o 1
• entitlement_version: Google configurará la versión del derecho que se envía a los operadores según lo que soliciten.
  • Por lo general, el entitlement_version es 10.0 o 12.0.

EAP-AKA #1: Respuesta de ECS

Encabezados de respuesta de ECS

• Content-Type: Android espera que el tipo de respuesta coincida con el encabezado Accept de la solicitud.
  • es decir, application/vnd.gsma.eap-relay.v1.0+json

Campos de respuesta de ECS

• eap-relay-packet: Contiene el paquete del PAA según RCC.14, sección C.2

EAP-AKA, paso 2: Obtén el token de autorización

EAP-AKA #2: Solicitud POST a ECS

Luego, el módulo de Telefonía de Android enviará el eap-relay-packet recibido al mismo extremo.

Encabezados de solicitud de Android

• Accept: Android establecerá dos encabezados Accept:
  • application/vnd.gsma.eap-relay.v1.0+json: Hace referencia a la empresa de telefonía celular que devuelve JSON si el dispositivo necesita enviar otra solicitud de EAP-AKA.
  • text/vnd.wap.connectivity-xml: Se refiere al formato real que Android espera que el operador devuelva como el token de autenticación de EAP-AKA.
• Content-Type: application/vnd.gsma.eap-relay.v1.0+json

Campos de solicitud de Android

• eap-relay-packet: Contiene el paquete eap-relay-packet de la respuesta EAP-AKA anterior, pero en el formato EAP-Response/AKA-Challenge según el RFC 4817, sección 9.2.

EAP-AKA #2 - Response from ECS

Después de una autenticación EAP-AKA exitosa, el operador devuelve un token de autenticación.

Encabezados de respuesta de ECS

• Content-Type: Android espera que la respuesta coincida con el encabezado Accept de la solicitud.
  • Es decir, Android espera que la respuesta con el token de autorización tenga el tipo text/vnd.wap.connectivity-xml.
  • El otro encabezado Accept, application/vnd.gsma.eap-relay.v1.0+json, se usa si el operador quiere que Android realice otra solicitud de EAP-AKA.

Campos de respuesta de ECS

• TOKEN.token: Contiene el token de autorización.
• TOKEN.validity: Cantidad de segundos durante los que la respuesta es válida después de que el dispositivo recibe la respuesta.
  • Google validará que el token de autorización cumpla con los Requisitos Técnicos.

AcquireTemporary Token

AcquireTempToken: Solicitud GET a ECS

Con el token de autorización recibido de EAP-AKA, el cliente de Android recupera el token temporal llamando al extremo AcquireTemporaryToken del operador. La solicitud

• Ejemplo: TS.43 v12.0 - Sección 6.4.6 - "Ejemplo de solicitud de AcquireTemporaryToken"
• AcquireTempToken tiene parámetros similares a EAP-AKA #1, excepto por lo siguiente:
  • AcquireTempToken también especifica IMSI, operation y operation_targets.
  • AcquireTempToken no especifica EAP_ID

Encabezados de solicitud de Android

• Accept: Android establecerá text/vnd.wap.connectivity-xml

Campos de solicitud de Android

• terminal_vendor/model/sw_version: Android no garantiza que estos campos contengan la información real del dispositivo.
• operation_targets
  • FPNV: El objetivo de la operación es GetPhoneNumber.

AcquireTempToken: Respuesta de ECS

Ejemplo: TS.43 v12.0 - Sección 6.6.6 - "Ejemplo de respuesta de AcquireTemporaryToken"

Encabezados de respuesta de ECS

• Content-Type: Android espera que el tipo de respuesta coincida con el encabezado Accept de la solicitud.
  • es decir, text/vnd.wap.connectivity-xml

Campos de respuesta de ECS

• APPLICATION.TemporaryToken: Es el TemporaryToken que el servidor de FPNV puede intercambiar por un número de teléfono.
• APPLICATION.TemporaryTokenExpiry: Hora de vencimiento en formato AAAA-MM-DDThh:mm:ssTZD
  • Google validará que el vencimiento de TempToken satisfaga los Requisitos Técnicos.
• APPLICATION.OperationResult: Consulta TS.43 v12.0, sección 6.5.1
  • Específicamente, si las operaciones son un SUCCESS, devuelve 1.

Paso 2: Intercambia TempToken por número de teléfono

Opción 1: TS.43 de Vanilla

Extremos: Los extremos de OAuth y GetPhoneNumber pueden ser servidores o extremos diferentes entre sí. Estos extremos también pueden diferir del extremo EAP-AKA/AcquireTempToken.

OAuth

La empresa de transporte debe seguir esta guía de OAuth y proporcionar a Google la información de OAuth necesaria (ID de cliente, secreto de cliente y URL del servidor de OAuth).

OAuth: Solicitud POST al servidor de autenticación de la empresa de transporte

Encabezados de solicitud de FPNV

• Authorization: El FPNV establecerá Basic $BASE64_ENCODED_CREDENTIALS.
  • Las credenciales codificadas en Base64 son la codificación en Base64 de $CLIENT_ID:$CLIENT_SECRET de OAuth.
• Content-Type: El FPNV establecerá application/x-www-form-urlencoded
• Accept: El FPNV establecerá application/json

Campos de solicitud de 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: Respuesta del servidor de autenticación del operador

Encabezados de respuesta del operador

• Content-Type: El FPNV espera que el tipo de respuesta coincida con el encabezado Accept de la solicitud.
  • es decir, application/json

Campos de respuesta del operador

• access_token: Token de acceso de OAuth
• token_type: bearer
• expires_in: Vencimiento del token de acceso de OAuth en segundos
  • Google validará que el tiempo de vencimiento del token de OAuth satisfaga los Requisitos Técnicos.

200 OK
Content-Type: application/json

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

GetPhoneNumber

GetPhoneNumber: Solicitud POST a ECS

El servidor de verificación de Google recupera el número de teléfono con la operación GetPhoneNumber.

• Ejemplo: TS.43 v12.0 - Sección 6.4.7 - "Ejemplo de GetPhoneNumberRequest"

Encabezados de solicitud del FPNV

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

Campos de solicitud de FPNV

• requestor_id: Identifica el servicio que llama a la operación GetPhoneNumber TS.43.
  • UUID de verificación de número de teléfono de Firebase: 191fd7cc-f7cd-4bb4-a5d2-455ae1fb9a19
• temporary_token: TemporaryToken de AcquireTempToken
• access_token: Token de OAuth para que Google se autentique con el operador
• terminal_vendor/model/sw_version: FPNV completará estos campos con valores arbitrarios.
• entitlement_version: Google configurará la versión del derecho que se envía a los operadores según lo que soliciten.
  • Por lo general, el entitlement_version es 10.0 o 12.0.
• app: El FPNV establecerá ap2014
• app_name: FPNV establecerá firebase para todas las solicitudes de FPNV.
  • Nota: AcquireTempToken tendrá un app_name de Google-OGI, independientemente del agregador que se use.
• operation: El FPNV establecerá GetPhoneNumber

GetPhoneNumber: Respuesta de ECS

Ejemplo: TS.43 v12.0 - Sección 6.6.7: "Ejemplo de respuesta de GetPhoneNumber"

Encabezados de respuesta del operador

• Content-Type: El FPNV espera que el tipo de respuesta coincida con el encabezado Accept de la solicitud.
  • es decir, application/json

Campos de respuesta del operador

• ap2014.MSISDN: El FPNV espera que el número de teléfono se devuelva en formato E164.
  • JSON distingue entre mayúsculas y minúsculas, por lo que el MSISDN debe estar en mayúsculas.

Códigos de error de TemporaryToken

Referencias de TS.43 v12.0, sección 2.8.6.

En la siguiente tabla, se detallan las respuestas de error que se espera que el ECS devuelva al servidor de verificación de Google para las solicitudes de GetPhoneNumber:

Opción 2: CAMARA

Extremos: Recuperar el token de acceso de CAMARA y recuperar el número de teléfono pueden ser servidores o extremos diferentes entre sí. Estos extremos también pueden diferir del extremo EAP-AKA o AcquireTempToken.

OAuth: Recupera el token de acceso de CAMARA

Google solo admitirá el flujo de token de portador de JWT de CAMARA y no el flujo de CIBA.

Token de acceso a CAMARA: Solicitud POST al operador

Google creará un JWT con los siguientes campos.

• iss: Emisor del JWT (también conocido como ID de cliente)
  • Es decir, firebase (integración real de FPNV) o fpnv-carrier-tester-app (app de prueba del operador)
• sub: Es el sujeto del JWT.
  • es decir, operatortoken:$TEMP_TOKEN
• aud: Público; destinatarios a los que se dirige el JWT
  • URL del extremo del token (es decir, URL del servidor de autorización)
• exp: Tiempo de vencimiento en segundos
  • Google enviará una duración de vencimiento que coincida con el tiempo durante el que el token de acceso de CAMARA debe ser válido (consulta los Requisitos técnicos).
• iat: Se emitió en el momento en segundos
• jti: Es un identificador único para evitar ataques de repetición.
  • p.ej., UUID generado de forma aleatoria
• scope: Propósito de la solicitud
  • es decir, 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"
}

El FPNV firmará el JWT con su propia clave privada, y el operador podrá validar el JWT con la clave pública correspondiente. El FPNV proporcionará la clave pública a través de un extremo de JWKS. Los operadores deben sondear periódicamente este extremo de JWKS para obtener la clave pública (p.ej., una vez al día), ya que FPNV rotará las claves públicas con una cadencia regular (p.ej., una vez cada 30 días).

Encabezados de solicitud del FPNV

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

Campos de solicitud de FPNV

• grant_type: urn:ietf:params:oauth:grant-type:jwt-bearer
• assertion: El JWT creado anteriormente y firmado con la clave privada de FPNV
  • En particular, este JWT contiene el 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 de acceso de CAMARA: Respuesta del operador

Encabezados de respuesta del operador

• Content-Type: El FPNV espera que el tipo de respuesta coincida con el encabezado Accept de la solicitud.
  • es decir, application/json

Campos de respuesta del operador

• access_token: Token de acceso de CAMARA, que se puede intercambiar más adelante por un número de teléfono
• token_type: bearer
• expires_in: Vencimiento del token de acceso de OAuth en segundos
  • Google validará que el tiempo de vencimiento del token de OAuth satisfaga los Requisitos Técnicos.
• scope: Propósito de la solicitud
  • es decir, 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 de CAMARA NumberVerification v2

Luego, Google intercambiará ese token de acceso de CAMARA enviando una solicitud GET al extremo /device-phone-number del operador.

CAMARA NumberVerification - Solicitud GET al operador

Encabezados de solicitud del 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

Encabezados de respuesta del operador

• Content-Type: El FPNV espera que el tipo de respuesta coincida con el encabezado Accept de la solicitud.
  • es decir, application/json

Campos de respuesta del operador

• devicePhoneNumber: Devuelve el número de teléfono en formato E164.

200 OK
Content-Type: application/json

{
 "devicePhoneNumber": $PHONE_NUMBER
}