Guia técnico de integração de operadoras do FPNV

Data da última modificação: 10 de setembro de 2025

Visão geral

Este documento descreve todas as etapas obrigatórias para integrar uma operadora à Verificação de número de telefone do Firebase (FPNV, na sigla em inglês) usando as verificações de número de telefone TS.43.

Terminologia

Partes envolvidas

• CSP: provedor de serviços de comunicação
  • Por exemplo, "Operadoras de celular"
• Agregadores
  • Agregadores voltados para apps: agregador que permite que os apps façam uma verificação sem interagir diretamente com a operadora.
  • por exemplo, a verificação de número de telefone do Firebase
  • Meta-agregador: agregador que ajuda a operadora a integrar um agregador voltado para apps.
    • Um meta-agregador pode ser responsável por configurar os servidores de direitos para as operadoras e/ou configurar os detalhes dos servidores de direitos com os agregadores voltados ao app.
• FPNV: verificação de número de telefone do Firebase
• TAM do Google: gerente técnico de contas do Google, que ajuda a integrar a operadora ao FPNV.
• Telefonia Android: oferece APIs de número de telefone no Android, incluindo uma plataforma para operadoras e agregadores fornecerem verificações TS.43.
• GSMA: associação de operadoras de redes móveis que definem especificações, incluindo TS.43
• CAMARA: projeto de código aberto do Linux que define APIs de operadora em colaboração com a GSMA.

Termos de verificação

• PNV: verificação do número de telefone
• TS.43: define o protocolo para que clientes e servidores móveis se comuniquem com a operadora usando HTTP.
• EAP-AKA: método de autenticação definido em https://www.rfc-editor.org/rfc/rfc4187, que não exige interação com o usuário
• ECS: servidor de configuração de direitos
  • Ponto de entrada para o agregador conversar com a operadora
• ODSA: ativação de serviço no dispositivo
  • Refere-se a diferentes operações fornecidas pelo ECS para ativar serviços no dispositivo.
  • Por exemplo, "AcquireTemporaryToken" ou "GetPhoneNumber".

Servidor de direitos da operadora e endpoint PNV

Criar os endpoints necessários

ACTION1: a operadora implementa os seguintes endpoints, que são acessíveis pela Internet. Consulte o Anexo A para mais detalhes sobre a implementação.

Requisitos técnicos

Performance geral: o tempo de atividade de todos os endpoints precisa ser de pelo menos 99,99%.

Segurança: por motivos de segurança, os endpoints da operadora precisam atender aos seguintes requisitos:

• Token de autenticação EAP-AKA: precisa expirar em até 1 hora.
• Token temporário: uso único com validade de 5 minutos
• Opção 1: Vanilla TS.43
  • Token OAuth: precisa expirar em até uma hora
• Opção 2: CAMARA
  • Token de acesso da CAMARA: uso único com validade de 5 minutos

Qualidade dos dados da API: 100% do conteúdo das respostas bem-sucedidas (ou seja, o MSISDN precisa ser preciso).

O FPNV é compatível com duas versões do TS.43. A principal diferença é como o servidor FPNV troca o TempToken com a operadora.

• Vanilla TS.43: refere-se à implementação conforme prescrito pela especificação TS.43.
• CAMARA: refere-se à implementação conforme prescrito pelo fluxo de portador JWT da CAMARA.

Opção 1: implementação do TS.43 simples

Solicitações de dispositivos Android

1. Endpoint EAP-AKA: retorna um token de autenticação.
2. Endpoint AcquireTemporaryToken: dado o token de autenticação, retorna um TempToken.

Solicitações do servidor FPNV

1. Endpoint do OAuth 2.0: fluxo de ID/chave secreta do cliente OAuth: dado o ID/chave secreta do cliente OAuth, retorne um token de acesso do OAuth.
2. Endpoint GetPhoneNumber: dado o token de acesso OAuth e o TempToken, retorna o número de telefone correspondente.

Opção 2: implementação da CAMARA

A implementação da CAMARA é semelhante à implementação TS.43 simples, exceto pelos endpoints para processar as solicitações do servidor FPNV.

Solicitações de dispositivos Android

1. Endpoint EAP-AKA: retorna um token de autenticação.
2. Endpoint AcquireTemporaryToken: dado um token de autenticação, retorna um TempToken.

Solicitações do servidor FPNV

1. Endpoint OAuth 2.0: fluxo de portador JWT: dado um JWT que contém o TempToken, retorna um token de acesso do CAMARA.
2. Endpoint NumberVerification v2 da CAMARA: dado o token de acesso da CAMARA, retorne o número de telefone correspondente.

Integração com telefonia Android e FPNV

App de teste da operadora

ACTION2: a operadora entra em contato com o gerente técnico de contas (TAM) do Google, que compartilha o app de teste da operadora FPNV com ela. Esse app de teste da operadora simula as solicitações que serão enviadas pelo FPNV, sem envolver o servidor do FPNV. Esse app de teste é útil para a operadora validar se os endpoints estão funcionando corretamente.

ACTION3: a operadora verifica se os endpoints acima funcionam de ponta a ponta usando o app de teste da operadora FPNV.

Configurar as configurações de produção necessárias

Configuração do Android: EAP-AKA / AcquireTempToken

ACTION4: a operadora define a configuração de produção para as solicitações EAP-AKA/AcquireTempToken da telefonia Android.

• Configuração:
  • O ID canônico da transportadora do Android
  • Valores de TS.43 use_cases: use_case=GetPhoneNumber
  • URL do servidor de direitos de produção para EAP-AKA/AcquireTempToken
  • SAN e impressão digital do certificado x509 de produção do Firebase
  • SAN: fpnv.googleapis.com
  • Impressão digital: aad068c93399a22fc2b11ab58468e8cb72b8f9fc53700991799a8b764c589c7e

Configuração do Firebase: troca de TempToken por telefone

ACTION5: credenciais do Firebase para recuperar um token OAuth da operadora

• Vanilla TS.43
  • A operadora cria o ID e a chave secreta do cliente OAuth para as solicitações do FPNV. A operadora configura o endpoint OAuth para retornar um token de acesso para essas credenciais.
• CAMARA
  • O TAM do Google fornece a chave pública do Google para que o endpoint OAuth da operadora possa verificar se o JWT foi assinado pelo Google.

ACTION6: a operadora define uma configuração de produção para o servidor FPNV trocar o TempToken por um smartphone.

• O ID canônico da operadora do Android dessa OMV
• Vanilla TS.43
  • OAuth: fluxo de ID/chave secreta do cliente
  • URL do endpoint OAuth
  • ID/chave secreta do cliente OAuth
  • Escopo do OAuth (se houver)
  • GetPhoneNumber
  • URL do endpoint GetPhoneNumber
• CAMARA
  • OAuth: fluxo de portador JWT
  • URL do endpoint OAuth
  • API NumberVerification v2
  • URL do endpoint NumberVerification

Compartilhamento de credenciais/configurações

Verificação de número de telefone do Firebase

ACTION7: a operadora compartilha a configuração de produção de ACTION4 e ACTION6 com o gerente técnico de contas do Google.

• [IMPORTANTE] O segredo do OAuth precisa ser compartilhado com o Google usando um mecanismo seguro fora da banda (sem e-mails, sem documentos etc.). Esse mecanismo fora da banda será acordado pela operadora e pelo TAM do Google.

ACTION8: o TAM do Google valida se a configuração funciona de ponta a ponta usando o app de teste da operadora. Depois, o TAM do Google armazena as credenciais OAuth em um armazenamento seguro do Google e atualiza as configurações do FPNV para trocar o TempToken por um smartphone (ou seja, as configurações de ACTION6).

Telefonia Android

ACTION9: a operadora segue o documento "Integração do CSP do Google Open Gateway" (que o TAM do Google vai compartilhar com a operadora). A operadora ou o TAM do Google cria um ticket do Buganizer para integração à configuração da telefonia do Android: https://issuetracker.google.com/issues/new?component=1861595&template=2168610. Esse bug vai usar a configuração de produção de ACTION4.

Se um meta-agregador estiver configurando a integração do FPNV em nome da operadora, uma declaração de consentimento (e-mail, PDF, carta etc.) da liderança da operadora (nível de diretor ou superior) precisará confirmar a relação comercial com o operador em questão. Depois disso, o meta-agregador pode fornecer a configuração da operadora em nome dela para a telefonia do Android.

Anexo A. Implementação detalhada

Diferenciação entre maiúsculas e minúsculas

• Os cabeçalhos HTTP não diferenciam maiúsculas de minúsculas.
• No entanto, os formatos XML e JSON diferenciam maiúsculas de minúsculas. Portanto, para os campos de solicitação/resposta, verifique se eles correspondem exatamente a esta documentação.

Etapa 1: EAP-AKA / AcquireTempToken

Endpoints: EAP-AKA e AcquireTempToken precisam usar o mesmo endpoint do ECS.

Desafio EAP-AKA

Referências: TS.43 v12.0 - Seção 2.8.1 - "Embedded EAP-AKA Authentication by Entitlement Configuration Server".

EAP-AKA Etapa 1: desafio de autenticação

EAP-AKA #1 - GET Request to ECS

O módulo de telefonia do Android envia uma solicitação TS.43 EAP-AKA ao servidor de direitos da operadora.

Cabeçalhos de solicitação do Android

• Accept: application/vnd.gsma.eap-relay.v1.0+json
  • É um formato JSON específico da GSMA, não apenas application/json.

Campos de solicitação do Android

• eap_id: consulte o Anexo C da RCC.14
  • Por exemplo, 0<IMSI>@<realm>.mnc<MNC>.mcc<MCC>.3gppnetwork.org
• GID1: especificado somente se a versão do direito for 12.0
• app_name: o AppName codificado terá um valor de hash MD5 do caso de uso que está realizando a verificação por telefone:
  • Todas as solicitações de agregador voltadas para o app terão o nome Google-OGI.
• app: o ID do app ap2014 representa informações de número de telefone.
• terminal_vendor/model/sw_version: definido como um valor arbitrário. O Android não garante que esses campos contenham as informações reais do dispositivo.
• vers: versão da configuração, por exemplo, 0 ou 1.
• entitlement_version: o Google vai configurar a versão do direito enviada às operadoras com base no que elas solicitam
  • Normalmente, o entitlement_version é 10.0 ou 12.0

EAP-AKA nº 1: resposta do ECS

Cabeçalhos de resposta do ECS

• Content-Type: o Android espera que o tipo de resposta corresponda ao cabeçalho "Accept" da solicitação.
  • Por exemplo, application/vnd.gsma.eap-relay.v1.0+json

Campos de resposta do ECS

• eap-relay-packet: contém o pacote do PAA de acordo com RCC.14 - Seção C.2

Etapa 2 do EAP-AKA: receber o token de autenticação

EAP-AKA nº 2: solicitação POST para ECS

Em seguida, o módulo de telefonia do Android vai enviar o eap-relay-packet recebido para o mesmo endpoint.

Cabeçalhos de solicitação do Android

• Accept: o Android vai definir dois cabeçalhos "Accept":
  • application/vnd.gsma.eap-relay.v1.0+json: refere-se à operadora retornando JSON novamente se o dispositivo precisar enviar outra solicitação EAP-AKA de novo.
  • text/vnd.wap.connectivity-xml: refere-se ao formato real que o Android espera que a operadora retorne o token de autenticação EAP-AKA como
• Content-Type: application/vnd.gsma.eap-relay.v1.0+json

Campos de solicitação do Android

• eap-relay-packet: contém o eap-relay-packet da resposta EAP-AKA anterior, mas no formato EAP-Response/AKA-Challenge, seguindo a RFC 4817, seção 9.2.

EAP-AKA #2: resposta da ECS

Após uma autenticação EAP-AKA bem-sucedida, a operadora retorna um token de autenticação.

Cabeçalhos de resposta do ECS

• Content-Type: o Android espera que a resposta corresponda ao cabeçalho "Accept" da solicitação
  • ou seja, o Android espera que a resposta com o token de autenticação tenha o tipo de text/vnd.wap.connectivity-xml
  • O outro cabeçalho Accept, application/vnd.gsma.eap-relay.v1.0+json, é usado se a operadora quiser que o Android faça outra solicitação EAP-AKA.

Campos de resposta do ECS

• TOKEN.token: contém o token de autenticação.
• TOKEN.validity: número de segundos em que a resposta é válida depois que o dispositivo recebe a resposta
  • O Google vai validar se o token de autenticação atende aos Requisitos técnicos.

AcquireTemporary Token

AcquireTempToken - Solicitação GET para ECS

Usando o token de autenticação recebido do EAP-AKA, o cliente Android busca o token temporário chamando o endpoint AcquireTemporaryToken da operadora. A solicitação

• Exemplo: TS.43 v12.0 - Seção 6.4.6 - "Exemplo de solicitação AcquireTemporaryToken"
• O AcquireTempToken tem parâmetros semelhantes ao EAP-AKA nº 1, exceto:
  • O AcquireTempToken também especifica o IMSI, operation e o operation_targets.
  • O AcquireTempToken não especifica o EAP_ID

Cabeçalhos de solicitação do Android

• Accept: o Android vai definir text/vnd.wap.connectivity-xml

Campos de solicitação do Android

• terminal_vendor/model/sw_version: o Android não garante que esses campos contenham as informações reais do dispositivo.
• operation_targets
  • FPNV: o destino da operação é GetPhoneNumber

AcquireTempToken: resposta do ECS

Exemplo: TS.43 v12.0 - Seção 6.6.6 - "Exemplo de resposta AcquireTemporaryToken"

Cabeçalhos de resposta do ECS

• Content-Type: o Android espera que o tipo de resposta corresponda ao cabeçalho "Accept" da solicitação.
  • Por exemplo, text/vnd.wap.connectivity-xml

Campos de resposta do ECS

• APPLICATION.TemporaryToken: TemporaryToken que o servidor FPNV pode trocar por um número de telefone.
• APPLICATION.TemporaryTokenExpiry: tempo de expiração no formato AAAA-MM-DDThh:mm:ssTZD
  • O Google vai validar se o vencimento do TempToken atende aos Requisitos técnicos.
• APPLICATION.OperationResult: consulte TS.43 v12.0 - Seção 6.5.1
  • Especificamente, se as operações forem um SUCCESS, retorne 1

Etapa 2: trocar TempToken por número de telefone

Opção 1: TS.43 simples

Endpoints: os endpoints OAuth e GetPhoneNumber podem ser servidores/endpoints diferentes entre si. Esses endpoints também podem ser diferentes do endpoint EAP-AKA/AcquireTempToken.

OAuth

A operadora precisa seguir este guia do OAuth e fornecer ao Google as informações necessárias (ID do cliente, chave secreta do cliente e URL do servidor OAuth).

OAuth: solicitação POST para o servidor de autenticação da operadora

Cabeçalhos de solicitação FPNV

• Authorization: o FPNV vai definir Basic $BASE64_ENCODED_CREDENTIALS
  • As credenciais codificadas em base64 são a codificação em base64 do OAuth $CLIENT_ID:$CLIENT_SECRET
• Content-Type: o FPNV vai definir application/x-www-form-urlencoded
• Accept: o FPNV vai definir application/json

Campos de solicitação 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: resposta do servidor de autenticação da operadora

Cabeçalhos de resposta da operadora

• Content-Type: o FPNV espera que o tipo de resposta corresponda ao cabeçalho Accept da solicitação
  • Por exemplo, application/json

Campos de resposta da operadora

• access_token: token de acesso do OAuth
• token_type: bearer
• expires_in: expiração do token de acesso OAuth em segundos
  • O Google vai validar se o tempo de expiração do token OAuth atende aos requisitos técnicos.

200 OK
Content-Type: application/json

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

GetPhoneNumber

GetPhoneNumber: solicitação POST para ECS

O servidor de verificação do Google busca o número de telefone usando a operação GetPhoneNumber.

• Exemplo: TS.43 v12.0 - Section 6.4.7 - "GetPhoneNumber Request Example"

Cabeçalhos de solicitação do FPNV

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

Campos de solicitação do FPNV

• requestor_id: identifica o serviço que chama a operação GetPhoneNumber TS.43.
  • UUID de verificação de número de telefone do Firebase: 191fd7cc-f7cd-4bb4-a5d2-455ae1fb9a19
• temporary_token: TemporaryToken de AcquireTempToken
• access_token: token OAuth para o Google se autenticar com a operadora.
• terminal_vendor/model/sw_version: o FPNV vai preencher esses campos com valores arbitrários.
• entitlement_version: o Google vai configurar a versão do direito enviada às operadoras com base no que elas solicitam
  • Normalmente, o entitlement_version é 10.0 ou 12.0
• app: o FPNV vai definir ap2014
• app_name: o FPNV vai definir firebase para todas as solicitações de FPNV
  • Observação: o AcquireTempToken terá um app_name de Google-OGI, independente de qual agregador for usado.
• operation: o FPNV vai definir GetPhoneNumber

GetPhoneNumber: resposta do ECS

Exemplo: TS.43 v12.0 - Seção 6.6.7 - "Exemplo de resposta GetPhoneNumber"

Cabeçalhos de resposta da operadora

• Content-Type: o FPNV espera que o tipo de resposta corresponda ao cabeçalho Accept da solicitação
  • Por exemplo, application/json

Campos de resposta da operadora

• ap2014.MSISDN: o FPNV espera que o número de telefone seja retornado no formato E164.
  • O JSON diferencia maiúsculas de minúsculas. Portanto, o MSISDN precisa ser escrito em maiúsculas.

Códigos de erro TemporaryToken

Referências de TS.43 v12.0, seção 2.8.6.

A tabela a seguir detalha as respostas de falha que o ECS deve retornar ao servidor de verificação do Google para solicitações GetPhoneNumber:

Opção 2: CAMARA

Endpoints: a recuperação do token de acesso da CAMARA e do número de telefone pode ser feita por servidores/endpoints diferentes. Esses endpoints também podem ser diferentes do endpoint EAP-AKA / AcquireTempToken.

OAuth: recuperar token de acesso da CAMARA

O Google vai oferecer suporte apenas ao fluxo de portador JWT da CAMARA e não ao fluxo CIBA.

Token de acesso da CAMARA: solicitação POST para a operadora

O Google vai criar um JWT com os seguintes campos.

• iss: emissor do JWT (também conhecido como ID do cliente)
  • ou seja, firebase (integração real de FPNV) ou fpnv-carrier-tester-app (app de teste da operadora)
• sub: assunto do JWT
  • Por exemplo, operatortoken:$TEMP_TOKEN
• aud: público-alvo; destinatários a que o JWT se destina
  • URL do endpoint de token (ou seja, URL do servidor de autorização)
• exp: prazo de validade em segundos
  • O Google vai enviar uma duração de expiração que corresponda ao período de validade do token de acesso da CAMARA (consulte Requisitos técnicos).
• iat: emitido no tempo em segundos
• jti: identificador exclusivo para evitar ataques de repetição
  • Por exemplo, UUID gerado aleatoriamente
• scope: finalidade da solicitação
  • Por exemplo, 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"
}

O FPNV vai assinar o JWT usando a própria chave privada, e a operadora poderá validar o JWT usando a chave pública correspondente. O FPNV vai fornecer a chave pública usando um endpoint JWKS. As operadoras precisam consultar regularmente esse endpoint JWKS para a chave pública (por exemplo, uma vez por dia), porque o FPNV faz a rotação das chaves públicas em uma cadência regular (por exemplo, uma vez a cada 30 dias).

Cabeçalhos de solicitação do FPNV

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

Campos de solicitação do FPNV

• grant_type: urn:ietf:params:oauth:grant-type:jwt-bearer
• assertion: o JWT criado acima e assinado com a chave privada do FPNV.
  • Principalmente, esse JWT contém o 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 acesso da CAMARA: resposta da operadora

Cabeçalhos de resposta da operadora

• Content-Type: o FPNV espera que o tipo de resposta corresponda ao cabeçalho Accept da solicitação
  • Por exemplo, application/json

Campos de resposta da operadora

• access_token: token de acesso da CAMARA, que pode ser trocado por um número de telefone
• token_type: bearer
• expires_in: expiração do token de acesso OAuth em segundos
  • O Google vai validar se o tempo de expiração do token OAuth atende aos requisitos técnicos.
• scope: finalidade da solicitação
  • Por exemplo, 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 NumberVerification da CAMARA v2

Em seguida, o Google troca esse token de acesso da CAMARA enviando uma solicitação GET para o endpoint /device-phone-number da operadora.

CAMARA NumberVerification - Solicitação GET para a operadora

Cabeçalhos de solicitação do 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

Cabeçalhos de resposta da operadora

• Content-Type: o FPNV espera que o tipo de resposta corresponda ao cabeçalho Accept da solicitação
  • Por exemplo, application/json

Campos de resposta da operadora

• devicePhoneNumber: retorna o número de telefone no formato E164.

200 OK
Content-Type: application/json

{
 "devicePhoneNumber": $PHONE_NUMBER
}